agent-shim

A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling — precisely, and per working directory — what gets shared between them.

The problem

Claude Code keeps everything it knows in one place: ~/.claude. Skills, memory, conventions, but also every conversation transcript, session file, and task list you've ever produced, across every project you've ever touched. If you want a second login (a personal account alongside a work one, say) or you want to keep one client's work cleanly separated from another's, there's no built-in way to say "share the skills and conventions, but not the history" — it's all one directory, all or nothing.

agent-shim solves this with two independent things:

• An identity is a login. It's the thing that owns credentials and daemon state, and it's what you switch between with claude @work or claude @personal.
• A configuration profile is a reusable, named bundle of sharing rules — what's visible, what isn't. It exists independently of any identity, and which one applies can depend entirely on which directory you're working in.

Keeping these separate matters because they answer different questions. "Which login am I using?" and "What should this login see right now?" don't have to have the same answer every time, and forcing them to share one concept (as most ad hoc setups do) means you can't express "one login, several different sharing postures depending on where I am" — which turns out to be the common case.

Install

curl -fsSL https://github.com/ExaDev/agent-shim/releases/latest/download/install.sh | sh

This installs agent-shim alone into ~/.local/bin; your existing claude command is left untouched. agent-shim run [args...] reaches the same identity-resolve, farm-resync, spawn pipeline a claude-named binary would, so every feature already works with no further setup. Run agent-shim shim enable once for the shorter claude @<name> form (shim disable reverses it).

Also available: npm (npm install -g agent-shim, needs Node 22.18 or later, or 24 and above), Homebrew (brew install ExaDev/agent-shim/agent-shim), Scoop on Windows, a scoped GitHub Packages alias, and installing straight from the git repository with no registry at all. Each channel's exact commands, the platform support matrix, and the one architecture (macOS x64) that needs a different install path are in docs/installation.md.

Renamed from claude-use

agent-shim was called claude-use until it was renamed. Everything written for the old name keeps working, and agent-shim doctor lists what still uses it:

• The claude-use command is installed beside agent-shim by every channel and runs the same program.
• CLAUDE_USE_* environment variables are read wherever AGENT_SHIM_* is; the current name wins when both are set.
• An existing ~/.claude-use is used in place when there is no ~/.agent-shim. Do not move it: macOS Claude Code keys each identity's Keychain login on the exact path of its configuration directory (<root>/identities/<name>), so relocating the root signs every identity out. A fresh installation uses ~/.agent-shim.
• A committed .claude-use.json or .claude-use.local.json is read when the directory has no .agent-shim.json or .agent-shim.local.json; configure keeps writing into the legacy local file while it is the only one.
• A farm manifest written under the old name is read, and replaced by the current one on the next resync.
• A session launched by a release under the old name keeps working against a newer front door: its internal x-claude-use-* request headers are accepted as their x-agent-shim-* equivalents and never forwarded upstream.
• npm: claude-use is still published, identical to agent-shim and exposing both commands, so npm install -g claude-use keeps tracking releases. Homebrew moves an installed claude-use formula to agent-shim on upgrade.

Quick start

agent-shim identity add personal      # create your first identity (a fresh login)
agent-shim run @personal              # log in and start using it

Want the shorter claude @personal instead? Run agent-shim shim enable once — see Install.

That's it — with no further configuration, everything in ~/.claude that isn't credentials or daemon runtime is classified into categories (see below) and shared according to sensible defaults. Add a second identity, add configuration profiles, and add directory rules only once you actually need more control than that.

Concepts

agent-shim separates two things most ad hoc multi-account setups conflate:

• An identity is a login: the thing that owns credentials and daemon state, selected with agent-shim run @<name> or, once agent-shim shim enable has run, claude @<name>.
• A configuration profile is a reusable, named bundle of sharing rules, independent of any identity, resolved per working directory via directory rules or a committed .agent-shim.json.

A third, optional thing sits on top of identities: a pool is a named list of them. Select pool:<name> where an identity name goes (claude @pool:subs) and agent-shim picks the member whose unused quota is closest to expiring, skipping any that are refused right now, using the usage it already records. A pool can instead declare --preference listed, which tries the members in the order the pool lists them, skipping only one that is refused right now. A member entry may itself name another pool (pool:<name>), which is ranked with its own policy and contributes its pick at that position, so "this identity first, then the fleet" nests the fleet rather than copying its member list; cycles are refused. Members that hold the same login (the same account in the same organisation) share one quota window, so a pool ranks them as one candidate and never fails over from one to the other; pool add, pool set and doctor warn when a pool lists two of them. See docs/configuration-model.md. On a terminal, agent-shim run asks which identity to run as when none resolves, when a pool pick would change account, or when the identity is refused right now (--pick forces the question, --no-pick never asks); see docs/configuration-model.md.

Every top-level entry in ~/.claude is classified into one of five categories, shipped as a default map (config/categories.default.json):

Sharing composes through a cascade (shipped defaults, then a user-global override, then the active configuration profile, then directory rules for $PWD, shallowest to deepest); a specific path override always outranks a category default regardless of which layer set it. A committed .agent-shim.json at a project's root makes this portable: anyone who clones the repo and runs claude inside it gets the same isolation rules with no local setup.

claude refuses to launch while ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN or a CLAUDE_CODE_USE_BEDROCK/VERTEX/FOUNDRY variable is set in the environment, because those outrank every identity's stored credential and would make all identities authenticate as the same account. Opt in deliberately with AGENT_SHIM_ALLOW_AMBIENT_CREDENTIAL=1 for one launch or agent-shim identity set <name> --allow-ambient-credential.

Providers and identities take their token from one credential block: an ordered list of sources (env, file, command, and the op and keychain presets, plus a literal placeholder for a local proxy), tried in turn, and a target (bearer, apiKey, or oauthToken for an identity). An identity's token reaches the child's environment only; a provider's never reaches the child at all (the front door attaches it at the provider's route, which is also what lets provider inference and Remote Control share one session). check, doctor and --json report the source kind and target, never the value.

The full mechanics, including the credential block, the merge algorithm, conditional sharing rules (age, size, git branch, environment), the ambient-credential launch guard, and how ~/.claude/projects/ history is pattern-matched, are in docs/configuration-model.md. Worked examples are in docs/examples.md.

CLI reference

Every command is agent-shim <noun> <verb> [name] [options], over the nouns identity, profile, pool, provider, model, rule and job, plus the top-level run, configure, check, doctor, usage, update and the others; claude @<identity> is the same as agent-shim run @<identity> once agent-shim shim enable has run. The full list of commands with every flag is in docs/cli-reference.md, and agent-shim --help and agent-shim <noun> --help print it from the installed version.

Every list, show, check, doctor and headroom status prints text by default and JSON with --json, and so do the mutating commands (add, set, remove and use on identities, profiles, providers, pools and rules), which print one object naming the action, the kind, the name and, for a creation or update, the stored value. identity rename prints its report of what it moved and rewrote as the value, with the action planned under --dry-run. Prompts appear only when standard input is a terminal; without one, a command that needs input fails with the option that supplies it (a remove needs --yes). Failures print as agent-shim: <message> and exit 1, usage errors exit 2, a selected provider or identity whose credential block yields no token exits 64, and AGENT_SHIM_DEBUG=1 adds stack traces to unexpected errors. agent-shim completion <bash|zsh|fish> prints a shell completion script.

agent-shim check [path] resolves the full cascade for a directory without touching the farm, and is the primary way to answer "why is X shared or hidden here". agent-shim doctor audits the whole ~/.agent-shim config graph at once: every identity, profile, extends chain, provider (naming the exact replacement for a file still in the format before the credential block) and directory rule, plus whether the right agent-shim is the one actually on PATH.

The per-setting flag and environment-variable table (global, one-off, and directory-scoped forms of every setting) and the file-precedence rules configure uses when writing a toggle are in the same docs/cli-reference.md.

Architecture

One compiled binary backs both claude and agent-shim; the entrypoint dispatches on path.basename(process.argv[1]), so installation just needs two differently-named copies (or hardlinks) of the same executable on PATH.

src/
  cli.ts                 # entrypoint: dispatches on invoked name to launcher vs identity/profile-manager subcommands
  launcher.ts             # runLauncher: thin orchestration over launcher/*
  launcher/               # argv parsing, the ambient-credential guard, identity/profile resolution, farm resync
  identityManager.ts, configProfiles.ts, providers.ts, directoryRules.ts   # the `identity`/`profile`/`provider`/`rule` nouns' commands
  identityStore.ts, configProfilesStore.ts, providersStore.ts, directoryRulesStore.ts, poolStore.ts   # their data layers, free of command-line dependencies and exported by the library
  program.ts, completion.ts # buildProgram (the whole command tree, side-effect free) and generated shell completion
  configure.ts, check.ts, doctor.ts, claudeShim.ts           # interactive picker, the check and doctor commands, `claude` shim
  checkReport.ts, checkReportSchema.ts, doctorReport.ts, poolPickReport.ts   # the dry-run inspector, the Zod schema of its JSON form, the whole-tree audit and the pool ranking as data, free of command-line dependencies and exported by the library
  resolve/                # the pure cascade resolver: flatten, decide, extends, walk, plan, reconcile
  agents/                 # the agent tree reader: a session's subagents, forks, workflow runs and task list from the transcripts on disk, over an injected filesystem
  config/                 # Zod schemas, cosmiconfig loading, category classification, atomic JSON store
  index.ts                # the library surface (see below): resolver, farm sync, headroom routing, the ambient-credential guard
schema/                   # published JSON Schemas, generated by `pnpm schema`
scripts/build.mts          # esbuild bundle, then `node --build-sea`
install.sh                 # downloads, verifies, and installs the latest release binary

Every custom error extends CliError; main()'s top-level catch prints its message alone for an expected failure and a full stack trace for anything else. Config validation is Zod throughout, with categories a closed shape and entries an open, glob-capable record, since the two fields have opposite key cardinality. The resolver itself is pure: it takes filesystem, git, and environment facts as an injected parameter rather than reading them itself, which is what makes it unit-testable with fakes.

The package also publishes a library surface alongside the binary: import { resolveDecisions, resyncFarm, startConnectServer, runFrontDoorSupervisor, runSupervisor, detectAmbientCredential } from "agent-shim" (ESM or CJS, with type declarations). It re-exports only the pure, port-injected modules, so another tool can resolve identities, sync a farm, run the front door's CONNECT surface and supervisor and the headroom supervisor, or check the ambient-credential guard in process without the CLI installed. Nothing reachable from it imports commander or @clack/prompts, and the build fails if that stops being true. Its dependencies stay external, installed through the package's own dependencies.

The full source layout with per-file responsibilities, the schema design rationale, why config loading uses cosmiconfig's load() rather than search(), and the resolver's merge and materialisation mechanics are in docs/architecture.md.

Releases and builds

Commits follow Conventional Commits (enforced by commitlint); every push to main runs semantic-release, which decides whether a release is warranted, bumps the version, updates CHANGELOG.md, and tags it. pnpm build bundles the CLI and then runs Node's single-executable-application step, which needs Node 25.5.0 or later with SEA support: a Homebrew-installed Node has this compiled out, so use a build from nodejs.org or a version manager instead.

macOS x64 is the one target Node core does not verify SEA against, and the resulting binary segfaults on that architecture: a known, unfixed upstream Node limitation, not a bug in this project. Homebrew and install.sh both work around it by installing through npm and a real Node on that one platform instead of the broken binary.

The full CI pipeline (why the six platform builds also run on every PR, the semantic-release quirks, npm OIDC trusted publishing, and the root-cause investigation behind the macOS x64 crash) is in docs/release-process.md.

Testing

The resolver's cascade and materialisation logic is pure, taking filesystem, git, and environment facts as an injected parameter, so it is unit-tested extensively with fakes rather than a real filesystem, git, or ~/.agent-shim. launcher.ts, check.ts, and doctor.ts each get their own coverage for the real side effects the resolver's purity does not reach: symlink and materialised-directory writes, spawning the real claude binary, and the ambient-credential guard.

The full list of test cases, including the two-phase merge algorithm, conditional entries, farm reconciliation, and every command's own edge cases, is in docs/testing.md.

Development

pnpm install     # install dependencies
pnpm typecheck   # tsc --noEmit
pnpm lint        # eslint . --max-warnings 0
pnpm test        # vitest run
pnpm build       # bundle src/cli.ts with esbuild, then node --build-sea (needs Node >= v25.5.0 with SEA support, not Homebrew's build; see docs/release-process.md)
pnpm schema      # regenerate schema/*.schema.json from src/config/schema.ts; CI fails if this drifts from what's committed

Run a single test file directly with pnpm exec vitest run <path>. Tests never touch a real identity: vitest.config.ts sets AGENT_SHIM_HOME to a throwaway directory, and a setup file refuses to run at all if that variable is unset or resolves to the real ~/.agent-shim.

Commits are gated by Husky hooks: commit-msg enforces conventional-commit format, pre-commit runs eslint --fix on staged files and rejects merge/squash commits and mass deletions on main, and pre-push runs typecheck, the schema drift check, knip and the tests related to what the push changes (CI runs the full suite) and also rejects a push that would delete more than 100 files on the remote.

A fresh clone needs one extra step before committing anything, since git stores filter definitions in .git/config rather than in the repository:

git config filter.secrets.clean 'python3 .githooks/git-filter-clean %f'
git config filter.secrets.smudge cat

Without this, the secret-redaction clean filter .gitattributes declares resolves to nothing and content reaches the object store unredacted. Never add a diff.secrets.textconv pointing at the same script: it is a stream filter expecting stdin, not a path, and would hang forever under lint-staged. Full rationale for the %f argument, plus the test-isolation and commit-hook details above, is in docs/development.md.

Contributing

Issues and pull requests are welcome. Please keep the tool itself free of assumptions about any particular organisation, client, or directory layout — it should work the same for anyone. Governance details (contribution sign-off requirements, code of conduct, review process) aren't decided yet and will be added here before the repository is opened up beyond its initial maintainers.

References

• docs/configuration-model.md: identities, configuration profiles, category-based sharing, the cascade merge algorithm, directory rules, conditional matching, portable .agent-shim.json, ~/.claude/projects/ pattern matching, providers, headroom routing, and launch flags.
• docs/cli-reference.md: the full flag and environment-variable table, configure's file-write precedence, and the check/doctor debugging commands.
• docs/examples.md: worked configuration examples and a permutation reference.
• docs/architecture.md: the source layout file by file, error reporting design, schema rationale, and resolver mechanics.
• docs/release-process.md: the semantic-release pipeline, the Node SEA build, its macOS x64 limitation, and npm/GitHub Packages publishing.
• docs/testing.md: the full list of cases the test suites cover.
• docs/library.md: using agent-shim in process: what the library exposes, and what stays CLI-only.
• docs/installation.md: every install channel in full, with the platform support matrix.
• docs/development.md: test isolation, commit hooks, and the secret-redaction filter rationale.
• docs/headroom-measurement.md: measuring what headroom's transforms are worth on real conversations, offline: the replay method, the cache-weighted cost model and its limits.
• docs/rc-interception-rig.md: the Remote Control interception rig: bring-up, per-host TLS proof, teardown, and the manual login step.
• docs/rc-web-client.md: the self-hosted Remote Control web client: the page the door serves behind its control token for browser control of its sessions, how it authenticates and speaks the typed API, and how it is tested.
• docs/rc-agent-events.md: the task and subagent lifecycle events a Remote Control session's read stream carries, and the keys that join them to the transcripts on disk.
• docs/agent-transcripts.md: how Claude Code lays out a session's subagents, forks, workflow runs, tasks, teams and jobs on disk, and which fields are always present.

License

MIT License.