\n\n# 中文\n\nForgeRelay 是一个运行在你自己机器上的 MCP Server。它解决的是一个很实际的问题：ChatGPT 这类 Host 会写代码，但默认碰不到你电脑上的项目、Shell 和 Git。\n\n把 ForgeRelay 接上以后，Agent 就能直接在你现有的仓库里改文件、跑测试和构建、执行 Git、调用语言服务器，并继续使用你已经装好的工具链。项目不用搬到另一套工作目录，也不用为了这件事再换一套 Coding Agent。\n\n## 安装\n\n需要 Node.js `>=22.19 <27`、npm 和 Git。\n\n```bash\nnpm install -g @akira-tl/forgerelay\nforgerelay init\nforgerelay serve\n```\n\n不想全局安装也可以：\n\n```bash\nnpx @akira-tl/forgerelay init\nnpx @akira-tl/forgerelay serve\n```\n\n默认 MCP 地址：\n\n```text\nhttp://127.0.0.1:7676/mcp\n```\n\n`forgerelay init` 会让你选择允许访问的项目目录，并生成 Owner password。第一次连接 MCP Host 时，用这个密码批准客户端。\n\n检查当前实际生效的配置和 Shell：\n\n```bash\nforgerelay doctor\nforgerelay config check\nforgerelay config sources\nforgerelay config explain \n```\n\nForgeRelay 的 Config System 统一解析 User、Project 和机器私有 Project Local 配置，优先级是 `runtime > project-local > project > user > built-in`。External MCP、Language Servers、Hooks 和 Subagent Profiles 支持按需刷新与 last-known-good；启动不会自动重写旧配置。需要深入配置、迁移或排查来源时，直接看 [配置指南](https://github.com/Akira-TL/forgerelay/wiki/Configuration)。\n\n### ChatGPT 访问不到 localhost？\n\n如果 Host 运行在云端，需要给 ForgeRelay 一个公网 HTTPS 入口。Cloudflare Tunnel、ngrok、Tailscale Funnel 或普通反向代理都可以。\n\n假设公网地址是：\n\n```text\nhttps://forge.example.com/forgerelay\n```\n\n那么 Host 连接：\n\n```text\nhttps://forge.example.com/forgerelay/mcp\n```\n\n`publicBaseUrl` 填到 `/mcp` 之前。更完整的 OAuth、Tunnel 和反向代理说明见 [快速开始](https://github.com/Akira-TL/forgerelay/wiki/Getting-Started)。\n\n## 用起来是什么样\n\n正常情况下，Agent 打开你现有的 checkout，然后直接在里面工作：\n\n```text\nopen_workspace(path=\"~/project\")\n```\n\n之后它可以读取和修改文件，也可以运行真实命令：\n\n```text\nread(path=\"src/server.ts\")\nbash(command=\"npm test\")\nbash(command=\"git status --short\")\n```\n\nForgeRelay 不会默认为每个任务创建 worktree。只有你明确要求隔离或并行开发时，才使用 managed worktree。Worktree 可以从本地 branch、tag 或历史 commit SHA 启动，同时把最终集成的本地 `targetBranch` 单独记录；不需要为了历史基线先造一个临时 branch。\n\n长命令也不会要求 Agent 高频轮询。命令超过当前等待窗口时会返回稳定的 `processId`，后续继续等待、交互或中断同一个进程即可。\n\n## 主要能力\n\n- 文件、Shell、Git、测试、构建和项目脚本都在你的机器上运行。\n- Linux / macOS 可以用 Bash、zsh、POSIX sh；Windows 原生支持 PowerShell 7、Windows PowerShell 5.1 和 `cmd.exe`。\n- 同一个 checkout 会保留自己的 Workspace 身份。换一次对话，不需要重新创建工作区。\n- `code.intelligence` 可以查 definition、hover、references、symbols 和 diagnostics。\n- Agent 上下文来源走 Config v2：默认 system instructions 是 `~/.agents/AGENTS.md`，项目指令默认只匹配 `AGENTS.md`，Skills 默认按顺序扫描 `~/.agents/skills` 与项目 `./.agents/skills`。项目/User/Project Local/runtime 都可以用 replace semantics 选择其他通用 Agent 目录；ForgeRelay 不再隐式维护 `.forgerelay/skills` 来源。\n- 需要并行开发时可以创建真实 Git worktree；起始 commit 与最终 `targetBranch` 独立，集成仍只接受安全的 fast-forward，不自动制造 merge conflict。\n- 支持 MCP Apps 的 Host 会显示 Workspace Summary / Activity Panel；Workspace 身份色在 Panel 与 pretty log 中保持一致，长路径会在详情区正常换行。\n- Workspace Relay 可以把执行放到另一台 ForgeRelay；Composite Workspace 可以同时协调几个独立环境。\n- `read` 可以直接把 PNG、JPEG、WebP 和 GIF 作为临时 MCP Media content 返回；外部 MCP 通过独立的 global/Project `mcp.json` 热加载到 `mcp.external` Capability，并支持人工 OAuth 认证，而不会自动打开它返回的路径或 URL。\n\nLifecycle Hooks、Workspace Tasks、本地 Subagent、Activity/Audit、Checkpoint 和 Recovery 也已经包含在项目里，但第一次安装时不需要先学这些。需要哪个，再去 [Wiki](https://github.com/Akira-TL/forgerelay/wiki) 查哪个。\n\nForgeRelay 默认直接用现有 checkout。它不会偷偷创建 worktree、复制 Git ignored 文件、安装 Language Server，也不捆绑 Codex、Claude Code、Pi 之类的本地 Coding Agent runtime。\n\n## 安全\n\nForgeRelay 给 Agent 的是真实本机执行权限，不是模拟环境。\n\n文件工具受 Workspace 和 allowed roots 限制；Shell 命令使用启动 ForgeRelay 的本地用户权限执行，**Shell 不是 OS sandbox**。因此只连接你信任的 MCP Host，只开放确实需要的项目目录，并保护好 Owner password。\n\nAllowed roots 是文件系统 / Workspace authority，不等于 Project Trust approval。项目中的可执行配置已经统一接入 Project execution trust seam；当前稳定策略仍是 compatibility-allow，完整的交互式 Project Trust approval UI 尚未实现。\n\nForgeRelay 默认拒绝 elevated / administrator 启动。只有你显式选择高权限运行时才会继续，并会提示系统级修改可能不可逆。\n\n完整边界见 [安全模型](https://github.com/Akira-TL/forgerelay/wiki/Security)。\n\n## 文档\n\n- [快速开始](https://github.com/Akira-TL/forgerelay/wiki/Getting-Started)\n- [配置](https://github.com/Akira-TL/forgerelay/wiki/Configuration)\n- [Managed Worktree](https://github.com/Akira-TL/forgerelay/wiki/Managed-Worktrees)\n- [ChatGPT 与 MCP 工作流](https://github.com/Akira-TL/forgerelay/wiki/ChatGPT-and-MCP-Workflow)\n- [External MCP](https://github.com/Akira-TL/forgerelay/wiki/External-MCP)\n- [安全模型](https://github.com/Akira-TL/forgerelay/wiki/Security)\n- [故障排查](https://github.com/Akira-TL/forgerelay/wiki/Troubleshooting)\n- [完整 Wiki](https://github.com/Akira-TL/forgerelay/wiki)\n\n> [!NOTE]\n> ForgeRelay 是基于 MIT License 的 [Waishnav/devspace](https://github.com/Waishnav/devspace) 独立衍生项目，不是官方 DevSpace Release。原始版权与 MIT License 保留在 [LICENSE](LICENSE)，来源与修改说明见 [NOTICE.md](NOTICE.md)。\n\n---\n\n# English\n\nForgeRelay is a self-hosted MCP server for a practical gap: hosts such as ChatGPT can write code, but they do not normally have access to the projects, shells, and Git repositories on your machine.\n\nOnce ForgeRelay is connected, an Agent can edit the repository you already use, run tests and builds, execute Git, query language servers, and call your existing local toolchain. There is no separate project copy and no requirement to adopt another coding-agent runtime.\n\n## Install\n\nForgeRelay requires Node.js `>=22.19 <27`, npm, and Git.\n\n```bash\nnpm install -g @akira-tl/forgerelay\nforgerelay init\nforgerelay serve\n```\n\nOr run it without a global install:\n\n```bash\nnpx @akira-tl/forgerelay init\nnpx @akira-tl/forgerelay serve\n```\n\nThe default MCP endpoint is:\n\n```text\nhttp://127.0.0.1:7676/mcp\n```\n\n`forgerelay init` asks which project roots may be opened and generates an Owner password. Use that password to approve an MCP client on its first connection.\n\nTo see the configuration and Command Shell Runtime ForgeRelay actually resolved:\n\n```bash\nforgerelay doctor\nforgerelay config check\nforgerelay config sources\nforgerelay config explain \n```\n\nForgeRelay's Config System resolves User, Project, and machine-private Project Local sources using `runtime > project-local > project > user > built-in`. External MCP, Language Servers, Hooks, and Subagent Profiles refresh on demand with last-known-good protection, and startup never rewrites legacy configuration automatically. See [Configuration](https://github.com/Akira-TL/forgerelay/wiki/Configuration) for scopes, migration, schemas, and diagnostics.\n\n### Host cannot reach localhost?\n\nCloud-hosted MCP clients need a public HTTPS route to ForgeRelay. Cloudflare Tunnel, ngrok, Tailscale Funnel, or a normal reverse proxy all work.\n\nFor a public base URL such as:\n\n```text\nhttps://forge.example.com/forgerelay\n```\n\nthe MCP client connects to:\n\n```text\nhttps://forge.example.com/forgerelay/mcp\n```\n\nSet `publicBaseUrl` before the final `/mcp`. See [Getting Started](https://github.com/Akira-TL/forgerelay/wiki/Getting-Started) for OAuth, tunnels, and reverse-proxy setup.\n\n## What using it looks like\n\nFor normal work, an Agent opens the checkout you already have:\n\n```text\nopen_workspace(path=\"~/project\")\n```\n\nIt can then work with files and run real local commands:\n\n```text\nread(path=\"src/server.ts\")\nbash(command=\"npm test\")\nbash(command=\"git status --short\")\n```\n\nForgeRelay does not create a worktree for every task. Managed worktrees are for cases where you explicitly want isolation or parallel development. A worktree may start from a local branch, tag, or historical commit SHA while keeping the eventual local `targetBranch` separate, so a temporary baseline branch is unnecessary.\n\nLong commands do not require tight polling either. Once the current wait window expires, ForgeRelay returns a stable `processId`; later calls wait on, interact with, or interrupt that same process.\n\n## Highlights\n\n- Files, shells, Git, tests, builds, and project scripts run on your machine.\n- Linux/macOS can use Bash, zsh, or POSIX sh. Windows has native PowerShell 7, Windows PowerShell 5.1, and `cmd.exe` support.\n- Reopening the same checkout reuses the same Workspace identity instead of creating another one for every conversation.\n- `code.intelligence` provides definition, hover, references, symbols, and diagnostics.\n- Agent context sources use Config v2: the default system instruction is `~/.agents/AGENTS.md`, project instructions match only `AGENTS.md` by default, and Skills scan `~/.agents/skills` then project `./.agents/skills`. Project/User/Project Local/runtime config can replace those generic sources; ForgeRelay no longer implicitly owns `.forgerelay/skills` sources.\n- Managed worktrees provide real Git isolation when you ask for parallel work. Starting commit and local `targetBranch` are tracked independently, while finalization remains fast-forward-only.\n- MCP Apps-capable hosts can render the Workspace Summary / Activity Panel. Workspace identity colors stay consistent between the panel and pretty logs, and long paths wrap in detail rows instead of hiding their tail.\n- Workspace Relay runs work on another ForgeRelay instance; Composite Workspaces coordinate several independent environments from one Host.\n- `read` can return PNG, JPEG, WebP, and GIF directly as transient MCP Media content; external MCP servers hot-reload from standalone global/Project `mcp.json` files into the `mcp.external` Capability, with explicit human OAuth when needed and no automatic dereferencing of returned paths or URLs.\n\nLifecycle Hooks, Workspace Tasks, local Subagents, Activity/Audit, checkpoints, and recovery are included too. They are optional parts of the workflow; the [Wiki](https://github.com/Akira-TL/forgerelay/wiki) documents them when you need them.\n\nBy default, ForgeRelay works in the checkout you already have. It does not silently create worktrees, copy Git-ignored files, install Language Servers, or bundle local coding runtimes such as Codex, Claude Code, or Pi.\n\n## Security\n\nForgeRelay gives an Agent real local execution capability.\n\nFilesystem tools are constrained by the opened Workspace and configured allowed roots. Shell commands run with the authority of the local user running ForgeRelay; **the shell is not an OS sandbox**. Connect only MCP hosts you trust, expose only project roots you want an Agent to access, and keep the Owner password private.\n\nAllowed roots grant filesystem/Workspace authority; they are not a Project Trust approval. Executable project configuration is routed through a shared Project execution trust seam; the current stable policy remains compatibility-allow, and a full interactive Project Trust approval UI is not implemented yet.\n\nElevated / administrator startup is rejected by default. It only proceeds after explicit opt-in, with a warning that system-level AI-driven changes may be irreversible.\n\nSee the [Security model](https://github.com/Akira-TL/forgerelay/wiki/Security) for the full boundary.\n\n## Documentation\n\n- [Getting Started](https://github.com/Akira-TL/forgerelay/wiki/Getting-Started)\n- [Configuration](https://github.com/Akira-TL/forgerelay/wiki/Configuration)\n- [Managed Worktrees](https://github.com/Akira-TL/forgerelay/wiki/Managed-Worktrees)\n- [ChatGPT and MCP Workflow](https://github.com/Akira-TL/forgerelay/wiki/ChatGPT-and-MCP-Workflow)\n- [External MCP](https://github.com/Akira-TL/forgerelay/wiki/External-MCP)\n- [Security model](https://github.com/Akira-TL/forgerelay/wiki/Security)\n- [Troubleshooting](https://github.com/Akira-TL/forgerelay/wiki/Troubleshooting)\n- [Full Wiki](https://github.com/Akira-TL/forgerelay/wiki)\n\n> [!NOTE]\n> ForgeRelay is an independently maintained derivative of the MIT-licensed [Waishnav/devspace](https://github.com/Waishnav/devspace) project. It is not an official DevSpace release. The original copyright and MIT License remain in [LICENSE](LICENSE); provenance and modification details are documented in [NOTICE.md](NOTICE.md).\n\n## Development\n\n```bash\nnpm install --include=dev\nnpm run dev\nnpm run debug:accept\nnpm run typecheck\nnpm test\nnpm run build\n```\n\n`npm run dev` uses the 7677 debug runtime. Product port 7676 is kept separate from development acceptance.\n\nRelease tags are created only after a developer has manually exercised and explicitly accepted the exact release-ready state. Automated verification and the Linux/macOS/Windows release matrix remain additional gates; they do not replace manual acceptance.\n","readmeFilename":"README.md"}
![\"ForgeRelay\"](\"docs/assets/forgerelay-lockup-dark.png\")
\n ![\"npm\"](\"https://img.shields.io/npm/v/%40akira-tl%2Fforgerelay?style=flat-square\")
![\"Release\"](\"https://img.shields.io/github/actions/workflow/status/Akira-TL/forgerelay/release.yml?style=flat-square&label=release\")
![\"License\"](\"https://img.shields.io/npm/l/%40akira-tl%2Fforgerelay?style=flat-square\")
![\"ForgeRelay](\"docs/assets/forgerelay-ui-preview.png\")
\n