kunchenguid/gh-axi

gh‑axi – a GitHub‑CLI wrapper built for autonomous AI agents

What it is

• gh‑axi is a Node‑based command‑line tool that sits on top of the official GitHub CLI (gh).
• It is designed for AI agents that need to interact with GitHub programmatically, offering token‑efficient output (TOON encoding), structured error messages, and next‑step suggestions.
• The tool is part of the AXI (Agent eXperience Interface) ecosystem, which standardises how agents discover and use capabilities.

Why it matters for agents

• Agents often have tight token budgets when calling large language models. gh‑axi reduces the amount of data the LLM has to process by compressing CLI output and by presenting only the information an agent needs to decide the next action.
• It provides deterministic, machine‑readable responses (JSON, concise status codes) instead of the free‑form, human‑oriented output of the raw gh CLI.
• Built‑in error handling and validation let the agent react to failures without having to parse ambiguous terminal messages.

Key capabilities

Area	What you can do with gh‑axi
Issues & PRs	List, view, create, edit, comment, add labels/assignees/reviewers, attach files (images, videos) – all with repeatable flags for multiple values.
Stacks	Full non‑interactive wrapper around the github/gh‑stack extension for stacked PR workflows (init, view, submit, merge, rebase, etc.).
Workflows & Runs	List, view, trigger, cancel, download logs of GitHub Actions runs; logs are truncated but a full copy is saved to a temp file for the agent to grep.
Projects (v2)	List, view, create, edit, close, copy, manage items and fields – with clear guidance when OAuth scopes are missing.
Secrets & Variables	Set secrets (stdin‑only for security), list/delete them, and manage repository‑wide variables.
Gists	List, view, create (public or secret), edit, rename, delete, and clone gists, with strict flag validation.
Raw API	Direct access to any GitHub REST endpoint via gh‑axi api, supporting custom HTTP methods, headers, JSON bodies, pagination, jq filtering, templating, and a “full” mode that disables output truncation.
Repo & Search	Standard repository commands (list, view, clone, fork) and powerful search across issues, PRs, code, commits.
Session hooks	Optional hooks that automatically surface the current repository’s state to agents like Claude Code, Codex, or OpenCode at the start of each session.

Agent‑friendly design details

• Token‑efficient TOON output – a compact representation that keeps the LLM’s context window small.
• Structured JSON for commands that need machine‑readable data (e.g., stack view, run view).
• Repeatable flags (e.g., --add-label) ensure every value is passed through to the underlying gh command, avoiding silent drops.
• Validation errors are explicit; missing or empty flag values cause a clear error instead of being ignored.
• Deterministic exit codes – the wrapper forwards the original gh exit codes, preserving the semantics agents rely on.
• Self‑update – agents can run gh‑axi update to keep the tool current without external package managers.

Installation & usage

1. Agent‑skill install (recommended):

   npx skills add kunchenguid/gh-axi --skill gh-axi -g
   

   This registers a lightweight “skill” that points agents to the latest npx -y gh-axi dashboard.
2. Zero‑setup – any capable agent can just execute npx -y gh-axi.
3. Global install (for manual use):

   npm install -g gh-axi
   gh-axi setup hooks   # optional session hooks
   

   The tool then works like any other CLI (gh‑axi <command> …).

Typical workflow for an agent

1. Agent decides it needs to triage an issue.
2. It runs gh‑axi issue list --label bug --assignee @me.
3. The tool returns a concise, token‑light list of matching issues.
4. Agent picks an issue and runs gh‑axi issue comment 42 --body-file ./reply.md.
5. If the comment includes an image, the agent adds --attach ./screenshot.png and the tool uploads the file via the underlying gh binary.

Benchmarks

• In the AXI benchmark (17 real‑world GitHub tasks, Claude‑Sonnet‑4‑6 as the agent), gh‑axi achieved 100 % success, the lowest average input tokens (≈46 k), lowest cost (≈ $0.05 per task), and fastest average duration (≈ 15.7 s) compared to raw gh and other GitHub‑MCP‑based interfaces.

Who should use it

• Developers building autonomous DevOps agents, AI‑assisted code reviewers, or any LLM‑driven workflow that needs reliable, low‑overhead GitHub interaction.
• Teams that already use the AXI ecosystem and want a drop‑in skill for GitHub operations.

License: MIT.