gl-axi is a GitLab CLI built for coding agents, following the AXI (Agent eXperience Interface) approach. It wraps the official glab CLI rather than replacing it: authentication, host, and project resolution stay in glab, while gl-axi reshapes issue, merge request, CI, repository, label, milestone, release, and API responses into compact output that an agent can read cheaply and act on right away.

The AXI idea comes from kunchenguid/axi.

Benchmarks

The pitch behind gl-axi is that an agent gets more done with less context, so rather than just claiming that, we measured it. The accuracy benchmark hands an agent the same 17 real-world GitLab tasks twice: once in a plain environment with only glab installed, and once with the gl-axi session hook feeding it ambient project context. The tasks range from quick reads like listing issues and checking pipelines up to full release-readiness reviews and a file-and-close issue workflow. Both runs use claude-sonnet-4-6 as the agent, and an LLM judge grades whether each task actually succeeded.

Both setups finish all 17 tasks, so the interesting question becomes what the work costs. With gl-axi, the same tasks cost 30% less in total, consume 39% fewer marginal input tokens (the tokens billed after prompt caching), and finish in fewer turns without a single tool-friction error:

| Condition | Success | Total cost | Marginal input tokens | Output tokens | Total response time | Avg turns | Tool-friction errors | | --- | --- | --- | --- | --- | --- | --- | --- | | gl-axi (ambient context) | 17/17 | $0.55 | 20,353 | 5,585 | 166s | 2.8 | 0 | | Raw GitLab (glab) | 17/17 | $0.79 | 33,177 | 6,851 | 210s | 3.6 | 3 |

It also matters where the savings land. Most of the catalog is quick read work, and there gl-axi trims total cost by 27%. On the three heavy multi-step workflows, which are exactly the kind of task that dominates a real agent's bill, the saving grows to 37%:

| Task slice | Tasks | Raw GitLab total cost | gl-axi total cost | Cost reduction | | --- | ---: | ---: | ---: | ---: | | Simple / read-heavy | 14 | $0.52 | $0.38 | 27% | | Heavy workflows | 3 | $0.27 | $0.17 | 37% |

Everything else is held equal between the two runs: same tasks, same model, same target project, with hook evidence recorded for every task. The full methodology and reproduction commands are in docs/benchmark-accuracy-workflow.md.

Quick Start

Run without installing:

npx -y gl-axi dashboard -R group/subgroup/project

Install globally:

npm install -g gl-axi
gl-axi setup hooks

The second command installs the SessionStart hook for Claude Code, Codex, and OpenCode through axi-sdk-js. With the hook in place, every new agent session opens with the same ambient GitLab context the benchmark above measured. Restart your agent session afterwards so the hook takes effect.

Requirements

• Node.js 22 or newer.
• The official glab CLI installed and authenticated with glab auth login.

Agent Skill

If your agent runtime supports skills, the skill is the best setup path. The npm package ships it at skills/gl-axi/SKILL.md, and it teaches the agent the command map, the dashboard-first workflow, project targeting, glab authentication expectations, and the issue mutation rules before the first GitLab call. Because the skill invokes the CLI through npx -y gl-axi, nothing needs to be installed from npm on that path.

The skill is optional, though. Any capable agent can run npx -y gl-axi dashboard -R <project-path> to catch up on a project and follow the help[] suggestions from there.

Usage

gl-axi dashboard -R group/subgroup/project   # live project state, content-first
gl-axi issue list                            # open issues in the current project
gl-axi issue view 42                         # one issue, compact schema
gl-axi mr view 7                             # one merge request
gl-axi ci list                               # recent pipelines
gl-axi ci get 2647388436                      # one pipeline by id
gl-axi job trace 9001                        # bounded, failure-focused job log
gl-axi commands --brief                      # runtime command discovery

Commands

| Command | Description | | --- | --- | | dashboard | Live repository state — issues, MRs, pipelines, releases | | issue | Issues — list, view, create, close, reopen | | mr | Merge requests — list, view | | ci | Pipelines — lint config, list, get/view | | job | CI jobs — view, trace, retry, cancel | | repo | Repositories — view, list, search, contributors | | label | Labels — list, get | | milestone | Milestones — list, get | | release | Releases — list, view | | api | Narrow GitLab API escape hatch | | setup | Install agent session hooks | | commands | Compact command discovery (--brief) |

When the skill, the command map, and the help[] suggestions all fail to point at the next step, gl-axi commands --brief lists the supported command families, output modes, and examples without making a live GitLab call.

Project targeting

Use -R/--repo <project-path> on any command to target another GitLab project:

gl-axi issue list -R group/subgroup/project
gl-axi mr view 7 --repo group/project
gl-axi api projects/:fullpath/issues -R group/project

Output modes

Read commands print compact TOON-style text by default, with explicit empty states instead of blank output and contextual help[] suggestions appended. When an agent needs structured data instead, detail and mutation commands accept --json:

gl-axi issue view 42 --json
gl-axi ci lint .gitlab-ci.yml --json
gl-axi release view v1.0.0 --json

API escape hatch

First-class commands cover the common ground, and gl-axi api handles the rest. It shells out to glab api, strips the noisy fields GitLab includes in every response, and renders a compact api_response. Reach for it only when no first-class command fits:

gl-axi api projects/:fullpath/issues -R group/project
gl-axi api POST projects/:fullpath/issues -R group/project -F 'title=Fix docs'
gl-axi api graphql -X POST -F 'query=...' -F 'variables[fullPath]=group/project'

CI Job Diagnostics

gl-axi ci lint validates .gitlab-ci.yml (or an explicit CI config source) through glab ci lint. Add --dry-run --ref <ref> when you want GitLab to simulate the expanded pipeline, and --include-jobs when the resulting job names are useful follow-up context.

To look at a pipeline that already ran, gl-axi ci get takes the id either positionally or as --pipeline-id, and ci view, pipeline view, and pipeline get are aliases for the same command:

gl-axi ci get 2647388436 -R group/project
gl-axi ci get --pipeline-id 2647388436 -R group/project

From there, job view inspects a single CI job and job trace pulls a bounded, failure-focused slice of its log rather than the whole thing. job retry and job cancel are the mutation half: both are non-interactive and check the job's current state before acting.

gl-axi ci lint .gitlab-ci.yml --dry-run --ref main --include-jobs -R group/project
gl-axi job view 9001 -R group/project
gl-axi job trace 9001 -R group/project
gl-axi job retry 9001 -R group/project

Issue Mutations

Issue mutations are kept deliberately narrow, and each one maps directly to glab: issue create, issue close, and issue reopen.

issue create is the one to treat with care, because it is not duplicate-safe. Check existing issues first with issue list or issue view, then create with a title and an optional description; --description-file takes a markdown file, which suits generated bodies:

gl-axi issue create --title "Fix package docs" --description-file prd.md

issue close and issue reopen, by contrast, are repeat-safe. Both read the issue before touching it, so closing an already-closed issue or reopening an already-open one succeeds quietly instead of erroring. A closing comment is posted before the state change:

gl-axi issue close 42 --comment-file close-note.md

Reopens are additionally verified after the fact, so the compact output reflects the issue's real state:

gl-axi issue reopen 42

Development

npm run build                     # compile TypeScript to dist/
npm test                          # build + run node --test suite
npm run benchmark:tokens:report   # fixture-based token benchmark report
npm run verify:package            # verify the publishable package surface

Accuracy benchmark commands and workflow are documented in docs/benchmark-accuracy-workflow.md.

License

MIT