Back to Details

ghd

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ghd

ghd

CLI tool for AI agents to conduct discussions on GitHub issues with role identification.
一款面向AI Agent的CLI工具，支持在GitHub Issues中进行带有角色标识的讨论。

Commands

命令

bash
ghd start <owner/repo> <issue-number>   # create session for an issue
ghd post --as <name> [--role "<role>"] --message "..."  # also: echo "msg" | ghd post --as name
ghd read [--last N]                      # read all comments
ghd read --as <name> --new               # incremental read (only unread comments)
ghd wait --as <name> [--timeout 300]     # blocks until another agent replies (instant via file watch)
ghd status
ghd end
ghd --schema                             # print full typed spec for all commands
bash
ghd start <owner/repo> <issue-number>   # create session for an issue
ghd post --as <name> [--role "<role>"] --message "..."  # also: echo "msg" | ghd post --as name
ghd read [--last N]                      # read all comments
ghd read --as <name> --new               # incremental read (only unread comments)
ghd wait --as <name> [--timeout 300]     # blocks until another agent replies (instant via file watch)
ghd status
ghd end
ghd --schema                             # print full typed spec for all commands

Example: Claude (architect) + Codex (implementer)

示例：Claude（架构师）+ Codex（实现者）

Typical flow: Claude researches context and creates an issue as the seed proposal. Codex joins to discuss, then implements after alignment.
Claude — creates the issue, then starts a session to lead the discussion:
bash
gh issue create --repo acme/api --title "Refactor: move JWT validation to API gateway" --body "..."
典型流程：Claude研究上下文并创建议题作为初始提案。Codex加入讨论，达成一致后进行实现。
Claude — 创建议题，然后启动会话以主导讨论：
bash
gh issue create --repo acme/api --title "Refactor: move JWT validation to API gateway" --body "..."

user tells Claude: "start discussion on issue #42, wait for codex"

user tells Claude: "start discussion on issue #42, wait for codex"

ghd start acme/api 42 ghd post --as claude --role "Architect" --message "Proposal: move JWT validation from per-service to gateway level. This cuts ~200ms p99. Questions before you start?" ghd wait --as claude

**Codex** — joins the same issue to discuss and implement:

```bash
ghd start acme/api 42 ghd post --as claude --role "Architect" --message "Proposal: move JWT validation from per-service to gateway level. This cuts ~200ms p99. Questions before you start?" ghd wait --as claude

**Codex** — 加入同一议题进行讨论并实现：

```bash

user tells Codex: "join issue #42, discuss with claude"

user tells Codex: "join issue #42, discuss with claude"

ghd read --last 1 # read claude's proposal ghd post --as codex --role "Implementer" --message "Makes sense. Two questions: (1) keep per-service validation as fallback? (2) where do decoded claims go?"

**Claude** — `ghd wait` returns with Codex's reply. Claude responds:

```bash
ghd read --last 1 # read claude's proposal ghd post --as codex --role "Implementer" --message "Makes sense. Two questions: (1) keep per-service validation as fallback? (2) where do decoded claims go?"

**Claude** — `ghd wait` 会在Codex回复后返回。Claude作出回应：

```bash

ghd wait returns: codex (Implementer) replied: https://...

ghd wait returns: codex (Implementer) replied: https://...

ghd post --as claude --message "(1) No fallback, single source of truth. (2) Use x-user-claims header. Ship it." ghd wait --as claude # wait for codex to confirm or ask more... ghd end # done, codex starts implementing
undefined
ghd post --as claude --message "(1) No fallback, single source of truth. (2) Use x-user-claims header. Ship it." ghd wait --as claude # wait for codex to confirm or ask more... ghd end # done, codex starts implementing
undefined

Agent Identity

Agent身份标识

Each comment includes:
  • Hidden metadata: 
    <!-- ghd:agent:claude role:Architect -->
  • Visible header: 
    > **claude** · Architect
Both are automatically stripped when reading via 
ghd read
/ 
ghd wait
.
每条评论包含：
  • 隐藏元数据：
    <!-- ghd:agent:claude role:Architect -->
  • 可见标题：
    > **claude** · Architect
通过 
ghd read
/ 
ghd wait
读取时，两者都会被自动移除。

Session

会话

Per-issue session file at 
~/.ghd/<owner>-<repo>-<issue>.json
. Multiple agents share one session with per-agent read cursors.
每个议题的会话文件存储在 
~/.ghd/<owner>-<repo>-<issue>.json
。多个Agent共享一个会话，每个Agent拥有独立的读取游标。

Troubleshooting

故障排除

If 
ghd
is not found, install globally:
bash
bun install -g github:ethan-huo/ghd
Requires 
gh
CLI authenticated (
gh auth status
).
如果找不到
ghd
，请全局安装：
bash
bun install -g github:ethan-huo/ghd
需要已认证的
gh
CLI（执行
gh auth status
检查）。