codex-github-router 0.2.0

Codex GitHub Router

Codex GitHub Router (cgr) is a small .NET CLI that connects Codex sessions with GitHub Issues and Pull Requests. It installs a Codex UserPromptSubmit hook, finds the next actionable workflow item, prioritizes existing review or change-request work, and can prevent new work from starting while an earlier item still requires attention.

CGR turns a labeled GitHub workflow (ready → working → done) into router decisions. When you ask Codex to "work on the next task", the hook checks the repository state and delivers the additional context Codex needs: which issue to take, whether an in-progress issue must be resumed, whether a pull request is waiting on a change request, and so on. It intentionally keeps at most one active coding claim per repository so multiple sessions and worktrees agree on who owns the work.

Requirements

• .NET 10 runtime
• GitHub CLI installed and authenticated (gh auth status)
• Codex CLI with hooks support
• A GitHub repository that uses the configured issue and pull-request labels

Installation

dotnet tool install --global codex-github-router --version 0.1.0-alpha
cgr --version

See docs/getting-started.md for the full install, update, and uninstall lifecycle.

Quick start

# 1. Check GitHub authentication
gh auth status

# 2. Initialize the router (creates the default configuration and registers the Codex hook)
cgr init

# 3. Enable autonomous mode for your repository (provisions missing workflow, gate, and worker labels)
cgr auto on

# 4. Confirm the environment and repository are healthy
cgr doctor

After enabling autonomous mode, prompts submitted to Codex inside the repository are routed according to the workflow. Codex may need to be restarted after cgr init changes its hooks configuration. A five-minute walkthrough lives in docs/getting-started.md.

Basic usage

Run these commands from a Git repository connected to GitHub:

cgr --help
cgr issue list
cgr issue list --state InProgress
cgr pr list
cgr auto status
cgr work status
cgr config validate
cgr doctor

Troubleshooting

Start with cgr doctor. It is strictly read-only and reports independent PASS / WARN / FAIL checks across the environment (version, .NET runtime, Git, GitHub CLI, hooks, global configuration) and the repository (override, effective configuration, autonomous mode, work claim, labels, worker routing). Exit codes: 0 for all-pass or warnings-only, 1 when any required setup fails, 2 for usage errors.

cgr doctor
cgr doctor --model gpt-5-codex

See docs/troubleshooting.md for step-by-step recovery guidance.

How it works (lifecycle overview)

1. Codex submits a user prompt and the installed cgr hook fires on UserPromptSubmit.
2. CGR checks autonomous mode and the activation policy (always, or an exact prompt gate).
3. CGR reconciles the repository work claim, then routes the prompt:
   • an active claim owned by the current session continues that work,
   • a change-requested pull request is prioritized,
   • an in-progress issue is resumed before new work,
   • otherwise the next ready issue is claimed and started.
4. The hook returns additional context to Codex (or a block decision with a reason), and writes a diagnostic record for troubleshooting.

Workflow and pull-request labels, worker routing, repository gates, and diagnostics are all configurable. See docs/configuration.md and docs/scenarios.md.

Documentation

• Getting started — install, setup, uninstall lifecycle
• Configuration reference — defaults, overrides, effective merge, validation
• Scenarios — common workflows with copyable examples
• Troubleshooting — doctor-first recovery guidance
• Roadmap — intended capabilities

Current scope and limitations

• At most one active coding claim per repository, shared across worktrees.
• CGR never starts a second issue, branch, or pull request while work is active.
• Autonomous mode is repository-specific and stored in the shared Git common directory.
• The router relies on GitHub labels to model state; conflicting labels are treated as an ambiguous state and block the hook.
• PR review itself is not a claimable work type yet; change requests on linked pull requests are.

See docs/roadmap.md for the intended future capabilities.

Development

dotnet restore CodexGithubRouter.slnx
dotnet build CodexGithubRouter.slnx -c Release --no-restore
dotnet run --project src/CodexGithubRouter -- --help
dotnet test CodexGithubRouter.slnx -c Release

The default test suite runs deterministic unit tests and sandboxed integration tests without requiring GitHub, a network connection, or a live user configuration. CI validates Release builds on Linux (ubuntu-latest) and Windows (windows-latest); macOS is not a required CI platform.

Releases

Releases are published manually from the current main head through the Release NuGet package GitHub Actions workflow. NuGet publication uses Trusted Publishing with a short-lived OIDC-backed API key; the release environment can enforce approvals. The checked-in project version is 0.0.1-dev; the release workflow supplies the resolved version so package metadata and cgr --version stay aligned. See docs/getting-started.md for the supported update and uninstall order.

License

Codex GitHub Router is licensed under the MIT License.