agent-shim

的配置文件管理器和启动器 克劳德代码 这使得一个人可以在一台机器上运行多个登录，同时精确地控制每个工作目录之间共享的内容。

这个问题

克劳德代码把它知道的一切都保存在一个地方： ~/.claude． 技能，记忆，惯例，还有每一次谈话记录，会议文件，以及你曾经制作过的任务列表，你曾经接触过的每一个项目。如果你想要二次登录（比如一个个人账户和一个工作账户），或者你想让一个客户的工作与另一个客户的工作清晰地分开，没有内置的方法来说“共享技能和惯例，但不共享历史”——这是一个目录，要么全有，要么全无。

agent-shim 用两个独立的东西来解决这个问题：

• 一个身份 是一个登录。它是拥有凭据和守护进程状态的东西，也是您在两者之间进行切换的东西 claude @work 或 claude @personal。
• 配置文件 是一个可重用的、命名的共享规则包——哪些可见，哪些不可见。它独立于任何标识存在，应用哪一个完全取决于您在哪个目录中工作。

把这些分开是因为它们回答了不同的问题。“我使用的是哪个登录名？”和“这个登录名现在应该看到什么？”不必每次都有相同的答案，强迫他们共享一个概念（就像大多数临时设置一样）意味着你不能表达“一个登录名，根据我在哪里有几个不同的共享姿势”——这是常见的情况。

安装

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

这个安装 agent-shim 独自一人到 ~/.local/bin;你现有的 claude Command保持不变。 agent-shim run [args...] 达到相同的身份解析，农场重新同步，刷出管道a claude-named binary会，所以每个特性都已经工作了，没有进一步的设置。运行 agent-shim shim enable 一次是短暂的 claude @<name> 形式(shim disable 反转)。

其他可用版本：npm (npm install -g agent-shim，需要Node 22.18或更高版本，或24及以上版本),Homebrew (brew install ExaDev/agent-shim/agent-shim)， Windows上的Scoop，一个有作用域的GitHub Packages别名，直接从git存储库安装，根本不需要注册表。每个通道的确切命令、平台支持矩阵和需要不同安装路径的架构（macOS x64）都在其中 文档/ installation.md。

从claude-use重命名

探员希姆被叫来了 claude-use 直到被重新命名。为旧名字写的所有东西都有效，而且 agent-shim doctor 列出了仍在使用它的地方：

• 这个 claude-use 命令安装在 agent-shim 每个频道都在播放同样的节目。
• CLAUDE_USE_* 环境变量可以在任何地方读取 AGENT_SHIM_* 是;当两者都设置时，当前名称获胜。
• 现有的 ~/.claude-use 是用在没有地方的时候 ~/.agent-shim． 不要移动它：macOS Claude Code在其配置目录的确切路径上密钥每个身份的Keychain登录(<root>/identities/<name>)，因此重新定位根会将每个身份标识标识出来。新安装使用 ~/.agent-shim。
• 一个承诺 .claude-use.json 或 .claude-use.local.json 当目录没有时读取 .agent-shim.json 或 .agent-shim.local.json； configure 当遗留本地文件是唯一的时候，继续写入该文件。
• 读取以旧名称编写的场清单，并在下一次重新同步时用当前名称替换。
• 由旧名称的发布发起的会话一直在对抗一个新的前门：它的内部 x-claude-use-* 请求头被接受为它们的 x-agent-shim-* 等价物，从未转发到上游。
• npm: claude-use 仍然出版，相同吗 agent-shim 并公开这两个命令，所以 npm install -g claude-use 跟踪发布。Homebrew移动安装 claude-use 公式 agent-shim 在升级。

快速启动

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

想要短一点的 claude @personal 而不是?运行 agent-shim shim enable Once - see 安装。

就是这样，没有进一步的配置，一切都进去了 ~/.claude 这不是凭据或守护进程运行时被分类（见下文），并根据合理的默认值共享。只有在实际需要更多控制时，才添加第二个标识、添加配置文件和添加目录规则。

概念

agent-shim 将大多数临时多帐户设置合并的两件事分开：

• 一个身份 是否选择了拥有凭据和守护进程状态的登录 agent-shim run @<name> 或者,一旦 agent-shim shim enable 运行, claude @<name>。
• 配置文件 一个可重用的、命名的、独立于任何身份的共享规则包是否通过目录规则或已提交的文件在每个工作目录中解析 .agent-shim.json。

第三个可选的东西位于身份之上： 池 是它们的命名列表。选择 pool:<name> 身份名称的位置(claude @pool:subs)， agent-shim选择未使用配额最接近到期的成员，跳过目前被拒绝的成员，使用它已经记录的使用情况。池可以声明 --preference listed，它按照池列出的顺序尝试成员，只跳过当前被拒绝的成员。成员项本身可以命名另一个池(pool:<name>)，它根据自己的政策进行排名，并在该位置贡献自己的选择，所以“先这个身份，然后是舰队”筑巢舰队，而不是复制它的成员名单；自行车被拒绝了。拥有相同登录名（同一组织的相同帐户）的成员共享一个配额窗口，因此一个池将他们列为一个候选人，永远不会从一个候选人转移到另一个候选人； pool add， pool set 和 doctor 当一个池列出其中两个时发出警告。看到 文档/ configuration-model.md． 在终端上， agent-shim run 询问当没有解决时运行哪个身份，当池选择将更改帐户时，或者当身份立即被拒绝时(--pick 引出一个问题， --no-pick 不曾要求);看到 文档/ configuration-model.md。

每个顶级条目 ~/.claude 分为以下五类之一，作为默认映射(config/categories.default.json):

共享通过级联（附带默认值，然后是用户全局覆盖，然后是活动配置文件，然后是目录规则）组成 $PWD从最浅到最深)；特定的路径覆盖总是优先于类别默认值，无论哪一层设置它。一个承诺 .agent-shim.json 在一个项目的根目录使它可移植：任何人克隆repo并运行 claude 在内部，它获得相同的隔离规则，没有本地设置。

claude 拒绝启动 ANTHROPIC_API_KEY， ANTHROPIC_AUTH_TOKEN， CLAUDE_CODE_OAUTH_TOKEN 或者一个 CLAUDE_CODE_USE_BEDROCK/VERTEX/FOUNDRY 变量在环境中设置，因为它们的级别高于每个身份的存储凭据，并且会使所有身份验证为相同的帐户。有意识地选择加入 AGENT_SHIM_ALLOW_AMBIENT_CREDENTIAL=1 一次发射或 agent-shim identity set <name> --allow-ambient-credential。

提供者和身份从一个对象中获取令牌 credential 块：一个有序的源列表(env， file， command，和 op 和 keychain 预设值，加上a literal 本地代理的占位符)，依次尝试，以及目标(bearer， apiKey,或 oauthToken 用于标识)。身份令牌只能到达孩子的环境；一个提供者永远不会到达子节点（前门将它连接到提供者的路由上，这也是让提供者推理和远程控制共享一个会话的原因）。 check， doctor 和 --json 报告源的种类和目标，而不是值。

完整的机制，包括凭证块、合并算法、条件共享规则（年龄、大小、git分支、环境）、环境-凭证启动保护，以及如何 ~/.claude/projects/ 历史是模式匹配的，都在 文档/ configuration-model.md． 工作实例见 文档/ examples.md。

CLI参考

每个命令都是 agent-shim <noun> <verb> [name] [options]，超过名词 identity， profile， pool， provider， model， rule 和 job，加上顶层 run， configure， check， doctor， usage， update 还有其他的； claude @<identity> 等于 agent-shim run @<identity> 一次 agent-shim shim enable 运行。包含每个标志的命令的完整列表 文档/ cli-reference.md, agent-shim --help 和 agent-shim <noun> --help 从安装的版本打印它。

每一个 list， show， check， doctor 和 headroom status 默认打印文本和JSON --json，变化的命令(add， set， remove 和 use （标识、配置文件、提供程序、池和规则），它们打印一个命名为 action, kind, name 对于创建或更新，存储的 value。 identity rename 将其移动和重写的报告打印为 value，与 action planned 下 --dry-run． 只有当标准输入是终端时才会出现提示；如果没有选项，需要输入的命令将无法使用提供它的选项(a remove 需要 --yes）. 失败打印为 agent-shim: <message> 退出1，使用错误退出2，其凭据块不产生令牌的选定提供者或标识退出64，以及 AGENT_SHIM_DEBUG=1 为意外错误添加堆栈跟踪。 agent-shim completion <bash|zsh|fish> 打印shell完成脚本。

agent-shim check [path] 在不触及场的情况下解析目录的完整级联，并且是回答“为什么X在这里共享或隐藏”的主要方法。 agent-shim doctor 全面审计 ~/.agent-shim 配置图一次：每个身份，配置文件， extends 链、提供程序（为仍然保持在凭证块之前的格式的文件命名确切的替代品）和目录规则，以及是否正确 agent-shim 那个真的开着吗 PATH。

每个设置标志和环境变量表（每个设置的全局、一次性和目录范围形式）以及文件优先级规则 configure 编写切换时的用法相同 文档/ cli-reference.md。

体系结构

一个编译后的二进制文件支持这两个文件 claude 和 agent-shim;入口点继续发送 path.basename(process.argv[1])因此，安装只需要同一可执行文件的两个不同名称的副本（或硬链接） 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

每个自定义错误扩展 CliError； main()的顶层catch对于预期的失败单独打印其消息，对于其他任何情况则打印完整的堆栈跟踪。配置验证贯穿始终 categories 一个闭合的形状 entries 一个开放的，具有全局功能的记录，因为两个字段具有相反的键基数。解析器本身是纯的：它将文件系统、git和环境事实作为一个注入的参数，而不是自己读取它们，这使得它可以用假象进行单元测试。

该包还在二进制文件旁边发布了一个库界面： import { resolveDecisions, resyncFarm, startConnectServer, runFrontDoorSupervisor, runSupervisor, detectAmbientCredential } from "agent-shim" （ESM或CJS，带类型声明）。它只重新导出纯端口注入模块，因此其他工具可以解析身份、同步场、运行前门的CONNECT界面和管理器以及净空管理器，或者在没有安装CLI的情况下检查正在进行的环境凭证保护。无法从它导入任何可访问的内容 commander 或 @clack/prompts，如果它不再为真，构建就会失败。它的依赖关系是外部的，通过包自己的依赖关系安装 dependencies。

包含每个文件职责的完整源代码布局、模式设计原理、配置加载使用cosmiconfig的原因 load() 而不是 search()，以及解析器的合并和物化机制 文档/ architecture.md。

版本和构建

提交遵循 传统的提交 （由委员会执行）；每一次推到 main 运行语义发布，它决定一个发布是否被保证，碰撞版本，更新 CHANGELOG.md，并贴上标签。 pnpm build 绑定CLI，然后运行Node的单可执行应用程序步骤，这需要Node 25.5.0或更高版本的SEA支持：homebrew安装的Node已经编译了这个，所以使用从nodejs.org或版本管理器构建。

macOS x64是一个目标节点核心没有验证SEA，并且在该架构上产生二进制段错误：一个已知的，未固定的上游节点限制，而不是这个项目中的错误。自制程序和 install.sh 这两种方法都是通过npm安装，并在该平台上安装一个真正的Node，而不是损坏的二进制文件。

完整的CI管道（为什么六个平台构建也在每个PR上运行，语义发布的怪癖，npm OIDC可信发布，以及macOS x64崩溃背后的根本原因调查） 文档/ release-process.md。

测试

解析器的级联和物化逻辑是纯粹的，将文件系统、git和环境事实作为注入参数，因此它是用假的而不是真实的文件系统进行广泛的单元测试的。 git,或 ~/.agent-shim。 launcher.ts， check.ts, doctor.ts 对于解析器的纯度无法达到的真正副作用，每个都有自己的覆盖范围：符号链接和物化目录写入，产生真正的副作用 claude 二进制，和环境凭证守卫。

完整的测试用例列表，包括两阶段合并算法、条件条目、场协调，以及每个命令自己的边缘用例 docs/testing.md。

发展

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

直接运行单个测试文件 pnpm exec vitest run <path>． 测试从不触及真实身份： vitest.config.ts 集合 AGENT_SHIM_HOME 到一个一次性目录，并且如果该变量未设置或解析为真实的，则安装文件根本拒绝运行 ~/.agent-shim。

提交由Husky hooks进行门控： commit-msg 强制常规提交格式， pre-commit 运行 eslint --fix 对分级文件和拒绝文件进行合并/压缩提交和批量删除 main, pre-push 运行typecheck、模式漂移检查、knip和与推送更改相关的测试（CI运行完整的套件），并拒绝将删除远程上超过100个文件的推送。

在提交任何内容之前，一个新的克隆需要一个额外的步骤，因为git将过滤器定义存储在 .git/config 而不是在存储库中：

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

没有这个，秘密编辑清理过滤器 .gitattributes 声明解析为零，并且到达对象存储库的内容未编校。永远不要添加 diff.secrets.textconv 指向同一个脚本：它是一个流过滤器，期望标准输入，而不是路径，并且将永远挂起在lint-stage下。的充分理由 %f 参数，加上上面的测试隔离和提交钩子详细信息 文档/ development.md。

贡献

欢迎发布和pull请求。请保持工具本身对任何特定组织，客户端或目录布局的假设-它应该为任何人工作相同。治理细节（贡献签名要求、行为准则、审查过程）尚未确定，将在仓库开放之前添加到这里。

参考文献

• 文档/ configuration-model.md：身份，配置文件，基于类别的共享，级联合并算法，目录规则，条件匹配，可移植 .agent-shim.json， ~/.claude/projects/ 模式匹配、提供者、净空路由和启动标志。
• 文档/ cli-reference.md：全标志和环境变量表； configure的文件写入优先级，以及 check/doctor 调试命令。
• 文档/ examples.md：工作配置示例和排列参考。
• 文档/ architecture.md：每个文件的源布局文件、错误报告设计、模式基本原理和解析器机制。
• 文档/ release-process.md：语义发布管道，Node SEA构建，macOS x64限制，以及npm/GitHub Packages发布。
• docs/testing.md：测试套件所涵盖的用例的完整列表。
• 文档/ library.md在进程中使用agent-shim：库公开哪些内容，哪些内容仅保留cli。
• 文档/ installation.md：每个安装通道全满，配合平台支撑矩阵。
• 文档/ development.md：测试隔离、提交挂钩和秘密编校过滤器原理。
• 文档/ headroom-measurement.md：衡量真实对话中净空转换的价值；离线：重播方法、缓存加权成本模型及其局限性。
• 文档/ rc-interception-rig.md远程控制拦截装置：启动、每台主机TLS验证、拆除和手动登录步骤。
• 文档/ rc-web-client.md自托管远程控制web客户端：门在其控制令牌后面服务的页面，用于浏览器对其会话的控制，它如何验证和使用类型化API，以及如何测试它。
• 文档/ rc-agent-events.md远程控制会话的读流携带的任务和子代理生命周期事件，以及将它们连接到磁盘上的副本的键。
• 文档/ agent-transcripts.mdClaude Code如何在磁盘上布局会话的子代理、分支、工作流运行、任务、团队和作业，以及哪些字段总是存在。

许可证

MIT许可证。