Skip to main content
Glama

ghmux — GitHub 多账户管理 CLI + MCP

一个零依赖(Node ≥ 20)的命令行工具 + Agent-first 配套 MCP,掌管 GitHub 多账户的提交身份、推送凭证、出口 IP 与 API 限流合规。

对 GitHub 的一切流量经 gh cli(api/认证/代理),代码零裸 HTTP;推送认证走 gh auth git-credential(GH_TOKEN 注入),出口走账户 proxy(proxylanes 泳道)。

为什么

多个 GitHub 账户时最容易出的事故:

事故

ghmux 的防线

用 A 账号的身份提交了 B 账号的仓库

use 绑定仓库→账户;commit 校验身份、漂移自动纠正

推送时凭证串号(keychain 里旧 token 抢先)

专用 credential helper(清空继承链,按仓库注入正确 token)

多账户同出口 IP(风控信号)

账户级 proxy 字段(proxylanes 泳道,一账户一泳道,天然并发隔离)

限流期间继续打 API → 官方明确会 ban

api 网关:串行锁 + 变异 ≥1s + 退避重试 + 4xx 绝不重试

Related MCP server: Octoswitch

快速上手

npm install -g .            # 或 npm link 开发模式

ghmux add work \
  --token ghp_xxx \
  --proxy http://127.0.0.1:24001   # proxylanes 泳道;自动验证 token、回填用户名/noreply 邮箱

cd 某个仓库
ghmux use work              # 绑定:提交身份 + 凭证 + 出口写进 local config
ghmux commit -m "..."       # 提交(身份漂移自动纠正,完成后回显 author)
ghmux push                  # 推送(正确账户凭证 + 正确出口)
ghmux api user --jq .login  # gh api 网关(当前仓库账户身份)
ghmux as work -- gh pr list # 以账户身份执行任意 gh 命令

未绑定的仓库:ghmux commit --auto / push --auto 按 origin owner 匹配账户, 身份与凭证一次性注入(-c 参数),不落盘。

命令

账户   add / ls / edit --set k=v / rm / check [名字] / doctor
绑定   use <名> / which / unuse
操作   commit [git参数…] [--auto] / push [git参数…] [--auto]
API    api [--as <名>] <endpoint> [gh-api参数…] / as <名> -- <命令…>
内部   git-credential <名> <get|store|erase>(git credential helper 协议)

账户字段:githubUser name email token sshKey proxy note。 配置存于 ~/.ghmux/config.json(0600,原子写)。

限流合规设计(依据 GitHub 官方 rate-limits + best-practices,2026-10 查证)

官方明确会封号的只有两类:限流期间继续发请求;故意忽略重复的 4xx 验证错误。 其余都是限流(403/429)不封号。ghmux api 按此设计:

  • 串行:跨进程锁(~/.ghmux/api.lock,30s 陈旧自愈)——防并发触发 secondary limit

  • 变异间隔 ≥1s:POST/PATCH/PUT/DELETE 前按时间戳文件补足(跨进程生效)

  • 退避重试:限流类失败(rate limit / secondary / abuse / 裸 429)按响应里的 retry-after / x-ratelimit-reset 等待;没有则 ≥61s 指数退避,最多 2 次

  • 绝不重试:404 与其他 4xx(权限/参数错误重试只会加重问题);--no-retry 全关

  • 限额查询:check 走 GET /rate_limit(官方不计限额端点)

  • 基于 gh CLI 转发:继承其内建限流退避与认证管理,不裸拼 HTTP

出口 IP 纪律(多账户环境)

每个账户配 proxy 指向 proxylanes 泳道端口(24001-24016,一账户一泳道、 每泳道固定绑定节点——多账户并发推送/调 API 各走各的出口,互不干扰):

  • use 时写入 http.https://github.com/.proxy(仅该仓库生效)

  • api / as 注入 https_proxy 环境变量

  • sshKey 场景自动生成带 ProxyCommand(nc connect 隧道)的 core.sshCommand

⚠️ 账户的出口节点不可随意更换(换绑泳道节点 = 换出口 IP = 风控信号)。 泳道↔账户↔节点的绑定以 accounts-cards 卡片 exitNode 为准,不要主动 switch/heal 已被账户占用的泳道。

配套 MCP(Agent-first,hot-mcp 架构)

mcp/ — Agent 的 GitHub 多账户操作入口(热加载,改 mcp/tools.mjs + reload 即时生效):

who          决策查询:某仓库该用哪个账户(绑定/origin 匹配/漂移状态)
accounts     账户清单(token 不回显)
check        token 有效性 + 限额余额(按资源池:core/search/graphql)
commit_push  一击必杀:正确身份提交并推送(漂移纠正/adopt 匹配/gh cli 认证通道)
api          限流合规 API 网关(一切 GitHub 查询/变更走这里,不自己拼 HTTP)
as           以账户身份执行任意命令(GH_TOKEN + 出口 env 注入)
use / unuse  仓库绑定管理
add / edit   账户管理

注册:claude mcp add ghmux --scope user -- node <项目>/mcp/index.mjs; 冒烟:node mcp/smoke.mjs(含双 reload 热加载验证)。

测试

node test/unit.mjs   # 限流分类 / retry-after 提取 / 方法推断,20 项

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to run structured preflight checks and identity-scoped Git operations, committing, pushing and opening GitHub PRs with the correct Git name, email, SSH key and signature for each repository. Persistent changes require exact proposals, human approval by default and recoverable, idempotent apply.
      77 PyPI
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to work with multiple GitHub accounts at once, automatically routing each call to the correct token based on an explicit account argument, the repository owner's login, or a configured default. Exposes tools for listing repos, issues, and pull requests plus creating repos, issues, comments, and PRs, while keeping tokens hidden and requiring confirmation before writes.
      11 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to automate account operations through natural language, exposing ten tools that create repositories, issues, commits and branches, list repositories, issues and commits, comment on and close issues, and diagnose token scopes and rate limits. Validation with Zod, retries with exponential backoff, and error translation into plain language keep the workflow reliable from any MCP-compatible host.
      10
      489 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding agents to perform scoped, policy-enforced GitHub operations with allowlisted repositories and tools, protected branches, approval gates, dry runs, secret redaction, and a tamper-evident audit log.
      MIT