Why ghx?

When AI agents use the gh CLI directly, they waste thousands of tokens on research, trial-and-error formatting, and guessing JSON parsing paths. ghx eliminates this waste by providing a stable, structured execution layer.

100% success rate, 73% fewer tool calls, 18% fewer active tokens, 54% lower latency compared to raw CLI usage (measured across 30 runs on standard PR workflows with Codex 5.3).

Read the full motivation: AI Agents Shouldn't Relearn GitHub on Every Run

sequenceDiagram
    participant Agent
    participant ghx as ghx
    participant GH as GitHub API

    %% Agent requests a typed execution
    Agent->>ghx: executeTask("pr.view", { owner, name, prNumber })
    
    %% ghx routing engine takes over
    Note over ghx: 1. Validate input schema<br/>2. Select optimal route (GraphQL/CLI)<br/>3. Run preflight checks
    ghx->>GH: typed GraphQL request
    GH-->>ghx: response
    Note over ghx: normalize errors & structure
    
    %% Stable envelope returned
    ghx-->>Agent: ResultEnvelope { ok: true, data: { ... } }

Features

• 70+ Declarative Capabilities: PRs, issues, labels, workflows, projects, releases — all defined by versioned YAML operation cards.
• Deterministic Routing: The agent doesn't choose CLI vs. GraphQL. ghx evaluates suitability rules and picks the optimal route automatically, with built-in fallbacks.
• Stable Result Envelope: No try/catch needed. Every execution returns { ok, data, error, meta }. Errors are mapped to standard codes (AUTH, RATE_LIMIT, NOT_FOUND, etc.).
• Chaining & Batching: Execute multiple steps (add label, add assignee, comment) in one call. ghx resolves node IDs and batches them into a single network request.
• Type Safety: Full TypeScript schemas for inputs and outputs (via generated GraphQL types).

Documentation

Comprehensive documentation is available in the docs/ directory:

• Getting Started — Installation, why ghx, and use case diagrams.
  • Library Quickstart
  • CLI Quickstart
  • Agent Setup
• Concepts — How ghx works internally (Routing Engine, Operation Cards, Result Envelope, Chaining).
• Architecture — System design, execution pipeline, formatters, and GraphQL layer.
• Reference — API exports, error codes, and a complete table of all 70+ capabilities.

Install

npm i -g @ghx-dev/core

This makes the ghx CLI available in your PATH. Then wire it into your agent (see Agent Integration below).

For library usage (TypeScript imports), install as a project dependency instead:

npm install @ghx-dev/core

Quick Start (Library)

import { createGithubClientFromToken, executeTask } from "@ghx-dev/core"

const token = process.env.GITHUB_TOKEN!
const githubClient = createGithubClientFromToken(token)

// Execute a task: input is validated, optimal route is chosen
const result = await executeTask(
  { task: "repo.view", input: { owner: "aryeko", name: "ghx" } },
  { githubClient, githubToken: token },
)

if (result.ok) {
  console.log("Success:", result.data.nameWithOwner)
  console.log("Route used:", result.meta.route_used) // e.g. "graphql"
} else {
  console.error("Failed:", result.error.code) // e.g. "NOT_FOUND"
  console.error("Retryable?", result.error.retryable)
}

Quick Start (CLI)

Use ghx directly from your terminal or add it as an agent skill.

# List all 70+ capabilities
ghx capabilities list

# Run a capability
ghx run pr.view --input '{"owner":"aryeko","name":"ghx","prNumber":42}'

# Output is a standard ResultEnvelope:
# {
#   "ok": true,
#   "data": { ... },
#   "meta": { "capability_id": "pr.view", "route_used": "graphql", ... }
# }

Agent Integration

Claude Code -- install from the plugin marketplace:

/plugin marketplace add aryeko/ghx
/plugin install ghx@ghx-dev

Cursor, Windsurf, Codex, other agents -- install the skill:

ghx setup --scope user --yes

This writes SKILL.md to ~/.agents/skills/using-ghx/ which teaches your agent how to use ghx for reliable GitHub interactions. See Agent Setup for platform-specific wiring.

License

MIT