{ "markdown": "

gh-axi

\n\n

\n \"npm\"\n \"CI\"\n \"Release\"\n \"Platform\"\n \"X\"\n \"Discord\"\n

\n\nGitHub CLI for agents — designed with [AXI](https://github.com/kunchenguid/axi) (Agent eXperience Interface).\n\nWraps the official `gh` cli with token-efficient TOON output, contextual next-step suggestions, and structured error handling.\nBuilt for autonomous agents that interact with GitHub via shell execution.\n\n## Benchmarks\n\nAgent ergonomics is measurable.\nThe [axi benchmark](https://axi.md) runs the same 17 real-world GitHub tasks (issue triage, PR review prep, CI failure investigation, and more) through 5 GitHub interface setups - 5 repeats each, with `claude-sonnet-4-6` as the agent and an LLM judge scoring task success.\n\ngh-axi posts the lowest input tokens, cost, and duration of all 5 conditions, and is the only one to pass every run:\n\n| Condition | Avg Input Tokens | Avg Cost/Task | Avg Duration | Avg Turns | Success |\n| -------------------------- | ---------------- | ------------- | ------------ | --------- | -------- |\n| **gh-axi** | **46,462** | **$0.050** | **15.7s** | **3** | **100%** |\n| gh CLI (raw) | 47,076 | $0.054 | 17.4s | 3 | 86% |\n| GitHub MCP code execution | 137,409 | $0.101 | 43.4s | 7 | 84% |\n| GitHub MCP + ToolSearch | 153,621 | $0.147 | 41.1s | 8 | 82% |\n| GitHub MCP (eager schemas) | 175,757 | $0.148 | 34.2s | 6 | 87% |\n\nAgainst raw `gh` - the very CLI this tool wraps - that is 100% vs 86% task success at 7% lower cost.\nAgainst the GitHub MCP server it is 66% cheaper, with 74% fewer input tokens and half the turns.\n\n## Quick Start\n\nInstall the gh-axi skill in the [Agent Skills](https://agentskills.io) format with [`npx skills`](https://github.com/vercel-labs/skills):\n\n```sh\nnpx skills add kunchenguid/gh-axi --skill gh-axi -g\n```\n\nThat is the entire setup - no npm install needed.\nThe skill is a minimal discovery stub that directs your agent to the always-current `npx -y gh-axi` dashboard and help output instead of duplicating command guidance.\nYou still need [`gh`](https://cli.github.com/) installed and authenticated via `gh auth login` (Node 20+ required). gh-axi adds no new minimum `gh` version for existing commands. Only `--attach` on issue and pull request create/edit/comment requires **gh >= 2.99.0**; older `gh` returns a structured error before any mutation runs. Set `GH_BIN` to point at a specific `gh` binary.\nStacked PR commands also require GitHub's official extension: `gh extension install github/gh-stack`.\nFor GitHub Enterprise or another custom host, authenticate `gh` for that host and either pass `--hostname ` after the command or set `GH_HOST`.\n\nThe skill is not a user-facing slash command (`user-invocable: false`).\nIts frontmatter also includes Hermes Agent metadata (`metadata.hermes`) so Hermes can categorize it as a `devops` skill for GitHub, git, CI, pull requests, releases, and projects.\nJust ask for anything that touches GitHub - filing issues, reviewing PRs, checking CI runs, cutting releases, managing Projects boards, or managing GitHub Actions secrets and variables - and the agent loads the skill on its own when it recognizes the task.\n\n`-g` installs the skill for all projects (`~/.claude/skills/`, for example); drop it to install for the current project only (`.claude/skills/`).\n\n## Other Ways to Install\n\nThe skill is the recommended path, but it is not the only one.\n\n### Zero setup\n\ngh-axi is an AXI, so any capable agent can run the CLI directly with nothing installed at all.\nJust tell your agent:\n\n```\nExecute `npx -y gh-axi` to get GitHub tools.\n```\n\n### Session hook\n\nWant ambient GitHub context - the current repo's open issues and PRs - fed into every agent session instead of loading on demand?\nInstall the CLI globally and opt into the hook:\n\n```sh\nnpm install -g gh-axi\ngh-axi setup hooks\n```\n\nThis installs a `SessionStart` hook for **Claude Code**, **Codex**, and **OpenCode** that surfaces the current repo state and usage guidance at the start of each session.\n**Restart your agent session after running this** so the new hook takes effect.\nFor global installs, run `gh-axi update --check` to see whether a newer release is available, or `gh-axi update` to upgrade.\n\n## Usage\n\n```bash\ngh-axi # dashboard - live state, no args needed\ngh-axi issue list # list issues in current repo\ngh-axi issue subissue list 16 # list sub-issues for issue #16\ngh-axi pr view 42 # view pull request #42\ngh-axi stack init model api ui # create or adopt a stack of branches\ngh-axi stack submit --open # create ready-for-review stacked PRs without prompts\ngh-axi stack view # inspect the current stack as token-efficient TOON\ngh-axi issue edit 42 --add-label bug --add-label chore # repeat a flag per value\ngh-axi run list -R owner/repo # list workflow runs for a specific repo\ngh-axi issue list --hostname git.example.com # target a GitHub Enterprise host\ngh-axi run view 123456 --job 789012 # inspect a single job within a run\ngh-axi run view --job 789012 --log-failed # show failed log lines for one job\ngh-axi workflow run ci.yml --ref main # trigger a workflow\ngh-axi project list --owner my-org # list Projects (v2) for an owner\necho -n \"sk-...\" | gh-axi secret set OPENAI_API_KEY # set a secret from stdin\necho -n \"sk-...\" | gh-axi secret set CSC_LINK --env production # scope a secret to an environment\ngh-axi variable set NODE_ENV --body production # set a variable from a flag\ngh-axi gist list # list your gists\ngh-axi gist list --public # list only public gists\ngh-axi gist view # view a gist's files and content\necho 'new content' | gh-axi gist edit --filename notes.md # replace a file from stdin\ngh-axi gist edit --remove old.txt # remove a file\ngh-axi gist rename old.txt new.txt # rename a file\ngh-axi gist create notes.md --public --desc \"My notes\" # create a public gist\ngh-axi gist create --file a.py --file b.py --secret # create a secret multi-file gist\necho \"content\" | gh-axi gist create --filename hello.txt --public # create from piped content\ngh-axi gist delete # delete a gist (always confirmed non-interactively)\ngh-axi gist clone # clone a gist locally\ngh-axi setup hooks # install optional agent session hooks\ngh-axi update --check # check whether a newer release exists\ngh-axi update # upgrade a global install\n```\n\nFor multi-line issue, PR, review, or comment text, write Markdown to a UTF-8 file and pass `--body-file ` on the relevant command.\nFor releases, `--body` and `--body-file` are aliases for release notes, alongside `--notes` and `--notes-file`.\nFor multi-line variable values, pipe stdin to `gh-axi variable set `; `--body`/`-b` is for inline values only.\n\n`--attach ` is repeatable on `issue` and `pr` `create`, `edit`, and `comment` (not `pr review`). It uploads a local image or video through the same `gh --attach` mechanism (requires **gh >= 2.99.0**) and inlines it in the Markdown body. If the body already references the local path, `gh` replaces that reference with the uploaded URL; otherwise it appends the attachment. Alt text is `path#alt` for images; videos cannot take alt text. Supported types: PNG, JPEG, GIF, WebP, SVG, MP4, MOV, WebM. Size limits match GitHub's web upload: 10 MB for images and GIFs, 10 MB for video on Free, 100 MB for video on paid plans. GitHub Enterprise Server is not supported in this gh release. Successful output names each attached file and only the `user-attachments` asset URLs uploaded by that invocation. Override the wrapped `gh` binary with `GH_BIN`.\n\nThe label, assignee, reviewer, and project flags of `issue create`/`edit` and `pr create`/`edit` are repeatable: pass the flag once per value and every value reaches `gh`.\n`issue list` and `pr list` accept repeated `--label` filters the same way.\nA repeated flag with a missing or empty value (`--add-label` with nothing after it, or `--add-label=`) fails with a validation error instead of being silently dropped.\n\nIn `gh-axi issue list` and `gh-axi pr list`, the `count: N of M total` line counts only what the filters you passed (`--label`, `--assignee`, `--author`, and the other list filters) match, not every issue or PR in the repository.\nWhen a total cannot be expressed faithfully — a numeric `--milestone`, since search matches milestone titles only, or a filter value containing a double quote, which search has no way to escape — gh-axi omits it and falls back to `showing first N` rather than printing a number that does not match the query.\nA total smaller than the page it accompanies is dropped the same way, since GitHub's search index lags behind freshly created issues and pull requests and can undercount them.\n\nLong `run view --log` and `run view --log-failed` output shows the last 20,000 characters so CI failures stay visible.\nWhen truncation happens, gh-axi best-effort saves the complete log to a temp file, includes it as `full_log`, and prints a `help:` hint telling agents to grep that file for earlier context.\n`gh-axi run` manages existing workflow runs; use `gh-axi workflow run --ref ` to trigger (dispatch) a workflow.\n\n`gh-axi pr checks ` and the `checks` summary of `gh-axi pr view ` bucket every entry of the PR's status-check rollup as `pass`, `fail`, `skip`, or `pending`, covering both check runs (GitHub Actions and similar) and legacy commit statuses (Vercel, `ci/circleci`, and similar).\nCancelled, stale, timed-out, action-required, and startup-failure check runs count as failed, so a red PR is never reported as merely unfinished.\n\n`gh-axi stack` is a strict, non-interactive adapter over the official `github/gh-stack` extension. It supports `view`, `init`, `add`, `checkout`, `push`, `submit`, `sync`, `rebase`, `link`, `unstack`, `merge`, and branch navigation. It intentionally excludes the interactive `modify` and `switch` TUIs and the human-only `alias` and `feedback` utilities.\nStack commands operate on local branches and `.git/gh-stack`, so run them from the target repository's working directory. They reject `-R`, `--repo`, and `GH_REPO` rather than pretending a remote repository is enough. `--hostname` remains available for authenticated GitHub Enterprise hosts.\nAgent-safe behavior is automatic: `stack view` requests JSON, `stack submit` adds `--auto`, and `stack merge` requires an explicit stack or PR target and adds `--yes`. Rebase conflicts and other extension exits retain their original exit codes and include recovery guidance.\n\n`gh-axi secret set ` reads the value only from piped stdin because secret flags would be visible in the `gh-axi` process argv.\n`gh-axi secret list` never prints values, matching `gh secret list`.\n`gh-axi secret list`, `set`, and `delete` accept `--env`/`-e ` to scope a secret to a deployment environment; without it the repository scope is used.\nOther `gh secret` scopes (`--org`, `--user`, `--app`) are rejected with a clear error rather than silently falling back to the repository scope.\n`gh-axi variable` accepts `--body`/`-b` or piped stdin, and variable values are shown in `list` output because variables are not secret.\n`gh-axi project` wraps GitHub Projects (v2) and requires the `project` (or `read:project`) OAuth scope; if a call fails on a missing scope, gh-axi tells you the `gh auth refresh -s ` command to run.\n`--owner` defaults to the current repo's owner, falling back to explicit `@me` for the authenticated user.\n\n`gh-axi gist create` requires `--public` or `--secret` explicitly — passing neither (or both) is an error.\nGist visibility is fixed at creation; a secret gist is unlisted (anyone with the URL can read it), not private.\nTwo file-on-disk input forms are available: positional paths (`gist create a.py b.py`) or repeatable `--file` flags (`gist create --file a.py --file b.py`); mixing the two is an error.\nTo create a gist from piped content, use `--filename ` together with a pipe (`echo \"...\" | gh-axi gist create --filename foo.txt --public`).\n\n`gh-axi api` accepts `-X ` and `-X=` as alternatives to the positional HTTP method, plus `--field`, `--header`, `--input `, `--paginate`, `--jq `, `--template `, and `--full`.\nUse `--input ` to send a raw JSON request body, or `--input -` to relay piped stdin byte for byte.\n`--input -` rejects an interactive terminal instead of waiting for input.\nGiving `-X` more than once or together with a positional method is rejected, as is any other unsupported flag, extra positional argument, or repeated `--input`/`--jq`/`--template`.\nJSON responses are normally stripped of noisy fields before TOON encoding, but a response you shaped yourself with `--jq` or `--template` keeps every key and value verbatim — only over-long strings are still truncated so one field cannot flood an agent's context.\n`--full` is an explicit opt-in escape hatch: it keeps every field and every complete value, and it also returns non-JSON response bodies without the length cap. `--full` is a gh-axi flag only, and gh-axi does not send it to `gh`. Compact output stays the default without `--full`.\n\n### Commands\n\n| Command | Description |\n| ---------- | --------------------------------------------------------------------------- |\n| `issue` | Issues — list, view, create, edit, close, reopen, comment, subissue |\n| `pr` | Pull requests — list, view, create, merge, review, checks |\n| `stack` | Stacked branches and PRs - create, submit, sync, rebase, merge, navigate |\n| `run` | Existing workflow runs - list, view, watch, rerun, cancel, delete, download |\n| `workflow` | Workflows - list, view, run (trigger), enable, disable |\n| `release` | Releases — list, view, create, edit, delete |\n| `repo` | Repositories — list, view, create, edit, clone, fork |\n| `label` | Labels — list, create, edit, delete |\n| `gist` | Gists — list, view, edit, rename, create, delete, clone |\n| `project` | Projects (v2) - list, view, create, edit, close, copy, items, fields |\n| `secret` | Actions secrets — list, set, delete |\n| `variable` | Actions variables — list, set, delete |\n| `search` | Search issues, PRs, repos, commits, code |\n| `api` | Raw GitHub API access |\n| `setup` | Install optional agent session hooks |\n| `update` | Built-in self-update command inherited from `axi-sdk-js` |\n\n### Global flags\n\n- `--help` — show help for any command\n- `-v`, `-V`, `--version` — show the installed `gh-axi` version\n- `--hostname ` / `--hostname=` — target a custom GitHub host; explicit flags win over `GH_HOST`\n\nRepository and host targeting are command-first too:\n\n- `gh-axi issue list -R owner/name`\n- `gh-axi issue list --repo owner/name`\n- `gh-axi issue list --repo=owner/name`\n- `gh-axi run list -R owner/name`\n- `gh-axi repo view --repo owner/name`\n- `gh-axi search issues \"login bug\" --repo owner/name`\n- `gh-axi issue list --hostname git.example.com`\n\n`repo view` also accepts exactly one positional repository, `gh-axi repo view owner/name`, as a repo-view-specific compatibility exception for `gh repo view []`. Do not combine that positional form with `--repo`, and do not pass extra positional arguments. For other commands, use the command-first `--repo owner/name` form.\n\nWhen a command also needs a destination repository, use a dedicated flag for it:\n\n- `gh-axi issue transfer 42 -R source/repo --to-repo dest/repo`\n\n## Development\n\n```sh\npnpm run build # Compile TypeScript to dist/\npnpm run build:skill # Regenerate skills/gh-axi/SKILL.md from src/skill.ts\npnpm run dev # Run CLI directly with tsx\npnpm test # Run tests with vitest\npnpm run test:watch # Run tests in watch mode\n```\n\nThe committed `skills/gh-axi/SKILL.md` is generated from `src/skill.ts` by `pnpm run build:skill`; `pnpm test` fails if the generated file drifts.\nThe generated skill intentionally defers all command guidance to the CLI dashboard and help output so installed copies do not duplicate stale instructions.\nThe npm package includes `skills/gh-axi/`, so published releases ship the same installable Agent Skill documented in Quick Start.\n\n## License\n\nMIT\n", "bytes": 18053, "sha": "b3131f6d2df6b18d432b728426689a52f905d6cd7b1fa7da162fabe1eb2c836e", "repo_slug": "kunchenguid/gh-axi", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/skl_kunchenguid_gh_axi_gh_axi_74ca856d/readme" }