Skip to content
claude-code-tools

github-watch: wake on GitHub comment

github-wake registers an existing GitHub issue and wakes the originating session when its first future comment arrives:

Terminal window
github-wake https://github.com/OWNER/REPOSITORY/issues/123

Create the issue separately with gh issue create or another GitHub client. Run github-wake only when the current session is genuinely waiting for a reply. The command verifies the issue, records a durable watch, and starts one shared per-user watcher daemon.

The github-wake command comes from the Python package (uv tool install claude-code-tools) and talks to GitHub through an installed, authenticated GitHub CLI (gh auth login). The skill that tells the agent how to use it works in Claude Code and Codex only (those are the two delivery paths) and installs with npx skills add pchalasani/claude-code-tools -s github-wake (it is also part of the dynamic-workflow plugin).

Codex

Section titled “Codex”

Run github-wake ISSUE_URL from the Codex session’s own shell (in practice, ask Codex to watch the issue and the installed skill runs it). The command reads the session’s thread from CODEX_THREAD_ID and, when the reply arrives, delivers it with Codex’s native message queue:

Terminal window
codex queue --thread THREAD --message ...

This needs a Codex CLI that has the codex queue command. The queue runs under the session’s Codex account directory. Codex does not export CODEX_HOME to tool shells, so github-wake picks the one ~/.codex* directory that holds the thread’s session. When none or several do, registration fails and asks for the directory explicitly:

Terminal window
github-wake --codex-home ~/.codex-rja https://github.com/OWNER/REPOSITORY/issues/123

An idle Codex session starts a new turn as soon as the reply is queued. A session in the middle of a turn receives the reply when that turn ends.

Claude Code

Section titled “Claude Code”

In Claude Code 2.1.98 or later, ask Claude to watch the issue with github-wake; the installed skill runs the following command through Claude’s Monitor tool:

Terminal window
github-wake --claude-monitor https://github.com/OWNER/REPOSITORY/issues/123

The Monitor tool must own this command. Running it through Bash would block a tool call instead of feeding the reply asynchronously into the conversation. Claude Code monitors stop when their session ends and are not restored when a session resumes.

How it works

Section titled “How it works”

The GitHub polling and durable state are agent-neutral. Separate delivery adapters send the event through either codex queue or Claude Code’s live Monitor process without replacing the shared watcher.

The daemon polls once per GitHub repository, even when many sessions have pending watches. It uses conditional GitHub requests, overlapping time windows, bounded pagination, and retry-safe cursors. Those safeguards reduce API use without losing comments that appear late in GitHub’s repository-wide index.

When the first future comment arrives, the daemon sends a normalized reply to the recorded session. The comment is wrapped as untrusted data, so its contents do not become trusted agent instructions.

Watcher controls

Section titled “Watcher controls”
Terminal window
github-wake --status
github-wake --status --json
github-wake --start
github-wake --stop
github-wake --cancel WATCH_ID

The daemon stores state under $XDG_STATE_HOME/claude-code-tools/github-watch, or ~/.local/state/claude-code-tools/github-watch when XDG_STATE_HOME is unset. It records a GitHub configuration directory rather than an access token, so personal and work gh configurations can share the same daemon without writing credentials into watcher state.