openclaude-improved

OpenClaude — Improved Version

runs anywhere. uses anything.

An open-source coding agent for the CLI. Cloud APIs, gateways, and local models — same tools, same agents, same workflow.

Install · Quick start · Providers · Sessions · Config · Docs

Install

Built from source. Windows examples below; macOS and Linux are identical minus the shell syntax.

Prerequisites — Node >=22 (enforced by engines.node) and Bun.

node --version
bun --version

No Bun? winget install Oven-sh.Bun or bun.sh.

Build and link

cd openclaude-main
bun install
bun run build
npm install -g .
openclaude

That's it — openclaude is now on your PATH.

Quick start

Run /provider inside OpenClaude for guided setup with saved profiles — this is the recommended path. Credentials land in .openclaude-profile.json.

Prefer env vars? Pick one:

$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_API_KEY="sk-..."
$env:OPENAI_MODEL="gpt-4o"
openclaude

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

OpenClaude talks to Ollama's native chat API and requests a 32768-token window per request, so same-session history isn't silently trimmed by the OpenAI-compat shim. Override with OPENCLAUDE_OLLAMA_NUM_CTX or OLLAMA_CONTEXT_LENGTH.

Run /onboard-github inside OpenClaude. Interactive, credentials saved.

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-...
export OPENAI_MODEL=gpt-4o
openclaude

Project .env files are not auto-loaded. Use --provider-env-file .env for provider vars, or export runtime knobs from your shell.

Providers

Gotchas worth knowing

• Anthropic-only features don't exist on every backend. Tool quality tracks model quality — small local models struggle with long multi-step tool loops.
• Some providers cap output below CLI defaults; OpenClaude adapts where it can.
• Opengateway uses one base URL — switch models with /model, don't pin the URL to /v1/xiaomi-mimo.
• GLM reasoning: glm-5.2?reasoning=high, ?reasoning=xhigh, or ?thinking=disabled.
• MiMo uses api-key header auth and has no /usage reporting yet.
• GitHub Copilot serializes sub-agents by default to save Premium Requests — see agent routing.

What you get

Sessions

openclaude --continue                             # most recent, this directory
openclaude --resume <session-id>
openclaude --resume <session-id> --fork-session   # branch history, new ID

Forking branches conversation history only — no worktree, no filesystem isolation.

openclaude --bg "fix failing tests"
openclaude --bg --name auth-refactor "refactor auth middleware"

openclaude ps
openclaude logs auth-refactor -f
openclaude kill auth-refactor

Plain local child processes — no daemon, no network service. Metadata and logs live in ~/.openclaude/bg-sessions/. Names are reusable once a session is terminal; use the ID to reach older logs sharing a name. attach currently just points you at logs <id> -f.

Config

OpenClaude owns ~/.openclaude/ and ~/.openclaude.json. It does not read ~/.claude, project .claude/ directories, or CLAUDE_CONFIG_DIR. Fresh installs start empty and don't need Claude Code present.

Migrating from a .claude-era setup? Copy only files you wrote — settings, commands, agents, skills, scheduled tasks — into the matching .openclaude path. Don't blanket-copy, and don't move credentials; re-run provider setup instead.

OPENCLAUDE_CONFIG_DIR relocates everything.

Buddy

/buddy hatches a truecolor pixel-art companion that stands beside your prompt and fires its signature move on every Enter.

/buddy set robinhood    green archer — arrow shot
/buddy set kaio         full-width energy wave
/buddy set strawhat     stretchy snap-back punch
/buddy set merlin       sparkle stream
/buddy set kage         spinning shuriken
/buddy set ember        dragon fire, real heat gradient
/buddy set corsair      cannonball with smoke trail

Respects prefersReducedMotion, degrades to line art on low-color terminals, /buddy mute silences it. Needs ~100 columns for the full sprite.

Development

bun run dev        # build and launch from source
bun test           # full suite

Before opening a PR:

bun run build
bun run smoke
bun test path/to/changed.test.ts
bun run test:coverage          # if you touched shared runtime or provider logic

bun run test:coverage:ui                        # rebuild HTML report only
bun run test:provider
bun run test:provider-recommendation
bun run doctor:runtime
bun run verify:privacy
bun run security:pr-scan -- --base origin/main

src/                                   core CLI and runtime
scripts/                               build, verify, maintenance
docs/                                  setup and contributor docs
bin/                                   launcher entrypoints
vscode-extension/openclaude-vscode/    VS Code extension

Coverage lands at coverage/lcov.info plus a browsable report at coverage/index.html.

If startup reports ripgrep not found, install ripgrep system-wide and confirm rg --version resolves in the same shell.

Docs

Getting started — Non-technical · Windows · macOS / Linux · Android

Going deeper — Advanced setup · Smart auto-routing · Agent routing · Repo map · gRPC server

Contributing

Open an issue first for anything large, so scope is settled before code. Bugs and actionable feature work go to Issues; questions and ideas to Discussions. Security reports: SECURITY.md.

MIT for contributor modifications; derived Claude Code code remains Anthropic's — see LICENSE.

An independent