setup

ax:setup

Install and verify ax - the local agent-experience graph. After this skill the user has the ax CLI on PATH, an ingested local graph (embedded DuckDB, no daemon to run or watch), and the ax skills loaded into Claude Code.

This skill is intentionally narrow: install + verify only. For day-to-day use see ax:retro (experiment loop), ax:extract-workflow (reconstruct the recipe behind a shipped artifact), or run the CLI directly.

When to fire

Trigger phrases:

• "install ax" / "set up ax" / "first-time ax setup"
• "ax not found" / "where is axctl"
• "ax doctor" / "is ax running" / "is ax working"
• "what does ax give me"

Do NOT auto-trigger on unrelated work or when the user is already deep in an ax workflow (ax improve list, ax recall …).

Install

# 1. Download the installer and inspect it before executing. Review the target
#    paths first; this repository does not publish a checksum for install.sh.
(
    set -eu
    ax_install_dir="$(mktemp -d "${TMPDIR:-/tmp}/ax-install.XXXXXXXX")"
    trap 'rm -f "$ax_install_dir/install.sh"; rmdir "$ax_install_dir"' EXIT
    curl -fsSL https://raw.githubusercontent.com/Necmttn/ax/main/install.sh -o "$ax_install_dir/install.sh"
    less "$ax_install_dir/install.sh"
    read -r -p "Execute this installer? [y/N] " answer
    case "$answer" in
        [yY][eE][sS]|[yY]) bash "$ax_install_dir/install.sh" ;;
        *) echo "Installer not run."; exit 1 ;;
    esac
)

Continue only after the installer completes successfully. A failed download, failed review command, declined approval, or end of input stops installation. Agents inspect the downloaded file and obtain approval before executing that same file. The private directory prevents another local user replacing it.

# 2. Review the skill changes and confirm before installing into the selected
#    agent skill directory. Omit -g unless a global install is intentional.
npx skills add Necmttn/ax -a codex

# 3. First ingest - seeds the graph from the user's last 7 days of
#    Claude Code + Codex transcripts.
PATH="$HOME/.local/bin:$PATH" ax ingest --since=7

If any step fails, run ax doctor --json and surface the blocker. If ax itself isn't found after step 1, the user probably has a custom shell rc - tell them to add $HOME/.local/bin to PATH.

Verify

ax --version              # expect axctl v0.1.x
ax doctor --json          # expect ok: true for cache + skills
ax skills taste --limit=5 # rank top skills - proof the graph populated

Specific failure modes:

• cache check fails / no successful ingest recorded → run ax ingest. There is no daemon to start - the graph is a published DuckDB snapshot, rebuilt on demand. A stale graph also self-heals: any DB-backed command forks a debounced background ax ingest on its own (AX_NO_AUTO_INGEST=1 to opt out).
• Zero skill invocations after ingest → user has a different Claude transcripts path. Set AX_TRANSCRIPTS_DIR and re-ingest.

Label skills ax can't classify (do this for the user)

ax tags skills with roles (e.g. framing, execution, verification) so ax skills weighted ranks by usage × role, not raw count. A skill the user invokes ≥3× with no role is "unclassified" - ax hands each one back to YOU as a task brief to fill. This is the core agent-in-the-loop step; don't skip it.

ax skills classify        # writes .ax/tasks/classify-<skill>.md per unclassified skill

For each brief written:

1. Read the skill (its SKILL.md / what it does) and the brief's evidence.
2. Fill the YAML frontmatter at the top of the brief: primary_role: (required, one label), plus optional secondary:, confidence: (0–1), rationale:. Run ax roles to see labels already in use; reuse them when they fit.
3. Apply + check:

ax skills lint            # reads filled briefs → writes plays_role edges
ax skills weighted        # the re-ranked list, now role-weighted

If classify reports "no unclassified skills", the user hasn't used enough yet - say so and revisit after a few days (re-run ax ingest, or let the freshness drive top it up automatically). One-off override without a brief: ax skills tag <skill> <role>.

Also surface the config front door when relevant:

• ax skills config - skill lifecycle (live / orphan / out-of-scope / parked).
• ax hooks config - hooks across claude/cursor/codex/opencode (+ add/remove/edit).
• ax hooks init - scaffold ~/.ax/hooks for authoring custom TypeScript guards (defineHook from @ax/hooks-sdk); validate with ax hooks backtest before ax hooks install.
• ax agents config - agent definitions and the skills they scope.

After the first ingest completes, show the user where their model spend goes - this is the fastest "aha" in the product:

ax cost split --days=7       # main loop vs subagents, by model
ax dispatches --candidates   # dispatches that could run on cheaper models

If the candidates list is non-empty, point at the routing loop: the efficient-dispatch skill (installed with the others), the route-dispatch hook (ax hooks init scaffolds it; install with ax hooks install ~/.ax/hooks/route-dispatch.ts --providers=claude), and docs/design/cost-routing.md for the full picture.

What's installed

Component	Where	Owner
ax / axctl CLI	~/.local/bin/ax (symlink to ~/.local/share/ax/bin/axctl)	install.sh
DuckDB cache	~/.local/share/ax/ (embedded, no daemon to run or watch)	ax ingest
Freshness drive	forks a debounced background ax ingest when the graph is stale	automatic, on any DB-backed command
OTLP receiver (optional, macOS)	com.necmttn.ax-otlpd LaunchAgent	ax install --telemetry
Claude skills	ax:setup (this one), ax:retro (experiment loop), ax:extract-workflow (recipe reconstruction), ax:release-announcement (release notes from git + session evidence)	npx skills add Necmttn/ax

After install

To run the experiment loop:

let's do an ax retro

That fires ax:retro which walks the user through proposal triage + verdict review against their recent work.

For ad-hoc queries the CLI is direct:

ax skills taste --limit=10      # most-used skills (with clean-run boost)
ax recall "auth middleware"     # cross-session text search
ax insights tools --limit=5     # tool-failure leaderboard
ax project context --json       # grounding for the current repo

Common questions

• "What does ax do?" Local typed graph of every Claude Code + Codex session, skill invocation, edit, and commit. Surfaces what skills you actually use, what context to ground on, and which repeated workflows are worth packaging.
• "Is my data shared?" No. Everything stays in a local embedded DuckDB cache under ~/.local/share/ax/. No telemetry leaves the box.
• "How do I uninstall?"

  ax uninstall --purge
  

What this skill is NOT for

• Experiment-loop workflow → use ax:retro.
• Reconstructing how a shipped artifact was built → use ax:extract-workflow.
• Drafting release notes or changelog pages → use ax:release-announcement.
• Day-to-day skill queries → run the CLI directly; no skill mediation needed.
• Schema / dev work on the ax repo itself → see docs/development.md in the repo.