⚓ firstmate field guide
The AXI ecosystem

The AXI tools firstmate uses

gh-axi, chrome-devtools-axi, tasks-axi, quota-axi and lavish-axi — install, core commands, and exactly where firstmate calls each one.

Tool Role in firstmate Floor Required
gh-axi every GitHub read and write by workers and merge checks 0.1.29 yes
chrome-devtools-axi browser work by workers presence yes
tasks-axi the backlog (data/backlog.md) and captain holds 0.2.6 + capability probes yes
quota-axi quota-aware dispatch among candidate profiles 0.1.51 yes
lavish-axi visual boards, plans and reviews 0.1.77 optional

Each floor is enforced by one owner file (bin/fm-bootstrap.sh, bin/fm-tasks-axi-lib.sh, bin/fm-quota-axi-lib.sh), so a version bump is one edit. An incompatible required tool blocks the capability it backs. It doesn't degrade silently. The one designed degradation is lavish-axi, which falls back to plain text.

All of them install the same way:

npx skills add kunchenguid/<tool> --skill <tool> -g      # skill only
npm install -g <tool> && <tool> setup hooks              # binary + SessionStart ambient context
npx -y <tool>                                            # zero setup, slower

-g installs the skill for all projects. The skills CLI may print PromptScript does not support global skill installation even when the install worked for your other agents; check for <tool>/SKILL.md in the agent's skills directory (for example ~/.claude/skills/) to confirm. Drop -g for a per-project install (.claude/skills/).

gh-axi#

gh-axi is a GitHub CLI for agents. It wraps gh, so gh auth login must be done first, and needs Node 20+.

gh-axi                                  # dashboard: live state, no args
gh-axi pr view 42
gh-axi issue list
gh-axi issue edit 42 --add-label bug
gh-axi run view 123456 --job 789012 --log-failed
gh-axi workflow run ci.yml --ref main
gh-axi stack init model api ui && gh-axi stack submit --open     # stacked PRs (needs gh-stack ext)
echo -n "sk-..." | gh-axi secret set OPENAI_API_KEY

Multi-line bodies go through --body-file <path|->, never an editor.

In firstmate:

  • fm-dod-lib.sh requires gh-axi pr view <n> to confirm draft: no (and runs gh-axi pr ready if needed) before a no-mistakes PR counts as ready.
  • fm-teardown.sh resolves a branch's PR with gh-axi pr list --state all --head <branch>.
  • fm-pr-merge.sh falls back to gh-axi pr view for the post-merge read.

chrome-devtools-axi#

chrome-devtools-axi wraps chrome-devtools-mcp behind an AXI CLI.

$ chrome-devtools-axi open https://example.com
page: {title: "Example Domain", url: "https://example.com", refs: 1}
snapshot:
RootWebArea "Example Domain"
  heading "Example Domain"
  uid=g1:1 link "More information..."
help[1]: Run `chrome-devtools-axi click @g1:1` to click the "More information..." link

$ chrome-devtools-axi click @g1:1

Refs carry a generation prefix (g1:). A stale ref fails loudly with STALE_REF instead of silently doing nothing. The skill tells agents to re-verify state changes with a fresh snapshot before claiming success. It scored 100% in the browser benchmark at the lowest cost (AXI).

tasks-axi#

tasks-axi is a task and backlog manager for agents. It edits a hand-editable backlog.md in place with a byte-exact round-trip. It borrows the dependency graph and ready-query model from beads.

Every backlog mutation today regenerates markdown through the model, which is expensive output tokens and risks dropped, duplicated, or reordered items. — tasks-axi README

tasks-axi                                     # dashboard: in_flight, summary, queued, done
tasks-axi add fix-login-q3 "fix flaky login test" --kind ship --repo xyz --priority 2 --start
tasks-axi done fix-login-q3 --pr https://github.com/you/xyz/pull/42
tasks-axi block a-task --by other-task
tasks-axi hold a-task --reason "captain decision pending" --kind captain
tasks-axi unhold a-task
tasks-axi ready [--include-held]
tasks-axi show a-task --full
tasks-axi update a-task --body "rewritten" --archive-body
tasks-axi prune --keep 10                     # archives, never deletes
tasks-axi mv a b --to ../other-home/data/backlog.md   # atomic multi-ID move

In firstmate:

  • .tasks.toml points it at data/backlog.md with done_keep = 10.
  • Captain holds are tasks-axi holds (--kind captain).
  • Secondmate handoffs always use tasks-axi mv.
  • Firstmate probes the actual --help surface for --archive-body and multi-ID mv, not just the version.
  • config/backlog-backend=manual opts a home out for routine edits.

quota-axi#

Your agent needs to be aware of your quota.

It reports quota windows for Claude, Codex, Cursor, Copilot, Grok, Kimi, Z.AI, Alibaba, OpenCode Go, Antigravity, MiniMax, DeepSeek, OpenRouter, Devin, Muse and more, in one call. It is data only. It never routes, recommends, proxies or logs in. It is local-first and hits first-party endpoints only.

$ npx -y quota-axi --provider claude,codex,cursor,grok
quota[n]{provider,scope,effectivePercentRemaining,spendPriority,runway,confidence,limitedBy,resetsAt}: ...
exhaustion[n]{provider,scope,usableRunwaySeconds,projectedExhaustedAt,limitingWindowId}: ...
attention[n]{provider,scope,kind,detail,remedy}: ...
help[1]: Run `quota-axi --full` for windows, pace, reserve, and account evidence
  • To read native secure stores (the macOS Keychain, etc.), grant consent once with quota-axi --allow-keychain-prompt.
  • Kun also mentions a human dashboard, quota-axi --tui.
  • In firstmate: the quota-array-dispatch skill ranks candidate worker profiles by spendPriority after its eligibility, reasoning-class and runway gates. See Scaling.

lavish-axi#

HTML is the new markdown. Lavish is the new editor for your HTML artifacts. — @kunchenguid, 2026-05-12

Lavish opens agent-generated HTML locally. You annotate elements or selected text, edit Mermaid diagrams, and click buttons, and your feedback goes back to the agent. At launch Kun wired in Tailwind and daisyUI, because "almost half of tokens while generating HTML are spent on stylesheets". Current versions no longer auto-inject them. The agent picks a design direction from lavish-axi design (the DESIGN_PRIORITY_RULE), and the packaged assets stay available for older artifacts (docs/invariants.md).

npx skills add kunchenguid/lavish-axi --skill lavish
npm install -g lavish-axi && lavish-axi setup hooks     # or: setup plugin (VS Code / Cursor / Copilot CLI)
lavish-axi plan.html            # open or attach a review session
lavish-axi plan.html --reopen

Kun's use: "i just ask the agent 'review the PR with me in lavish'... key decisions are then rendered as buttons and inputs for me to quickly decide."

In firstmate:

  • /bearings lavish builds the interactive fleet board at $FM_HOME/.lavish/bearings-board.html (bin/fm-bearings-board.sh). "A live session is proved, never assumed."
  • bin/fm-procevent-lavish.sh turns board clicks into process events. Decision answers feed fm-captain-hold.sh answers.
  • Missing or old → PRESENTATION_UNAVAILABLE, and everything continues in plain text.
  • config/lavish-axi-host sets a per-machine server address.
  1. node, git, gh + gh auth login
  2. no-mistakes (see no-mistakes)
  3. gh-axi, chrome-devtools-axi (with setup hooks)
  4. tasks-axi
  5. quota-axi (+ --allow-keychain-prompt if needed)
  6. your backend's tool + treehouse (skip treehouse for Orca)
  7. optional: lavish-axi

In practice you can skip the manual steps. The first mate's bootstrap lists exactly what's missing and installs the supported ones after one "yes".

Unofficial guide built 2026-09-26 from kunchenguid/firstmate, the AXI repos, and Kun Chen's public posts. The repo moves daily; when this guide and the repo disagree, the repo wins.