One alias per account. Shared history, memory, plugins, settings, and sessions across all of them. Plus turn any LLM API key into a Claude Code alias, share your whole plugin ecosystem with OpenCode, and auto-name a per-project session on every launch.
Quick start Β· Features Β· Commands Β· Guides Β· How it works
Running more than one Claude Code account on a machine normally means siloed worlds: each account has its own conversation history, project memory, todos, plans, and installed plugins, and nothing carries over. Claude Toolkit collapses that into one shared store β every account is mostly symlinks into it β so switching accounts is just a shell alias, and your work, memory, and plugins follow you. Only the things that must stay private (credentials, auth state) remain per-account.
claude1 # account 1 β your shared projects, memory, plugins, sessions
claude2 # account 2 β the SAME shared projects, memory, plugins, sessions
deepseek # the same ecosystem, running on DeepSeek's best model
kimi1 # Kimi Code account 1 β the same shared store, Kimi's OAuth subscription
kimi-deepseek # Kimi Code on the SAME deepseek backend the no-prefix alias uses- π Unified multi-account store. One alias per account (
claude1,claude2, β¦ or custom names). A single~/.claude-shared/holdsprojects/,todos/,tasks/,plans/,history.jsonl,settings.json,plugins/,CLAUDE.mdand more; each account dir is symlinks into it. - β»οΈ Cross-account session resume. The
projects/session index in.claude.jsonis deep-merged across accounts on every launch β a session started underclaude1shows up inclaude2's--resumelist, and vice versa. Auth keys never cross. - π·οΈ Per-project auto-session naming. Every bare alias launch resumes β or
first-time creates β one long-lived session per project root, named after
the directory in
kebab-case(Android 15βandroid-15). Openclaude2in a project and you're back in the same ongoing work, properly named β even if the session was previously unnamed. (Color: a deterministic per-alias/colorhint is printed; Claude Code's/coloris TUI-only and can't be auto-applied β see SESSION_COLOR.md.) - π Any LLM as a Claude Code alias.
claude-providersturns every API key in your keys file into its own alias pointed at that provider's strongest model β fully dynamic (no hardcoded providers/URLs/models), secrets never leave the keys file. Provider guide β - π€ Kimi Code CLI support.
kimi1,kimi2, β¦ accounts with their own OAuth subscriptions, unified like Claude's; plus akimi-<id>alias for every provider backend that opens Kimi Code on the same key. Kimi guide β - π Share your ecosystem with OpenCode.
claude-opencode-syncexposes every Claude plugin's Skills + MCP servers +CLAUDE.mdto a host-installed OpenCode in one command. OpenCode guide β - πͺ TOON encoding utility.
toon.mjs/toon_encode.pyencode JSON to TOON (~40% fewer tokens for structured prompt data). TOON guide β - π§ Jev decision layer. A shadow-first, fail-open permission gate backed by TypeSafe's Jev decision models (local llmctl gateway, LAN pins, OpenRouter, or TypeSafe hosted) β never a chat alias, always a lightweight allow/ask/deny signal wired into every agent launch. Jev guide β
- π§± Constitution hub engine. claude_toolkit is a hub engine of the
Helix constitution: consumed by reference at
constitution/submodules/claude_toolkit, depth 1, never initialised recursively, and it resolves its own dependencies (constitution, containers, challenges, LLMsVerifier, claude-code-router) withscripts/resolve_deps.shinstead of nesting them (Constitution Β§11.4.28(C) / Β§11.4.31). Hub-engine section β - β
llmctl validation gate + Vision QA. Local-model aliases run through
llmctl's known-answer validation gate (Constitution Β§11.4.277:
LLMCTL_VALIDATE_STRICT=1,llmctl require-validated <profile>), the gate Vision QA (Β§11.4.278) depends on. llmctl guide β - π Safe & reversible. Every destructive step is backed up;
claude-rollbackrestores everything. Idempotent installers. Verified on Linux and macOS.
curl -fsSL https://raw.githubusercontent.com/vasic-digital/claude-toolkit/main/scripts/curl-install.sh | bashClones to ~/claude-toolkit (or pulls if present), installs missing
dependencies via your system package manager, runs the full setup, and wires the
aliases into your shell. Re-run anytime to update.
Then open a new shell and:
claude-list-accounts # see what's wired up
claude1 # launch account 1 (auto-resumes this project's session)Optional β the Jev decision layer (permission gating via System-One decision
models, local-first via the llmctl :8095 gateway):
claude-providers sync # detect Jev endpoints into the ranked cache
jev-setup # install gate/hooks/MCP per agent (shadow mode default)
claude1 # "Jev decision layer: ACTIVE (β¦)" MOTD on launch
jev-stats # decisions, calibration, ESTIMATED tokens savedFull walkthrough: docs/jev/Jev_Quickstart.md.
Manual install
A. Host already has β₯1 ~/.claude-* account:
git clone https://github.com/vasic-digital/claude-toolkit.git claude-toolkit
cd claude-toolkit
bash scripts/install.sh # symlink scripts onto PATH, write managed alias
# file, source from rc files, unify existing
# accounts, install the TOON dep, refresh docs.
exec $SHELL -l
claude-list-accountsB. Clean-slate host (Claude Code installed, no accounts yet):
git clone https://github.com/vasic-digital/claude-toolkit.git claude-toolkit
cd claude-toolkit
bash scripts/claude-bootstrap.sh --count 2 --yes # provision claude1, claude2
exec $SHELL -l
claude1 /login && claude2 /login # authenticate each once--aliases personal,work for custom names; --dir-of NAME=PATH to override a
config dir. Both installers are idempotent.
| Command | Purpose |
|---|---|
claude-list-accounts |
Tabular status: alias, config dir, creds, link health. |
claude-add-account |
Add an account. Interactive, or --alias NAME --dir PATH --yes. |
claude-remove-account --alias NAME |
Drop an alias; archive (default) or --delete its dir. |
claude-unify |
Re-merge state into the shared store (auto-detects ~/.claude-*). |
claude-sync-state |
Fast jq sync of the .claude.json session index across accounts. Runs automatically around every launch. |
claude-sync-plugins |
Propagate the plugins / MCP servers you DISABLED in one alias (default claude1) to every alias, so they stop costing tokens. capture, --dry-run, --apply, --verify, --status. See Curated plugin set. |
claude-session |
Per-project session helper (name/id/color/flags) used by the alias wrappers. See SESSION_COLOR.md. |
claude-bootstrap |
Clean-slate provisioning on a fresh host. |
claude-providers |
Create/refresh aliases for other LLM providers from your keys file. |
claude-providers quota / limits |
Report usage/limit windows for every native account and provider alias. See Provider_Aliases_User_Guide.md#14-quota-and-limits-reporting-quota--limits. |
kimi-add-account |
Add a Kimi Code account (~/.kimi-code-<name>); --login drives the interactive device flow. |
kimi-list-accounts |
Tabular status of detected Kimi accounts. |
kimi-unify |
Re-merge Kimi state into $SHARED_DIR/kimi/. |
kimi-remove-account |
Drop a Kimi account; archive (default) or --delete its dir. |
kimi-rollback |
Restore .preunify.* backups for the Kimi family. |
kimi-providers |
Kimi framing over claude-providers (sync|list|show|verify|migrate-names). |
kimi-providers quota / limits |
Same usage/limit report, reached via kimi-providers' catch-all forward. See Provider_Aliases_User_Guide.md#14-quota-and-limits-reporting-quota--limits. |
claude-usage report |
Token/cost usage report built on the real ccusage binary (day/model/session/project/provider breakdowns; default last 4 weeks; json/md/csv, written under $SHARED_DIR/usage-reports/ by default). Native accounts are pooled (cannot be told apart) and "provider" is a best-effort catalog cross-reference β see claude-usage --help for the exact honesty contract. Auto-refreshed after every claude-providers sync/sync --multi (CMA_SYNC_SKIP_USAGE_REFRESH=1 to opt out), not just on demand. |
claude-usage merge |
Combines claude-usage report JSON files from one or more source paths (--from PATH[,PATH...], each a directory of *.json reports or a single file) into one consolidated report, re-summing any day/model/project/provider rows that key together. By default every project path is stripped to the placeholder "coding agents" (rows that collide after stripping are summed into one, not just relabeled) β --anonymize-as NAME picks a different label, --real-names opts out and keeps real paths distinct. |
claude-opencode-sync |
Expose Claude plugin Skills + MCP + CLAUDE.md to OpenCode. |
claude-export-docs |
Regenerate the long-form guide .html/.pdf from markdown. |
claude-rollback |
Restore .preunify.* backups and move the shared store aside. |
claude-providers sync-jev |
Jev-only fast path: re-probe decision endpoints and refresh the ranked jev-endpoints.json cache. |
jev-setup |
Install/audit (--check) the Jev decision layer per agent (hooks, MCP, plugin); edits agent homes only with consent (--yes / JEV_SETUP_CONSENT=1, backups first); --mode shadow|enforce (read by the gate, the launch wrappers and the OpenCode plugin: process env > ~/.config/jev/env > shadow), --key-file PATH (record where the gateway bearer key lives; nothing is copied), --uninstall. |
jev-stats |
Decision-layer report from decisions.jsonl: verdicts, latency, shadow calibration, ESTIMATED tokens saved. --days N, --json. |
jev-spec-setup <repo> |
Opt-in: install jev-spec CI templates (config + PR-verify workflow) into a target repo. |
| Guide | What it covers |
|---|---|
| User Manual (start here) | One index over every guide, FAQ, diagram and verification doc below, with the hub-engine, validation-gate and decision-model entry points. |
| Provider Aliases User Guide | Turning LLM keys into aliases; transports, overrides, verification. |
| llmctl Integration Quickstart β User Guide β FAQ | Auto-recognizing local llmctl models as aliases; on-demand switching; honest context/LAN warnings; flow diagrams. |
| Kimi Accounts User Guide | Kimi Code accounts, kimi-<id> aliases, the one-time kimi-* β kc-* rename. |
| Jev Quickstart β User Guide β FAQ | The Jev decision layer: endpoint detection, the shadow-first permission gate, MCP server, per-agent installer, stats/calibration; architecture diagram. |
| OpenCode Integration | Sharing Skills + MCP + CLAUDE.md with OpenCode. |
| Session & Color | Per-project auto-session naming + the per-alias color hint reality. |
| TOON Integration | Token-efficient JSON encoding utility. |
| Fine-Tuning deep dive | Full architecture walkthrough (.html/.pdf siblings). |
| CHANGELOG | Release history. |
claude_toolkit is one of the hub engines of the Helix constitution
(constitution/submodules/{llmctl,claude_toolkit,open_design}):
- Consumed by reference. A project gets it at
constitution/submodules/claude_toolkit(pinned by sha in the hub'shelix-deps.yaml); it is never copied, never shipped inside a product artifact. - Never initialised recursively.
git submodule update --initstops at the engine; the only submodules it carries are the third-partysubmodules/goandsubmodules/ccusage. - No nested own-org copies. Its dependencies are found by
scripts/resolve_deps.sh:CT_<NAME>_DIRoverride β parent hub β<root>/submodules/<name>β sibling (Constitution Β§11.4.28(C), gateCM-HUB-ENGINE-NO-OWNORG-NESTING);helix-deps.yamldeclares them (Β§11.4.31). Offline checks:scripts/tests/test_helix_deps_manifest.sh,scripts/tests/test_gitmodules_no_ownorg.sh. - Model governance it participates in. Β§11.4.277 (llmctl model validation
gate; STRICT mode,
llmctl require-validated), Β§11.4.278 (HelixQA Vision UI QA, which reads screens through a gate-validated Vision model) and Β§11.4.279 (the decision-models layer: typed, non-chat answers that never become aliases β the Jev layer here). The toolkit forwards the gate's environment and propagates its refusals; it does not re-implement the gate (scripts/tests/test_llmctl_vision_gate_wiring.sh).
Diagram: hub-engine placement.
Decision models answer typed questions (choice / noul / score) with
probabilities; they have no chat endpoint, so they are never aliases
(classification: decision, alias: null). The local llmctl decide gateway
is HTTPS with a mandatory bearer key (Authorization: Bearer $LLMCTL_API_KEY, local CA at $LLMCTL_HOME/cert/ca/ca.crt); /healthz and
/readyz are the only unauthenticated routes. The detector, gate and MCP server speak that
(TLS with the llmctl CA, key from the env var named in the pin, never printed
and never on a command line; plain http is opt-in via CMA_JEV_ALLOW_HTTP=1,
loopback-only, unauthenticated, never for other hosts). Verified
against a hermetic TLS stand-in, not a real gateway. See the
Jev guide and the
decide-gateway flow.
bash, rsync, jq, awk. Optional: node+npm (TOON utility), pandoc
(+ weasyprint/wkhtmltopdf/headless chromium) for doc regeneration.
# macOS (Homebrew)
brew install bash jq rsync gawk pandoc weasyprintmacOS ships bash 3.2; the scripts auto-re-exec under Homebrew bash when needed,
and only touch ~/.zshrc on Darwin.
Own-org dependencies are flat, not nested. This repo tracks no
vasic-digital/* or HelixDevelopment/* submodule (the only submodules are the
third-party submodules/go and submodules/ccusage). The Go router (claude-code-router), the optional
LLMsVerifier, and constitution/containers/challenges/superspec are found
by scripts/resolve_deps.sh <name>: CT_<NAME>_DIR override β parent hub
(<hub>/submodules/<name>) β <root>/submodules/<name> β sibling ../<name>,
with a loud error and the clone command when nothing resolves. A standalone
curl-install.sh run (no parent hub) clones the router over https into
$(dirname INSTALL_DIR)/claude_code_router for you.
The own-org dependency manifest is helix-deps.yaml
(Β§11.4.31; validated by scripts/tests/test_helix_deps_manifest.sh).
~/.claude-shared/ # single source of truth
projects/ todos/ tasks/ plans/ plugins/ sessions/ β¦
CLAUDE.md history.jsonl settings.json stats-cache.json
~/.claude-<account>/ # per-account β mostly symlinks
.credentials.json # PRIVATE β account-locked
.claude.json # per-account state (non-auth contents sync)
mcp-needs-auth-cache.json # PRIVATE
projects -> ~/.claude-shared/projects # every shared item is a symlink
~/.claude-shared/kimi/ # Kimi shared store (mirrors the above)
AGENTS.md plugins/ skills/ sessions/ session_index.jsonl
~/.kimi-code-<account>/ # per Kimi account β mostly symlinks
config.toml credentials/ oauth/ device_id # PRIVATE β per-account
sessions -> ~/.claude-shared/kimi/sessions # shared items are symlinks
~/.local/share/claude-multi-account/aliases.sh # managed alias file
Claude Code keeps a projects.<path> map inside each account's .claude.json
(lastSessionId, MCP status, project memory pointers). Without intervention,
account A's projects are invisible to account B even though the JSONL transcripts
live in the shared projects/. The toolkit fixes this in two layers:
- At unify time β
claude-unifydeep-merges every account's.claude.json(rightmost-wins on scalars, recursive union of theprojectssubtree), writing each account's auth-private keys back untouched. - At runtime β the
cma_runwrapper callsclaude-sync-state pullbefore each launch andpushafter exit (a fastjqmerge), so sessions created in one account appear in the others on the next launch.
Auth keys (userID, oauthAccount, firstStartTime, claudeCodeFirstTokenDate)
never cross accounts.
Disabled plugins (and the skills, MCP tools and agents they bundle) stop costing
tokens in every session. Claude Code stores the disablement per alias:
plugins in <alias>/settings.json .enabledPlugins, MCP servers in
<alias>/.claude.json .projects[<path>].disabledMcpServers. The toolkit's
unify/seed logic is additive (any-true union), which used to re-enable
everything the operator disabled in one alias. Since v1.34.0:
claude-sync-plugins capture # snapshot claude1's curated set -> ~/.claude-shared/plugin-policy.json
claude-sync-plugins --dry-run # what would change, writes nothing
claude-sync-plugins --apply # enforce on every alias (backs up + manifest)
claude-sync-plugins --verify # exit 0 conformant, 1 drift, 2 no policy
claude-sync-plugins --status # enabled/total plugin count per aliasenabledPluginsis applied verbatim; a plugin the policy does not list is set false (unknown => disabled). Every other settings key is untouched.disabledMcpServersis set-unioned into every project of every other alias.- The source alias is never written; when its
settings.json/.claude.jsonis newer than the policy, the launch-time hook (claude-sync-state) re-captures it, so a/pluginchange in claude1 reaches all aliases on their next launch. - New aliases (
claude-add-account,claude-providers sync,claude-bootstrap),claude-unifyandinstall.shenforce it;claude-install-verifyfails on drift. - Opt out with
CMA_PLUGIN_POLICY=off; with no captured policy nothing changes. - Limits: an MCP server you re-enable in the source is not removed from other aliases (union only); a project directory an alias has never opened gets the list at its next launch.
bash scripts/tests/run-all.sh # all hermetic suites (sandboxed $HOME)
bash scripts/tests/run-all.sh lib unify session # subset by suffix
bash scripts/tests/run-proof.sh # hermetic + live verifiers + evidence bundleTests use a sandboxed $HOME via mktemp β your real ~/.claude* is never
touched. The suite is 145 test files (ls scripts/tests/test_*.sh | wc -l); a hermetic run on a host without a claude-code-router checkout fails the router-backed files (see CHANGELOG v1.32.0), and shellcheck was NOT re-run for v1.34.0
(UNCONFIRMED; the historical v1.26.x figures were 62 warning-level and 203
style-level suggestions over an unrecorded file set, and are not a current claim); live verifiers
(verify_*_live.sh) prove behavior against the real OpenCode/provider state and
write inspectable evidence to scripts/tests/proof/.
claude-release-gate # sandbox suite + LIVE alias smoke
claude-release-gate --verify-providers # + full LLMsVerifier model scan
claude-release-gate --provider poe # smoke through a different providerNo release commit without a green claude-release-gate. The sandbox suite
proves wrapper logic but is structurally blind to real-host state β v1.25.1
shipped fully green while every router alias on the real host was bricked by a
PATH-shadowing ccr doppelgΓ€nger, and the live smoke then caught two more
real defects (a mis-sliced HelixLLM context and ~330k tokens of auto-resumed
session history) within minutes of existing. The gate drives the REAL
generated alias through the REAL PATH β ccr β route-apply β proxy β backend
and asserts the served reply plus the sink-side route. Fail-closed: any layer
red = do not release.
claude-rollback # == claude-unify --rollbackRestores every .preunify.<timestamp> backup and moves the shared store aside to
~/.claude-shared.removed.<timestamp>.
See repository.