clavis

🔑 Claude Code provider manager. One binary, many backends.

Clavis manages multiple Anthropic-compatible API providers for Claude Code. Store API keys securely, pick a profile, launch. Single static Go binary — no Node, no Python, no runtime.

$ clavis

  Pick a profile:
  > deepseek       DeepSeek (deepseek-chat)
    qwen           Custom (qwen3.7-max)
    work           Anthropic (claude-sonnet-5)

$ clavis deepseek "fix the auth bug"

  clavis deepseek  → deepseek
  model   deepseek-chat
  url     https://api.deepseek.com/anthropic
  config  default ~/.claude (your MCP servers, agents, memory)
  claude  fix the auth bug

Claude Code works with any Anthropic-compatible API — DeepSeek, Z.ai, MiniMax, OpenRouter, Moonshot, Qwen/Alibaba MaaS, and more. But switching between them means juggling env vars in your shell. Keys leak into .zshrc. No validation. No discoverability.

Clavis gives you a structured, secure, keyboard-driven way to manage all your providers — and it keeps your existing Claude Code setup (MCP servers, agents, memory, settings) intact while routing to whichever provider you choose.

• 5-tier model mapping — map provider models to Claude Code's opus / sonnet / haiku / subagent tiers plus the primary ANTHROPIC_MODEL
• Secure key storage — keys in .env files (chmod 0600), never in metadata
• Shares your ~/.claude by default — keep your MCP servers, agents, and memory; opt into an isolated config per-profile or per-launch
• Live model discovery — fetches the provider's real model list during setup
• Key validation — every profile is pinged before it's saved
• Token management — compaction control, effort level, output limits, timeouts
• 3P provider hygiene — auto-disables telemetry, beta headers, and attribution for third-party providers
• Agent-friendly — headless add with flags, --json output, stable exit codes, clavis test for health checks
• Self-updating — clavis update pulls the latest release
• Zero runtime — single static binary for Linux, macOS, and Windows

curl -fsSL https://raw.githubusercontent.com/dinhlongviolin1/clavis/main/install.sh | sh

brew install dinhlongviolin1/tap/clavis

irm https://raw.githubusercontent.com/dinhlongviolin1/clavis/main/install.ps1 | iex

go install github.com/dinhlongviolin1/clavis/cmd/clavis@latest
# or
git clone https://github.com/dinhlongviolin1/clavis.git
cd clavis && make install

Download a build for your OS/arch from the releases page and put the clavis binary on your PATH.

Once installed, keep it current with:

clavis update            # install the latest release
clavis update --check    # just report whether one is available

clavis update also refreshes any shell completions you've installed, so new commands tab-complete after upgrading.

clavis completion install zsh     # or bash / fish

clavis completion uninstall       # remove installed completions (all shells)
rm "$(command -v clavis)"         # remove the binary
rm -rf ~/.clavis                  # optional: remove profiles + saved keys

zsh caches completions in ~/.zcompdump. After removing a completion, run rm -f ~/.zcompdump* && exec zsh so the old entry doesn't linger (otherwise clavis<Tab> may print "function definition file not found"). clavis completion uninstall reminds you of this.

# Create a profile (interactive wizard: pick provider → key → models → review)
clavis add

# Launch with a profile
clavis deepseek

# Forward args to claude
clavis deepseek "explain this codebase"
clavis deepseek -- --dangerously-skip-permissions

# Check a profile is set up and runnable (pings every model tier)
clavis test deepseek

# List profiles
clavis list

Everything after --, or the first flag clavis doesn't recognise, is forwarded verbatim to claude.

Any Anthropic-compatible endpoint works via the Custom provider — just give it the base URL and key.

Clavis is designed to run headlessly under agent runners (Hermes, OpenClaw, cron, CI) with no interactive terminal. Every interactive flow has a flag-driven equivalent; nothing blocks on a prompt.

# Create a profile — key from stdin/env/file so it never lands in `ps`/history.
echo "$DEEPSEEK_KEY" | clavis add --json --key-stdin \
  --provider deepseek --model deepseek-chat \
  --reasoning-model deepseek-reasoner --alias ds --overwrite
# → {"ok":true,"profile":"ds","path":"/home/you/.clavis/profiles/ds"}

clavis get ds --json      # read it back (resolved tiers, key_present, no secret)
clavis test ds --json     # health check: config, key, claude, every model tier
clavis ds -- -p "2+2?"    # launch headless; banner goes to stderr, answer to stdout

Two integration styles:

• Let clavis launch claude: clavis <profile> -- -p "..." — the banner is printed to stderr (auto-suppressed when stdout isn't a TTY, or with --quiet), so stdout carries only claude's answer.
• Own the process yourself: eval "$(clavis env <profile> --reveal-key)" then run your own claude. clavis env prints exactly the vars clavis would set — nothing else touches your environment.

Guarantees for scripting:

• No TTY, no surprise. Interactive commands run without a terminal exit 2 with a clear message — never a silent success.
• Valid JSON always. --json outputs are json.Marshaled; list --json is [] (not null) when empty.
• Stable exit codes: 0 ok · 2 bad/missing flag · 3 provider/base-URL · 4 name exists · 5 validation failed · 6 save failed · 7 not found · 8 claude not installed.
• CLAVIS_HOME overrides the state dir (~/.clavis) for containers/service users.

See clavis add --help for the full flag reference.

Clavis is a launcher, not a proxy. It sets environment variables and spawns claude as a child process:

~/.clavis/
├── profiles/
│   └── deepseek/
│       ├── profile.json    # config pack (no secrets)
│       └── .env            # CLAVIS_KEY=sk-...  (0600)
└── state.json              # last-used profile

At launch, clavis:

1. Reads the profile config + API key.
2. Sets ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, the model tiers, compaction, and hygiene vars.
3. Unsets ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, and other credential vars so nothing from your shell leaks through.
4. Leaves CLAUDE_CONFIG_DIR inherited (shared ~/.claude) unless the profile or launch opts into isolation.
5. Spawns claude with signal forwarding, waits for exit, saves state.

By default a profile shares your real ~/.claude — your MCP servers, subagents, memory, and settings all work exactly as they do normally; clavis just points Claude Code at a different provider/model.

If you'd rather a profile run in a clean, isolated environment (its own CLAUDE_CONFIG_DIR under ~/.clavis/profiles/<name>), enable it:

• in the wizard's advanced step ("Isolate Claude config?"),
• headlessly with clavis add --isolated,
• or per-launch with clavis <name> --isolated (or --shared to override).

Claude Code routes different tasks to different model tiers:

Optional tiers fall back to sonnet if not set. The primary ANTHROPIC_MODEL is set to the sonnet model.

make build      # → bin/clavis
make install    # → ~/.local/bin/clavis
make test       # go test ./...
make lint       # go vet ./...

See CONTRIBUTING.md for the full workflow.

Apache License 2.0 © 2026 Long Nguyen