gem-hunter

OpenClaude is an open-source coding-agent CLI for cloud and local model providers.

Use OpenAI-compatible APIs, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, Atomic Chat, and other supported backends while keeping one terminal-first workflow: prompts, tools, agents, MCP, slash commands, and streaming output.

OpenClaude is also mirrored to Twigpine: gitlawb.com/node/repos/z6MkqDnb/openclaude

Quick Start | Setup Guides | Providers | Development | VS Code Extension | Partners | Community

Twigpine	Bankr.bot	Atomic Chat	Xiaomi MiMo	Atlas Cloud
AI/ML API	Novita AI	ApiSmart	Concentrate	Exa
GMI Cloud

• One CLI across cloud APIs and local model backends — no per-provider tooling
• Guided provider setup and saved profiles with /provider
• Coding-agent workflows in one place: bash, file tools, grep, glob, agents, tasks, MCP, and web tools
• A bundled VS Code extension for launch integration and theme support
• A pixel-art hero companion who fires an arrow every time you press Enter (really — see Meet your buddy)

OpenClaude requires Node.js >=24.22.1 for npm installs and runtime (Node 26 recommended/default). Bun is only needed for source builds and local development.

npm install -g @twigpine/openclaude@latest

Upgrading from @gitlawb/openclaude? The package moved to the @twigpine scope and the old one is no longer updated. Both packages provide the openclaude command, so npm refuses to install one over the other — remove the old one first:

npm uninstall -g @gitlawb/openclaude
npm install -g @twigpine/openclaude@latest

Your settings and sessions (~/.openclaude and ~/.openclaude.json) are not touched. Don't use --force to install over the old package instead: a later uninstall of the old one would then remove the openclaude command. If that happens, uninstall @twigpine/openclaude and install it again.

If you're on Arch Linux, you can install OpenClaude from the community-maintained AUR package:

paru -S openclaude

If the install later reports ripgrep not found, install ripgrep system-wide and confirm rg --version works in the same terminal before starting OpenClaude.

Verify / troubleshoot installed version:

openclaude --version
npm view @twigpine/openclaude dist-tags
npm install -g @twigpine/openclaude@latest

Update-lock recovery: Global updates use .update.lock in the OpenClaude configuration directory (OPENCLAUDE_CONFIG_DIR, or ~/.openclaude). Existing locks are never removed automatically, even when old, to avoid overlapping package-manager installations. If an update was interrupted, first confirm that all OpenClaude update processes and their package-manager children have stopped; then remove only .update.lock from that directory and retry openclaude update. Do not remove the lock while an update is running.

openclaude

Inside OpenClaude:

• run /provider for guided provider setup and saved profiles
• run /onboard-github for GitHub Models onboarding
• run /search to choose the web search backend (Exa by default) or add a search API key

Note: OpenClaude does not automatically load project .env files. We recommend using the /provider command for setup, which saves provider profiles and credentials in .openclaude-profile.json. If you prefer environment variables, export them explicitly or run openclaude --provider-env-file .env for provider/setup variables. Export runtime/debug knobs from your shell or launcher.

Resume an existing conversation by session ID, or continue the most recent conversation in the current directory:

openclaude --resume <session-id>
openclaude --continue

Add --fork-session to branch the conversation history into a new session ID instead of reusing the original transcript:

openclaude --resume <session-id> --fork-session
openclaude --continue --fork-session

Forking is conversation branching only. It does not create filesystem isolation, copy your working tree, or create a git worktree branch.

Run /sessions inside OpenClaude to list this project's saved conversations. Press Enter on one to Resume, Delete (asks for confirmation, defaulting to Cancel), or go Back to the list. As a shortcut, press d on a row and then d again to delete it; any other key in between cancels. Deleting removes the transcript and its sidecar files from disk and cannot be undone. The session you are currently in is not listed and cannot be deleted.

In /resume, type a search query, then press Down and Enter on Search deeply using a background model to search conversation contents with the background search model, which can differ from the active chat model. This explicit action sends transcript excerpts and session metadata to the model provider, including from loaded sessions that do not match the query locally. Ordinary filtering stays local. Deep search considers up to 100 loaded sessions within the active filters, so older history may not be included. Transcript extraction uses up to 100 messages (the first 50 and last 50 for longer sessions), then keeps only the first 2,000 extracted characters. Matches outside that excerpt may be missed. Results remain available as more history loads; changing the query or active filters clears the previous search. If a search fails, the picker shows an error and lets you retry the same query.

Run long non-interactive prompts detached from the current terminal:

openclaude --bg "fix failing tests"
openclaude --bg --name auth-refactor "refactor auth middleware"
openclaude ps
openclaude logs auth-refactor
openclaude logs auth-refactor -f
openclaude kill auth-refactor

Background sessions are local child processes. OpenClaude does not start a daemon or network service, and permission/provider/model/settings flags are passed to the child process the same way they are for a foreground --print run. Session metadata and logs are stored under the resolved OpenClaude config directory, usually ~/.openclaude/bg-sessions/; OPENCLAUDE_CONFIG_DIR can point OpenClaude somewhere else. CLAUDE_CONFIG_DIR is ignored for OpenClaude background-session storage. Session names can be reused after older sessions reach a terminal state; use the session ID to inspect older logs with the same name. A naturally finished session is recorded as exited when its process returns zero and failed when it returns nonzero or handles a termination signal. stale remains the conservative result when the process disappears without an observed outcome; an explicit successful openclaude kill is recorded as killed, and killed takes precedence over a natural exited or failed outcome for the same process. Terminal outcomes are stored separately under bg-sessions/terminal/; deleting that directory makes finished sessions fall back to liveness-derived status. OpenClaude does not infer POSIX signal names on Windows. Unobservable force termination, host crashes, and power loss remain stale on every platform.

openclaude attach <id-or-name> currently reports the matching session and points to openclaude logs <id> -f; full terminal reattach is not implemented for local background sessions yet.

OpenClaude stores its own config under ~/.openclaude and ~/.openclaude.json by default. It does not read ~/.claude, project .claude/ directories, or CLAUDE_CONFIG_DIR; new users can start with an empty OpenClaude config and do not need Claude Code installed.

If you previously used OpenClaude with .claude paths, migrate intentionally: copy only the settings, commands, agents, skills, scheduled tasks, or other files you personally created for OpenClaude into the matching .openclaude location. Do not blanket-copy .claude, and do not copy Claude Code credentials or auth files. For provider authentication, prefer running OpenClaude's provider setup again or exporting provider-specific environment variables.

macOS / Linux:

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

openclaude

Windows PowerShell:

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

openclaude

macOS / Linux:

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

openclaude

Windows PowerShell:

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

openclaude

For Ollama, OpenClaude uses Ollama's native chat API and requests a 32768-token context window on each chat request so same-session history is not silently truncated by Ollama's OpenAI-compatible shim. Set OPENCLAUDE_OLLAMA_NUM_CTX or OLLAMA_CONTEXT_LENGTH if you need a different request-level context size. See Advanced Setup for verification with ollama ps.

Beginner-friendly guides:

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

Advanced and source-build guides:

• Advanced Setup
• Smart Auto-Routing
• Agent Routing and Step Limits
• Headless gRPC Server
• Repo Map (codebase intelligence)
• Skills
• Android Install

• Tool-driven coding workflows: Bash, file read/write/edit, grep, glob, agents, tasks, MCP, and slash commands
• Streaming responses: Real-time token output and tool progress
• Tool calling: Multi-step tool loops with model calls, tool execution, and follow-up responses
• Images: URL and base64 image inputs for providers that support vision. Paste from the clipboard with Ctrl+V (Alt+V on Windows). 1080p/4K screenshots still attach. If processing fails and the image is over the 5MB payload limit or the 8000px API edge, the prompt shows that error instead of "No image found". For Anthropic requests containing more than 20 images (including retained conversation history and tool results), local images must fit within 2000×2000 pixels. On Amazon Bedrock and Google Cloud Vertex AI, document blocks also count toward that 20-block threshold. OpenClaude attempts to resize them before sending; if processing cannot produce a compliant image, it reports an actionable error rather than silently dropping attachments. Resize the affected images or start a new conversation with fewer images (or documents on those partners).
• Provider profiles: Guided setup plus saved user-level provider profile support
• Local and remote model backends: Cloud APIs, local servers, and Apple Silicon local inference
• Codebase intelligence (repo map): Structural map of the repository ranked by PageRank importance, auto-injected into context when the REPO_MAP flag is enabled or the REPO_MAP environment variable is set. Inspect with /repomap (2048-token default). See docs/repo-map.md for details.
• A companion with signature moves: A truecolor pixel-art hero who lives beside your prompt and reacts when you work. See below.

Run /buddy to hatch a companion — a truecolor pixel-art hero who stands beside your prompt, idles, blinks, and fires their signature move every time you submit a message:

/buddy                  hatch (first run) or pet your companion
/buddy set robinhood    the green archer — arrow shot on every Enter
/buddy set kaio         gold-haired warrior — charges a full-width energy wave
/buddy set strawhat     stretchy punch that snaps back
/buddy set merlin       twinkling sparkle stream
/buddy set kage         spinning shuriken
/buddy set ember        dragon fire with a real heat gradient
/buddy set corsair      cannonball with smoke trail
/buddy name Robin       rename your companion
/buddy set random       back to your rolled hero

Companions respect prefersReducedMotion, degrade gracefully to line art in low-color terminals, and can be silenced with /buddy mute. Requires a terminal at least 100 columns wide for the full sprite.

OpenClaude supports multiple providers, but behavior is not identical across all of them.

• Anthropic-specific features may not exist on other providers
• Tool quality depends heavily on the selected model
• Smaller local models can struggle with long multi-step tool flows
• Some providers impose lower output caps than the CLI defaults, and OpenClaude adapts where possible
• AI/ML API uses the OpenAI-compatible route, defaults to gpt-4o, and only surfaces chat-capable models from its public catalog
• Twigpine Opengateway is the fresh-install startup default and requires an API key from https://gitlawb.com/opengateway/keys. It uses one OpenAI-compatible base URL; switch between mimo-* and google/gemini-3.1-flash-lite-preview with /model, and do not pin the base URL to /v1/xiaomi-mimo.
• Z.AI GLM Coding Plan uses https://api.z.ai/api/coding/paas/v4 with glm-5.2 by default. On that direct route, GLM-5.3-Flash is selectable as glm-5.3-flash and accepts image input. Its OpenClaude effort choices are low, high, and xhigh, with xhigh requesting Z.AI max; GLM-5.3 and the existing GLM-5.2 query controls remain supported. These capabilities are not claimed for gateways that happen to carry the same model name.
• Xiaomi MiMo uses api-key header auth on the direct OpenAI-compatible route and currently does not support /usage reporting in OpenClaude
• GitHub Copilot serializes sub-agent execution by default to reduce Premium Request consumption — see Agent Routing and Step Limits for tuning

For best results, use models with strong tool/function calling support.

Route different agents to different models (cost optimization, splitting work by model strength), cap sub-agent tool steps with maxSteps, and tune GitHub Copilot sub-agent behavior. Configured via settings, agent frontmatter, and environment variables:

• per-agent provider/model overrides via agentModels + agentRouting in ~/.openclaude/settings.json
• model-only routes that reuse your current provider's credentials
• built-in agents (Explore and Plan [feature-gated], verification [feature-gated: requires VERIFICATION_AGENT + tengu_hive_evidence], code-reviewer [requires diff inline]) routable by type name

See Agent Routing and Step Limits for the full guide.

Exa is the default web search backend. With no setup, WebSearch on non-Anthropic models uses Exa's keyless free tier, which has per-second and daily limits. Run /search to pick a backend, add an API key, or test search:

/search              # pick a backend
/search key exa      # add an Exa API key (hidden input) for higher limits
/search remove-key   # remove a saved Exa key
/search status       # show which backend handles searches
/search test         # run a test search
/search anysearch    # select AnySearch (works without a key)
/search key anysearch # optionally add an AnySearch API key in the hidden input
/search keenable     # select Keenable (works without a key)
/search key keenable # optionally add a Keenable API key in the hidden input

Other backends in the auto chain that you configure with a key (Tavily, Brave, Firecrawl, …) run before the Exa free tier, and DuckDuckGo is the last-resort fallback. When the active provider is Ollama, OpenClaude uses the signed-in local Ollama Web Search endpoint ahead of the free tier. Set OLLAMA_API_KEY to enable the hosted Ollama endpoint as a fallback. Set EXA_FREE_TIER=0 if searches should never go to Exa without a key. See Web Search Providers for every backend and option.

If you use AI/ML API as your model provider, /search aimlapi (or WEB_SEARCH_PROVIDER=aimlapi) runs searches through the AI/ML API Toolbox web/search tool with your configured AI/ML API credential: AIMLAPI_API_KEY, or OPENAI_API_KEY when OPENAI_BASE_URL is the canonical https://api.aimlapi.com/v1 endpoint. Each search is billed to your AI/ML API balance at a variable price, and every run requests a $0.025 cost limit. It is only used when you select it and never joins the auto order. See Web Search Providers for credential restrictions and request details.

AnySearch is available as an explicit backend with /search anysearch or WEB_SEARCH_PROVIDER=anysearch. ANYSEARCH_API_KEY is optional; anonymous access has lower service limits. Set ANYSEARCH_MAX_RESULTS to an integer from 1 to 10 (default 10) to control the requested result count. AnySearch does not change the auto search order.

Keenable is available as an explicit backend with /search keenable or WEB_SEARCH_PROVIDER=keenable. KEENABLE_API_KEY is optional; keyless access is rate-limited per IP. Keenable does not change the auto search order.

Note: DuckDuckGo fallback works by scraping search results and may be rate-limited, blocked, or subject to DuckDuckGo's Terms of Service.

For Anthropic-native backends and Codex responses, OpenClaude keeps the native provider web search behavior unless you pick a specific backend with /search (for example /search exa).

To select Ollama search explicitly, use WEB_SEARCH_PROVIDER=ollama. A local Ollama route uses its configured OPENAI_BASE_URL or OLLAMA_BASE_URL; hosted search sends OLLAMA_API_KEY only to https://ollama.com/api/web_search.

WebFetch works, but its basic HTTP plus HTML-to-markdown path can still fail on JavaScript-rendered sites or sites that block plain HTTP requests.

Set a Firecrawl API key if you want Firecrawl-powered search/fetch behavior:

export FIRECRAWL_API_KEY=your-key-here

With Firecrawl enabled:

• WebSearch can use Firecrawl's search API while the Exa free tier remains the default free path for non-Claude models
• WebFetch uses Firecrawl's scrape endpoint instead of raw HTTP, handling JS-rendered pages correctly

Free tier at firecrawl.dev includes 500 credits. The key is optional.

WebFetch can also scrape pages through the AI/ML API Toolbox with your AI/ML API key. Each fetched page is one paid Toolbox run (about $0.0013; each run requests a $0.005 cost limit), so it is used only when you choose it:

export AIMLAPI_API_KEY=your-aimlapi-key
export WEB_FETCH_PROVIDER=aimlapi

WEB_FETCH_PROVIDER=aimlapi takes precedence over a Firecrawl key for WebFetch. Having AIMLAPI_API_KEY set without it does not change how pages are fetched. See AI/ML API Setup.

OpenClaude can run as a headless gRPC service with bidirectional streaming — integrate its agentic capabilities into other applications, CI/CD pipelines, or custom UIs. Start it with npm run dev:grpc; a test CLI client ships with the repo. See Headless gRPC Server for configuration and client generation from src/proto/openclaude.proto.

Use Node.js >=24.22.1 (Node 26 recommended/default) and Bun 1.4.4 for source builds.

bun install
bun run build
node dist/cli.mjs

Day-to-day commands:

• bun run dev — build and launch from source
• bun test — full unit suite (Bun's built-in runner)
• bun test path/to/file.test.ts — focused runs for the areas you touch
• bun run test:coverage — coverage to coverage/lcov.info plus a visual report at coverage/index.html (bun run test:coverage:ui rebuilds just the UI)
• bun run smoke — smoke checks
• bun run doctor:runtime, bun run verify:privacy; for PR intent scanning, use the fresh-upstream, explicit-ref workflow in the local pre-push validation contract

Focused suites: bun run test:provider, bun run test:provider-recommendation.

To benchmark the launcher module compile cache, build the CLI and run:

bun run build
bun run benchmark:startup

The benchmark and built OpenClaude launcher require Node >=24.22.1; Node 26 is recommended/default.

The benchmark defaults to 30 separate-process warm runs and 10 isolated empty-cache runs. It reports the median, IQR, MAD, first cache-populating run, first warm-up, Node/OS/CPU details, bundle size, and commit. Direct bundle timings are included only as a secondary diagnostic; the full launcher result is the decision signal. Use bun run benchmark:startup -- --warm-runs 40 --cold-runs 10 to request a larger sample set. The benchmark records results without enforcing a timing threshold in CI.

OpenClaude leaves Node's standard compile-cache controls authoritative. Set NODE_DISABLE_COMPILE_CACHE=1 to disable the optimization, including for V8 coverage runs that require uncached compilation.

Before opening or updating a PR, run the authoritative local pre-push validation contract. The commands below are useful for narrow iteration, but they do not replace that required preflight:

• bun run build
• bun run smoke
• bun run test:coverage when your change affects shared runtime or provider logic
• focused bun test ... runs for the files and flows you changed

• src/ - core CLI/runtime
• scripts/ - build, verification, and maintenance scripts
• docs/ - setup, contributor, and project documentation
• vscode-extension/openclaude-vscode/ - VS Code extension
• .github/ - repo automation, templates, and CI configuration
• bin/ - CLI launcher entrypoints

The repo includes a VS Code extension in vscode-extension/openclaude-vscode for OpenClaude launch integration, provider-aware Control Center, in-editor chat, theme support, and optional Microsoft Foundry / Azure OpenAI configuration (endpoint, API version, deployment, API key via Secret Storage) injected into launched terminals. See that folder's README.

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

• Use GitHub Discussions for Q&A, ideas, and community conversation
• Use GitHub Issues for confirmed bugs and actionable feature work
• Join the Discord to chat with the community in real time
• Follow @twigpine on X for updates and announcements

Contributions are welcome. For larger changes, open an issue first so the scope is clear before implementation. See Development for the build, test, and pre-PR validation commands.

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

OpenClaude 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. See LICENSE for details.

MIT for OpenClaude contributors' modifications; the derived Claude Code remains Anthropic's. See more.