OpenClaude: Open-Source Coding Agent for Cloud and Local Models

OpenClaude is an open-source coding-agent CLI that runs in the terminal and connects one workflow to cloud APIs and local model backends.

The coding agent executes prompts, file operations, and multi-step agent tasks directly from the command line. You can use it to maintain a single coding environment while switching between providers like OpenAI, Gemini, DeepSeek, and local Ollama models.

It supports OpenAI-compatible endpoints, Gemini, GitHub Models, Codex, Ollama, Atomic Chat, and several environment-based enterprise providers. You can run local models on your own hardware or connect to enterprise cloud APIs based on your project requirements.

Features

• Runs Bash commands and reads, writes, edits, searches, and matches files with grep and glob tools.
• Streams token output, tool progress, and permission prompts during execution.
• Executes multi-step tool loops and delegates work to agents and tasks.
• Supports MCP servers, slash commands, and URL or base64 image inputs for vision-capable models.
• Stores provider profiles locally for switching between configured backends.
• Routes named agents to separate models and applies per-agent maxSteps limits.
• Resumes, continues, or forks sessions and runs sessions as local background processes.
• Builds an optional structural Repo Map with REPO_MAP=1 and /repomap.
• Uses DuckDuckGo for non-Anthropic WebSearch and Firecrawl as an optional search and fetch provider.
• Runs a headless bidirectional gRPC server and includes a VS Code extension.

How to Use It

Getting Started

OpenClaude’s npm package requires Node.js 22 LTS or newer. Install Node.js before installing the CLI.

node --version

Install the latest published package globally with npm.

npm install -g @gitlawb/openclaude@latest
openclaude --version

OpenClaude expects ripgrep on the system path for repository search. If the CLI reports that ripgrep is missing, install it and verify the current shell.

rg --version

Start the interactive terminal session, then open the guided provider flow.

openclaude
/provider

For GitHub Models, run the dedicated onboarding command after launch.

/onboard-github

OpenClaude does not load .env files automatically. Use /provider for saved profiles or pass a file explicitly when you need environment-based setup. Keep that file out of Git when it contains credentials.

openclaude --provider-env-file .env

After the provider is ready, start with a repository question that produces a concrete first result.

Explain this project structure and list the files that need attention.

Sessions and Background Work

Resume an earlier conversation, branch it into a new conversation, or run a session in the background from the same CLI.

openclaude --continue
openclaude --resume <session-id>
openclaude --fork-session <session-id>
openclaude --bg
openclaude ps
openclaude logs
openclaude kill

A fork branches the conversation and does not create an isolated filesystem or worktree. Background sessions run as local child processes, not as a daemon or network service.

Provider Setup

Cloud and Local Model Examples

For an OpenAI-compatible cloud route on macOS or Linux, set the provider switch, API key, and model name before starting OpenClaude.

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

PowerShell uses the same variables with PowerShell syntax.

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

For local Ollama inference, start a model and point the OpenAI-compatible route at Ollama’s local server. A cloud API key is not required for this local route.

ollama run llama3.1:8b
export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=llama3.1:8b
openclaude

The PowerShell version uses the same local endpoint.

ollama run llama3.1:8b
$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_BASE_URL="http://localhost:11434/v1"
$env:OPENAI_MODEL="llama3.1:8b"
openclaude

Current Ollama setup requests a 32768-token context by default. Set OPENCLAUDE_OLLAMA_NUM_CTX or OLLAMA_CONTEXT_LENGTH when the model and hardware need a different value.

Available Commands

Environment Variables

When the OpenAI-compatible route is active, a non-local endpoint needs OPENAI_API_KEY or OPENAI_API_KEYS. Check the provider switch, endpoint, credential, and model together when OpenClaude reports that an API key is required.

Agent Routing Example

Agent routing uses ~/.openclaude.json. Define named models in agentModels, then map built-in or custom roles in agentRouting.

{
  "agentModels": {
    "fast-model": {
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-your-key"
    },
    "strong-model": {
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-your-key"
    }
  },
  "agentRouting": {
    "Explore": "fast-model",
    "Plan": "strong-model",
    "verification": "strong-model",
    "default": "strong-model"
  }
}

Keep routing files private because API key values in this configuration are stored as plaintext. Use environment variables where possible and never commit credentials.

Web Tool Behavior

WebSearch uses DuckDuckGo by default with non-Anthropic models. WebFetch uses a basic HTTP and HTML-to-Markdown path unless Firecrawl is configured. JavaScript-heavy or blocked pages can fail with the basic fetcher.

export FIRECRAWL_API_KEY=your-key-here

Headless gRPC Server

The source checkout includes a headless bidirectional gRPC server. It listens on localhost:50051 by default and streams text chunks, tool calls, and permission requests. The repository includes a CLI test client and a Protocol Buffers definition for generating clients in Python, Go, Rust, or another supported language.

npm run dev:grpc
npm run dev:grpc:cli

Source Build

Source builds require Node.js 22 or newer and Bun 1.3.13 or newer. npm installs of the published CLI do not require Bun.

git clone https://github.com/Gitlawb/openclaude.git
cd openclaude
bun install
bun run build
node dist/cli.mjs

Development and verification commands are available from the repository root.

bun run dev
bun test
bun run smoke
bun run doctor:runtime
bun run verify:privacy

Android (Termux)

Android has a separate Termux path. Install Termux from F-Droid, use proot Ubuntu because Bun is not native on Android, then follow the repository’s source-build and provider setup steps. This route is separate from the npm desktop install. Check the OpenClaude on Android (Termux) guide’s current prerequisites before starting.

Pros

• One terminal workflow for cloud and local providers.
• Guided /provider setup with saved profiles.
• Per-agent models and maxSteps limits.
• Resume, fork, and background session commands.
• Optional Repo Map for structural code context.
• Headless gRPC streaming and a VS Code extension.

Cons

• npm installs require Node.js 22 LTS or newer.
• Cloud routes require provider credentials and billing.
• Local routes depend on available hardware and a running model server.
• Routing files can contain plaintext API keys.
• DuckDuckGo can be rate-limited or blocked.
• Android requires the separate Termux and Ubuntu path.

FAQ

Why does OpenClaude say that an OpenAI API key is required?

That message appears when the OpenAI-compatible route is active and the target endpoint is treated as a cloud service. Set OPENAI_API_KEY or OPENAI_API_KEYS with CLAUDE_CODE_USE_OPENAI=1, then confirm that OPENAI_BASE_URL points to the intended API. Local Ollama, LM Studio, and Atomic Chat routes do not need a cloud API key.

How do I configure OpenClaude?

Start openclaude and run /provider. Select a hosted or local provider, enter its credentials or endpoint, choose a model, and save the profile. Use /onboard-github for GitHub Models.

Does OpenClaude load a .env file automatically?

No. Pass the file explicitly with openclaude --provider-env-file .env or use /provider to save a profile. Keep credentials outside your repository.

Alternatives & Related Resources

• 7 Best CLI AI Coding Agents (Open Source)
• CodeWhale (DeepSeek TUI): Free, Open-source Claude Code Alternative
• OpenWork: Free Open-Source Claude Cowork Alternative
• OpenScience: AI Workbench for Scientific Research (Claude Science Alternative)
• OpenTag: Free Open-Source Claude Tag Alternative for Slack
• Aperant (Auto Claude): Open-Source AI Coding Agent Harness
• The Ultimate Claude Code Resource List: Agents, Skills, Plugins & More

Last Updated: Aug 02, 2026