{"id":46261146,"url":"https://github.com/aryeko/ghx","last_synced_at":"2026-03-14T03:10:40.225Z","repository":{"id":338181631,"uuid":"1156710734","full_name":"aryeko/ghx","owner":"aryeko","description":"Typed GitHub capability router for AI agents. Deterministic CLI + GraphQL execution with normalized results.","archived":false,"fork":false,"pushed_at":"2026-03-03T23:55:29.000Z","size":4042,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T04:04:17.384Z","etag":null,"topics":["agentic","ai-agents","api-router","automation","cli","developer-tools","github","github-api","github-cli","graphql","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/aryeko/ghx#readme","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aryeko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T00:48:36.000Z","updated_at":"2026-03-03T23:52:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aryeko/ghx","commit_stats":null,"previous_names":["aryeko/ghx-router","aryeko/ghx"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/aryeko/ghx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryeko%2Fghx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryeko%2Fghx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryeko%2Fghx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryeko%2Fghx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aryeko","download_url":"https://codeload.github.com/aryeko/ghx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryeko%2Fghx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30479944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T23:57:05.347Z","status":"ssl_error","status_checked_at":"2026-03-13T23:56:58.046Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","ai-agents","api-router","automation","cli","developer-tools","github","github-api","github-cli","graphql","typescript"],"created_at":"2026-03-04T01:35:02.522Z","updated_at":"2026-03-14T03:10:40.213Z","avatar_url":"https://github.com/aryeko.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ghx\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/branding/social/ghx-social-dark-1280x640.png\" alt=\"ghx social preview\" width=\"480\"\u003e\n\u003c/p\u003e\n\n\u003e GitHub execution router for AI agents.\n\u003e One typed capability interface over `gh` CLI + GraphQL.\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#4A90D9', 'primaryTextColor': '#fff', 'primaryBorderColor': '#2E6BA4', 'lineColor': '#666', 'fontSize': '13px'}}}%%\nsequenceDiagram\n    participant Agent\n    participant ghx as ghx\n    participant GH as GitHub API\n\n    Agent-\u003e\u003eghx: executeTask(\"pr.view\", { owner, name, prNumber })\n\n    Note over ghx: 1. Validate input schema\u003cbr/\u003e2. Select optimal route (GraphQL/CLI)\u003cbr/\u003e3. Run preflight checks\n    ghx-\u003e\u003eGH: typed GraphQL request\n    GH--\u003e\u003eghx: response\n    Note over ghx: normalize errors \u0026 structure\n\n    ghx--\u003e\u003eAgent: ResultEnvelope { ok: true, data: { ... } }\n```\n\n[![CI (main)](https://github.com/aryeko/ghx/actions/workflows/ci-main.yml/badge.svg)](https://github.com/aryeko/ghx/actions/workflows/ci-main.yml)\n[![codecov](https://codecov.io/gh/aryeko/ghx/graph/badge.svg?token=KBIGR138V7)](https://codecov.io/gh/aryeko/ghx)\n[![npm version](https://img.shields.io/npm/v/%40ghx-dev%2Fcore)](https://www.npmjs.com/package/@ghx-dev/core)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n`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.\n\n## 30-Second Quick Start\n\nRequirements: Node.js `22+`, `gh` CLI authenticated, `GITHUB_TOKEN` or `GH_TOKEN` in env.\n\n```bash\nnpx @ghx-dev/core capabilities list\nnpx @ghx-dev/core capabilities explain repo.view\nnpx @ghx-dev/core run repo.view --input '{\"owner\":\"aryeko\",\"name\":\"ghx\"}'\n```\n\nOr install globally:\n\n```bash\nnpm i -g @ghx-dev/core\nghx capabilities list\nghx run repo.view --input '{\"owner\":\"aryeko\",\"name\":\"ghx\"}'\n```\n\nAgent onboarding (Claude Code skill):\n\n```bash\nnpx @ghx-dev/core setup --scope project --yes\nnpx @ghx-dev/core setup --scope project --verify\n```\n\n## Who is this for?\n\n- **Claude Code users** -- install with `ghx setup --scope project` and get deterministic GitHub operations\n- **Cursor / Windsurf users** -- point your agent at `ghx capabilities list` for structured tool use\n- **Custom agent builders** -- import `createExecuteTool()` for typed GitHub access in your own agent framework\n\n## The Problem\n\nAgents instructed to \"use `gh` CLI\" for GitHub operations waste significant tokens on research, trial-and-error, and output parsing:\n\n- **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.\n- **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.\n- **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.\n\n## Before / After\n\n**WITHOUT ghx** -- agent submitting a PR review with inline comments (15 tool calls, 126s):\n\n```bash\ngh pr view 42 --repo acme/repo                          # read PR\ngh pr diff 42 --repo acme/repo                          # read diff\ngh api POST reviews -f event=REQUEST_CHANGES \\           # attempt 1: 422 error\n  -f 'comments[0][path]=src/stats.ts' ...\nnoglob gh api POST reviews ...                           # attempt 2: 422 error\npython3 -c \"import json; ...\" | gh api --input -         # attempt 3: no inline comments\ngh api POST reviews/comments -f path=src/stats.ts ...    # attempt 4-6: individual comments\ngh api POST reviews -f event=REQUEST_CHANGES             # attempt 7: submit event\ngh pr view 42 --json reviews                             # verify\n```\n\n**WITH ghx** -- same task (2 tool calls, 26s):\n\n```bash\nghx chain --steps - \u003c\u003c'EOF'\n[\n  {\"task\":\"pr.diff.view\",\"input\":{\"owner\":\"acme\",\"name\":\"repo\",\"prNumber\":42}},\n  {\"task\":\"pr.view\",\"input\":{\"owner\":\"acme\",\"name\":\"repo\",\"prNumber\":42}}\n]\nEOF\nghx run pr.reviews.submit --input - \u003c\u003c'EOF'\n{\n  \"owner\": \"acme\", \"name\": \"repo\", \"prNumber\": 42,\n  \"event\": \"REQUEST_CHANGES\",\n  \"body\": \"Found blocking issues.\",\n  \"comments\": [\n    {\"path\": \"src/stats.ts\", \"line\": 4, \"body\": \"Empty array guard missing.\"},\n    {\"path\": \"src/stats.ts\", \"line\": 8, \"body\": \"Missing await on fetch.\"},\n    {\"path\": \"src/stats.ts\", \"line\": 12, \"body\": \"Hardcoded credential.\"}\n  ]\n}\nEOF\n```\n\n## Benchmarked Performance\n\nThree-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.\n\n| Scenario | Tool calls | Active tokens | Latency |\n| --- | --- | --- | --- |\n| Reply to unresolved review threads | **-73%** | **-18%** | **-54%** |\n| Review and comment on PR | **-71%** | **-18%** | **-54%** |\n\nFull methodology, per-iteration data, and statistical analysis: [Evaluation Report](docs/eval-report.md)\n\n## Chain: Batch Operations\n\n`ghx chain` batches multiple operations into a single tool call. One command, batched execution, three operations:\n\n```bash\nghx chain --steps - \u003c\u003c'EOF'\n[\n  {\"task\":\"issue.labels.remove\",\"input\":{\"owner\":\"acme\",\"name\":\"repo\",\"issueNumber\":42,\"labels\":[\"triage\",\"feature-request\"]}},\n  {\"task\":\"issue.labels.add\",\"input\":{\"owner\":\"acme\",\"name\":\"repo\",\"issueNumber\":42,\"labels\":[\"enhancement\"]}},\n  {\"task\":\"issue.comments.create\",\"input\":{\"owner\":\"acme\",\"name\":\"repo\",\"issueNumber\":42,\"body\":\"Triaged -- tracking as enhancement.\"}}\n]\nEOF\n```\n\nAgents 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.\n\n## Example Output\n\n```json\n{\n  \"ok\": true,\n  \"data\": {\n    \"id\": \"...\",\n    \"name\": \"ghx\",\n    \"nameWithOwner\": \"aryeko/ghx\"\n  },\n  \"error\": null,\n  \"meta\": {\n    \"capability_id\": \"repo.view\",\n    \"route_used\": \"cli\",\n    \"reason\": \"CARD_PREFERRED\"\n  }\n}\n```\n\n## Golden Workflow: CI Diagnosis\n\nDiagnose a failing CI run, read logs, rerun, and merge:\n\n```bash\nghx run workflow.run.view --input '{\"owner\":\"acme\",\"name\":\"repo\",\"runId\":123456}'\nghx run workflow.job.logs.view --input '{\"owner\":\"acme\",\"name\":\"repo\",\"jobId\":789012}'\nghx run workflow.run.rerun.failed --input '{\"owner\":\"acme\",\"name\":\"repo\",\"runId\":123456}'\nghx run pr.checks.list --input '{\"owner\":\"acme\",\"name\":\"repo\",\"prNumber\":14}'\nghx run pr.merge --input '{\"owner\":\"acme\",\"name\":\"repo\",\"prNumber\":14,\"method\":\"squash\"}'\n```\n\n## Capabilities\n\n70+ capabilities across 6 domains ([full list](packages/core/docs/reference/capabilities.md)).\n\n## Security and Permissions\n\n- Use least-privilege tokens and only grant scopes needed for the capabilities you execute.\n- For fast local evaluation, a classic PAT with `repo` scope is the simplest path.\n- 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.\n- `ghx` reads `GITHUB_TOKEN` or `GH_TOKEN` from environment.\n\n## Packages\n\n- `@ghx-dev/core` (`packages/core`) -- public npm package; CLI + execution engine\n- `@ghx-dev/agent-profiler` (`packages/agent-profiler`) -- private; generic AI agent session profiler\n- `@ghx-dev/eval` (`packages/eval`) -- private; evaluation harness for ghx benchmarking\n\n## Documentation\n\nFull documentation lives in [`docs/`](docs/README.md):\n\n- **[Core Documentation](packages/core/docs/README.md)** -- Getting started, architecture, capabilities, guides\n- **[Agent Profiler](packages/agent-profiler/docs/README.md)** -- Profiler architecture, guides, API reference\n- **[Eval Harness](packages/eval/docs/README.md)** -- Evaluation methodology, scenarios, fixtures\n- **[Contributing](CONTRIBUTING.md)** -- Development setup, testing, CI, publishing\n- **[Repository Structure](docs/repository-structure.md)** -- Monorepo layout and module organization\n- Branding assets: `assets/branding/README.md`\n\n## Roadmap\n\nCurrent roadmap priorities and capability batches are tracked in `ROADMAP.md`.\n\n## Contributing\n\nSee `CONTRIBUTING.md` for local setup, test commands, and PR expectations.\n\nTooling notes for local development:\n\n- `gh` CLI is required for CLI-backed execution paths (`gh auth status`).\n- `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`.\n\n```bash\ngit clone https://github.com/aryeko/ghx.git \u0026\u0026 cd ghx\n./scripts/setup-dev-env.sh\npnpm install\npnpm run build\npnpm run ci\n```\n\n## License\n\nMIT © Arye Kogan\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faryeko%2Fghx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faryeko%2Fghx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faryeko%2Fghx/lists"}