OpenCow Agent SDK

OpenCow Agent SDK is an open-source coding agent toolkit with two entrypoints:

• CLI: opencow
• SDK: @opencow-ai/opencow-agent-sdk

Use one workflow across OpenAI-compatible APIs, Gemini, GitHub Models, Codex, Ollama, Atomic Chat, and other supported backends, with tools, agents, MCP, and streaming responses.

Table of Contents

• Why OpenCow Agent SDK
• Choose Your Path
• Requirements
• CLI Quick Start
• SDK Quick Start
• SDK API Status
• Supported Providers
• Core Capabilities
• Web Search and Fetch
• Setup Guides
• Build From Source
• Testing and Validation
• Repository Structure
• VS Code Extension
• Contributing
• Security
• Community
• Disclaimer
• License

Why OpenCow Agent SDK

• One project for both terminal users and SDK builders
• Unified model/provider surface across cloud APIs and local inference
• Tool-first coding workflows: bash, file editing, grep/glob, agents, tasks, MCP
• Streaming responses and multi-turn tool execution loops
• In-process MCP server support for embedding custom tools in SDK integrations

Choose Your Path

If you want a ready-to-use coding agent in terminal:

npm install -g @opencow-ai/opencow-agent-sdk
opencow

If you want to embed OpenCow in your JS/TS app:

npm install @opencow-ai/opencow-agent-sdk

Requirements

• Node.js >= 20
• ripgrep (rg) available on PATH for full CLI experience
• Bun is recommended for local development in this repository

CLI Quick Start

Install

npm install -g @opencow-ai/opencow-agent-sdk

Start

opencow

Inside OpenCow:

• run /provider for guided provider setup and saved profiles
• run /onboard-github for GitHub Models onboarding

Fast OpenAI setup

macOS / Linux:

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-your-key-here
export OPENAI_MODEL=gpt-4o

opencow

Windows PowerShell:

$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_API_KEY="sk-your-key-here"
$env:OPENAI_MODEL="gpt-4o"

opencow

Fast local Ollama setup

macOS / Linux:

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=qwen2.5-coder:7b

opencow

Windows PowerShell:

$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_BASE_URL="http://localhost:11434/v1"
$env:OPENAI_MODEL="qwen2.5-coder:7b"

opencow

SDK Quick Start

Install

npm install @opencow-ai/opencow-agent-sdk

Minimal query example

import { query } from '@opencow-ai/opencow-agent-sdk'

const stream = query({
  prompt: 'List files in the current directory.',
  options: {
    cwd: process.cwd(),
    model: 'gpt-4o',
    maxTurns: 3,
  },
})

for await (const message of stream) {
  if (message.type === 'assistant' || message.type === 'result') {
    console.log(message)
  }
}

Use SDK MCP tools in-process

npm install zod

import { createSdkMcpServer, query, tool } from '@opencow-ai/opencow-agent-sdk'
import { z } from 'zod/v4'

const echoTool = tool(
  'echo',
  'Echo text back',
  { text: z.string() },
  async ({ text }) => ({
    content: [{ type: 'text', text }],
  }),
)

const mcpServer = createSdkMcpServer({
  name: 'local-tools',
  tools: [echoTool],
})

const stream = query({
  prompt: 'Call the echo tool with text = hello from sdk',
  options: {
    mcpServers: {
      local: mcpServer,
    },
  },
})

for await (const message of stream) {
  console.log(message)
}

SDK API Status

Current SDK implementation status in this repository version:

| API | Status | Notes | | --- | --- | --- | | query | Available | Primary async streaming interface | | tool | Available | Build SDK MCP tool definitions | | createSdkMcpServer | Available | In-process MCP transport | | unstable_v2_createSession | Not implemented | Throws not implemented | | unstable_v2_resumeSession | Not implemented | Throws not implemented | | unstable_v2_prompt | Not implemented | Throws not implemented | | getSessionMessages | Not implemented | Throws not implemented | | listSessions | Not implemented | Throws not implemented | | getSessionInfo | Not implemented | Throws not implemented | | renameSession | Not implemented | Throws not implemented | | tagSession | Not implemented | Throws not implemented | | forkSession | Not implemented | Throws not implemented |

Supported Providers

| Provider | Setup Path | Notes | | --- | --- | --- | | OpenAI-compatible | /provider or env vars | Works with OpenAI, OpenRouter, DeepSeek, Groq, Mistral, LM Studio, and other compatible /v1 servers | | Gemini | /provider or env vars | Supports API key, access token, or local ADC workflow | | GitHub Models | /onboard-github | Interactive onboarding with saved credentials | | Codex | /provider | Uses existing Codex credentials when available | | Ollama | /provider or env vars | Local inference with no API key | | Atomic Chat | advanced setup | Local Apple Silicon backend | | Bedrock / Vertex / Foundry | env vars | Additional provider integrations for supported environments |

Core Capabilities

• Tool-driven coding workflows (bash, file tools, grep, glob, tasks, agents, MCP)
• Streaming responses with tool-progress feedback
• Multi-step tool calling loops
• Provider profiles with saved .opencow-profile.json
• URL/base64 image inputs for providers that support vision
• Local and remote model backend support

Web Search and Fetch

WebSearch supports a non-Anthropic fallback path using DuckDuckGo for compatible models.

WebFetch is available, but plain HTTP + HTML parsing may fail on JS-heavy or protected sites.

For stronger reliability, configure Firecrawl:

export FIRECRAWL_API_KEY=your-key-here

With Firecrawl enabled:

• WebSearch can use Firecrawl search APIs
• WebFetch uses Firecrawl scraping for better JS-rendered page handling

Setup Guides

Beginner-friendly guides:

• Non-Technical Setup
• Windows Quick Start
• macOS / Linux Quick Start

Advanced guides:

• Advanced Setup
• Android Install

Build From Source

bun install
bun run build

Run CLI from source build:

node dist/cli.mjs

Build output highlights:

• dist/cli.mjs - CLI entrypoint
• dist/sdk.js - SDK runtime export
• dist/sdk.d.ts - SDK public typings
• dist/entrypoints/agentSdkTypes.d.ts - expanded SDK API types

Create local npm tarball:

npm pack

Testing and Validation

Run core checks:

bun run build
bun run smoke
bun test

Coverage:

bun run test:coverage

Additional checks:

• bun run doctor:runtime
• bun run verify:privacy
• bun run security:pr-scan -- --base origin/main
• focused bun test path/to/file.test.ts

Repository Structure

• src/ - core CLI/runtime and SDK entrypoints
• scripts/ - build, validation, and maintenance scripts
• docs/ - setup and project documentation
• python/ - standalone Python helpers and tests
• .github/ - CI workflows and issue/PR templates
• bin/ - CLI launcher entrypoints

Contributing

Contributions are welcome.

Before large changes, open an issue to align scope and approach.

Please review:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md

Security

If you believe you found a security issue, see SECURITY.md.

Community

• Use GitHub Discussions for Q&A and ideas
• Use GitHub Issues for confirmed bugs and actionable feature requests

Disclaimer

OpenCow is an independent community project and is not affiliated with, endorsed by, or sponsored by Anthropic.

OpenCow originated from the Claude Code codebase and has since been substantially modified to support multiple providers and open use. "Claude" and "Claude Code" are trademarks of Anthropic PBC.

License

Licensed under Apache License 2.0. See LICENSE.