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

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"
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

# 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?"

# 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

bun install -g github:ethan-huo/ghd