agent-shim weekly downloads statistics

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

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 @ 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 (/identities/), 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

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 @ or, once agent-shim shim enable has run, claude @. • 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: 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:), 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. 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):

| Category | Default shared? | Example entries |…

Description from the npm listing.