npm package: @opencow-ai/opencow-agent-sdk
Description: Claude Code opened to any LLM — OpenAI, Gemini, DeepSeek, Ollama, and 200+ models
Latest version: 0.1.8

# 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.

[![PR Checks](https://github.com/OpenCowAI/opencow-agent-sdk/actions/workflows/pr-checks.yml/badge.svg?branch=main)](https://github.com/OpenCowAI/opencow-agent-sdk/actions/workflows/pr-checks.yml)
[![Release](https://img.shields.io/github/v/tag/OpenCowAI/opencow-agent-sdk?label=release&color=0ea5e9)](https://github.com/OpenCowAI/opencow-agent-sdk/tags)
[![Discussions](https://img.shields.io/badge/discussions-open-7c3aed)](https://github.com/OpenCowAI/opencow-agent-sdk/discussions)
[![Security Policy](https://img.shields.io/badge/security-policy-0f766e)](SECURITY.md)
[![License](https://img.shields.io/badge/license-Apache%202.0-2563eb)](LICENSE)

## Table of Contents

- [Why OpenCow Agent SDK](#why-opencow-agent-sdk)
- [Choose Your Path](#choose-your-path)
- [Requirements](#requirements)
- [CLI Quick Start](#cli-quick-start)
- [SDK Quick Start](#sdk-quick-start)
- [SDK API Status](#sdk-api-status)
- [Supported Providers](#supported-providers)
- [Core Capabilities](#core-capabilities)
- [Web Search and Fetch](#web-search-and-fetch)
- [Setup Guides](#setup-guides)
- [Build From Source](#build-from-source)
- [Testing and Validation](#testing-and-validation)
- [Repository Structure](#repository-structure)
- [VS Code Extension](#vs-code-extension)
- [Contributing](#contributing)
- [Security](#security)
- [Community](#community)
- [Disclaimer](#disclaimer)
- [License](#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:

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

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

```bash
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

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

### Start

```bash
opencow
```

Inside OpenCow:

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

### Fast OpenAI setup

macOS / Linux:

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

opencow
```

Windows PowerShell:

```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:

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

opencow
```

Windows PowerShell:

```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

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

### Minimal query example

```ts
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

```bash
npm install zod
```

```ts
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:

```bash
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](docs/non-technical-setup.md)
- [Windows Quick Start](docs/quick-start-windows.md)
- [macOS / Linux Quick Start](docs/quick-start-mac-linux.md)

Advanced guides:

- [Advanced Setup](docs/advanced-setup.md)
- [Android Install](ANDROID_INSTALL.md)

## Build From Source

```bash
bun install
bun run build
```

Run CLI from source build:

```bash
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:

```bash
npm pack
```

## Testing and Validation

Run core checks:

```bash
bun run build
bun run smoke
bun test
```

Coverage:

```bash
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
- `vscode-extension/opencow-vscode/` - VS Code extension
- `.github/` - CI workflows and issue/PR templates
- `bin/` - CLI launcher entrypoints

## VS Code Extension

This repository includes a VS Code extension in [`vscode-extension/opencow-vscode`](vscode-extension/opencow-vscode) for OpenCow launch integration, provider-aware control-center UI, and theme support.

## Contributing

Contributions are welcome.

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

Please review:

- [CONTRIBUTING.md](CONTRIBUTING.md)
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)

## Security

If you believe you found a security issue, see [SECURITY.md](SECURITY.md).

## Community

- Use [GitHub Discussions](https://github.com/OpenCowAI/opencow-agent-sdk/discussions) for Q&A and ideas
- Use [GitHub Issues](https://github.com/OpenCowAI/opencow-agent-sdk/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](LICENSE).