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

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

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

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

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.