https://github.com/aryeko/ghx
Typed GitHub capability router for AI agents. Deterministic CLI + GraphQL execution with normalized results.
https://github.com/aryeko/ghx
agentic ai-agents api-router automation cli developer-tools github github-api github-cli graphql typescript
Last synced: 6 days ago
JSON representation
Typed GitHub capability router for AI agents. Deterministic CLI + GraphQL execution with normalized results.
- Host: GitHub
- URL: https://github.com/aryeko/ghx
- Owner: aryeko
- License: mit
- Created: 2026-02-13T00:48:36.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-03-03T23:55:29.000Z (16 days ago)
- Last Synced: 2026-03-04T04:04:17.384Z (16 days ago)
- Topics: agentic, ai-agents, api-router, automation, cli, developer-tools, github, github-api, github-cli, graphql, typescript
- Language: TypeScript
- Homepage: https://github.com/aryeko/ghx#readme
- Size: 3.85 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# ghx
> GitHub execution router for AI agents.
> One typed capability interface over `gh` CLI + GraphQL.
```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#4A90D9', 'primaryTextColor': '#fff', 'primaryBorderColor': '#2E6BA4', 'lineColor': '#666', 'fontSize': '13px'}}}%%
sequenceDiagram
participant Agent
participant ghx as ghx
participant GH as GitHub API
Agent->>ghx: executeTask("pr.view", { owner, name, prNumber })
Note over ghx: 1. Validate input schema
2. Select optimal route (GraphQL/CLI)
3. Run preflight checks
ghx->>GH: typed GraphQL request
GH-->>ghx: response
Note over ghx: normalize errors & structure
ghx-->>Agent: ResultEnvelope { ok: true, data: { ... } }
```
[](https://github.com/aryeko/ghx/actions/workflows/ci-main.yml)
[](https://codecov.io/gh/aryeko/ghx)
[](https://www.npmjs.com/package/@ghx-dev/core)
[](https://opensource.org/licenses/MIT)
`ghx` helps agents execute GitHub tasks without re-discovering API surfaces on every run. Agents call stable capabilities like `repo.view` or `pr.merge`; ghx handles route choice, retries, fallbacks, and normalized output.
## 30-Second Quick Start
Requirements: Node.js `22+`, `gh` CLI authenticated, `GITHUB_TOKEN` or `GH_TOKEN` in env.
```bash
npx @ghx-dev/core capabilities list
npx @ghx-dev/core capabilities explain repo.view
npx @ghx-dev/core run repo.view --input '{"owner":"aryeko","name":"ghx"}'
```
Or install globally:
```bash
npm i -g @ghx-dev/core
ghx capabilities list
ghx run repo.view --input '{"owner":"aryeko","name":"ghx"}'
```
Agent onboarding (Claude Code skill):
```bash
npx @ghx-dev/core setup --scope project --yes
npx @ghx-dev/core setup --scope project --verify
```
## Who is this for?
- **Claude Code users** -- install with `ghx setup --scope project` and get deterministic GitHub operations
- **Cursor / Windsurf users** -- point your agent at `ghx capabilities list` for structured tool use
- **Custom agent builders** -- import `createExecuteTool()` for typed GitHub access in your own agent framework
## The Problem
Agents instructed to "use `gh` CLI" for GitHub operations waste significant tokens on research, trial-and-error, and output parsing:
- **Array parameter syntax is fragile.** Submitting a PR review with inline comments via `gh api` requires `comments[0][path]`, `comments[][body]`, or heredoc piping. Agents try 3-15 syntaxes before one works.
- **API surface re-discovery every session.** Each new session, the agent figures out which `gh` subcommands exist, what `--json` fields are available, and how to format GraphQL queries from scratch.
- **Output shapes vary by endpoint.** REST, GraphQL, and `gh` CLI each return different structures. The agent spends tokens parsing and normalizing before it can reason about results.
## Before / After
**WITHOUT ghx** -- agent submitting a PR review with inline comments (15 tool calls, 126s):
```bash
gh pr view 42 --repo acme/repo # read PR
gh pr diff 42 --repo acme/repo # read diff
gh api POST reviews -f event=REQUEST_CHANGES \ # attempt 1: 422 error
-f 'comments[0][path]=src/stats.ts' ...
noglob gh api POST reviews ... # attempt 2: 422 error
python3 -c "import json; ..." | gh api --input - # attempt 3: no inline comments
gh api POST reviews/comments -f path=src/stats.ts ... # attempt 4-6: individual comments
gh api POST reviews -f event=REQUEST_CHANGES # attempt 7: submit event
gh pr view 42 --json reviews # verify
```
**WITH ghx** -- same task (2 tool calls, 26s):
```bash
ghx chain --steps - <<'EOF'
[
{"task":"pr.diff.view","input":{"owner":"acme","name":"repo","prNumber":42}},
{"task":"pr.view","input":{"owner":"acme","name":"repo","prNumber":42}}
]
EOF
ghx run pr.reviews.submit --input - <<'EOF'
{
"owner": "acme", "name": "repo", "prNumber": 42,
"event": "REQUEST_CHANGES",
"body": "Found blocking issues.",
"comments": [
{"path": "src/stats.ts", "line": 4, "body": "Empty array guard missing."},
{"path": "src/stats.ts", "line": 8, "body": "Missing await on fetch."},
{"path": "src/stats.ts", "line": 12, "body": "Hardcoded credential."}
]
}
EOF
```
## Benchmarked Performance
Three-mode comparison (baseline vs MCP vs ghx) across 30 runs (2 scenarios, 5 iterations each, 3 modes) with Codex 5.3. ghx achieved 100% success rate.
| Scenario | Tool calls | Active tokens | Latency |
| --- | --- | --- | --- |
| Reply to unresolved review threads | **-73%** | **-18%** | **-54%** |
| Review and comment on PR | **-71%** | **-18%** | **-54%** |
Full methodology, per-iteration data, and statistical analysis: [Evaluation Report](docs/eval-report.md)
## Chain: Batch Operations
`ghx chain` batches multiple operations into a single tool call. One command, batched execution, three operations:
```bash
ghx chain --steps - <<'EOF'
[
{"task":"issue.labels.remove","input":{"owner":"acme","name":"repo","issueNumber":42,"labels":["triage","feature-request"]}},
{"task":"issue.labels.add","input":{"owner":"acme","name":"repo","issueNumber":42,"labels":["enhancement"]}},
{"task":"issue.comments.create","input":{"owner":"acme","name":"repo","issueNumber":42,"body":"Triaged -- tracking as enhancement."}}
]
EOF
```
Agents use chain to collapse multi-step workflows (label swap + comment, bulk thread resolve + reply, etc.) into a single tool call instead of sequential shell commands.
## Example Output
```json
{
"ok": true,
"data": {
"id": "...",
"name": "ghx",
"nameWithOwner": "aryeko/ghx"
},
"error": null,
"meta": {
"capability_id": "repo.view",
"route_used": "cli",
"reason": "CARD_PREFERRED"
}
}
```
## Golden Workflow: CI Diagnosis
Diagnose a failing CI run, read logs, rerun, and merge:
```bash
ghx run workflow.run.view --input '{"owner":"acme","name":"repo","runId":123456}'
ghx run workflow.job.logs.view --input '{"owner":"acme","name":"repo","jobId":789012}'
ghx run workflow.run.rerun.failed --input '{"owner":"acme","name":"repo","runId":123456}'
ghx run pr.checks.list --input '{"owner":"acme","name":"repo","prNumber":14}'
ghx run pr.merge --input '{"owner":"acme","name":"repo","prNumber":14,"method":"squash"}'
```
## Capabilities
70+ capabilities across 6 domains ([full list](packages/core/docs/reference/capabilities.md)).
## Security and Permissions
- Use least-privilege tokens and only grant scopes needed for the capabilities you execute.
- For fast local evaluation, a classic PAT with `repo` scope is the simplest path.
- For production agents, prefer fine-grained tokens with read permissions first (`Metadata`, `Contents`, `Pull requests`, `Issues`, `Actions`, `Projects`) and add write permissions only where required.
- `ghx` reads `GITHUB_TOKEN` or `GH_TOKEN` from environment.
## Packages
- `@ghx-dev/core` (`packages/core`) -- public npm package; CLI + execution engine
- `@ghx-dev/agent-profiler` (`packages/agent-profiler`) -- private; generic AI agent session profiler
- `@ghx-dev/eval` (`packages/eval`) -- private; evaluation harness for ghx benchmarking
## Documentation
Full documentation lives in [`docs/`](docs/README.md):
- **[Core Documentation](packages/core/docs/README.md)** -- Getting started, architecture, capabilities, guides
- **[Agent Profiler](packages/agent-profiler/docs/README.md)** -- Profiler architecture, guides, API reference
- **[Eval Harness](packages/eval/docs/README.md)** -- Evaluation methodology, scenarios, fixtures
- **[Contributing](CONTRIBUTING.md)** -- Development setup, testing, CI, publishing
- **[Repository Structure](docs/repository-structure.md)** -- Monorepo layout and module organization
- Branding assets: `assets/branding/README.md`
## Roadmap
Current roadmap priorities and capability batches are tracked in `ROADMAP.md`.
## Contributing
See `CONTRIBUTING.md` for local setup, test commands, and PR expectations.
Tooling notes for local development:
- `gh` CLI is required for CLI-backed execution paths (`gh auth status`).
- `opencode` CLI is only required if you run E2E suites locally (`pnpm run test:e2e`); CI installs it via `curl -fsSL https://opencode.ai/install | bash`.
```bash
git clone https://github.com/aryeko/ghx.git && cd ghx
./scripts/setup-dev-env.sh
pnpm install
pnpm run build
pnpm run ci
```
## License
MIT © Arye Kogan