Docs — axiom

What is axiom?

axiom is an open-source CLI and Node.js library that gives you a catalog of production-ready AI agents — for research, writing, code review, analysis, and more — that you can run from your terminal or import directly into your project.

It's built on top of the Anthropic Claude Agent SDK and works with your own Anthropic API key (BYOK). No proxy, no account required for v1.

axiom is made of three packages:

@axiomcm/cli — the global axiom command you install and run in any terminal
@axiomcm/agents — the agent SDK, importable into any Node.js app
@axiomcm/dashboard — the local web dashboard server

v2 coming soon: A managed proxy tier — pay a flat monthly rate and run agents without your own Anthropic key. Join the waitlist →

Installation

Install the axiom CLI globally with npm, pnpm, or yarn. Requires Node.js 18+.

$ npm install -g @axiomcm/cli

$ pnpm add -g @axiomcm/cli

Verify the installation:

$ axiom --version
0.1.0

$ axiom --help

Using the SDK directly

If you want to import agents into your own Node.js project rather than using the CLI:

$ npm install @axiomcm/agents

Authentication

axiom uses your own Anthropic key to call Claude. There are two supported methods — use whichever you have access to.

Option A — Anthropic API Key (recommended)

Get your key from console.anthropic.com. Set it as an environment variable:

# In your shell profile (.bashrc, .zshrc) or .env file
export ANTHROPIC_API_KEY=sk-ant-api03-...

Option B — Claude OAuth Token

If you're a Claude Pro or Max subscriber, you can use your OAuth token instead:

export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...

axiom also checks for an AXIOM_API_KEY environment variable, which is reserved for the upcoming v2 proxy tier.

Tip: Create a .env file in your project root and run axiom init — axiom will automatically pick up environment variables from it.

All commands

Command	Description
`axiom list`	List all available built-in and custom agents
`axiom try <agent> "<input>"`	Run a built-in agent with a prompt
`axiom dashboard`	Open the local web dashboard
`axiom create`	Scaffold a new custom agent interactively
`axiom init`	Initialise axiom in the current project directory
`axiom --help`	Show help for any command
`axiom --version`	Print the installed version

axiom list

Lists all available agents — both built-in and any custom agents you've created in the current project's .axiom/agents/ directory.

$ axiom list

Built-in agents (18):
  research              Research Agent
  prd-writer            PRD Writer
  code-review           Code Reviewer
  email-drafter         Email Drafter
  competitor-analyzer   Competitor Analyzer
  ...

Custom agents (0):
  No custom agents found. Run `axiom create` to make one.

axiom try

Runs a built-in or custom agent with the input you provide. The agent executes, prints its output, and saves the run to .axiom/runs/.

$ axiom try <agent-id> "your input here"

Examples

# Run the research agent
$ axiom try research "What are the top AI agent frameworks in 2026?"

# Run the code reviewer
$ axiom try code-review "Review my authentication middleware for security issues"

# Run the PRD writer
$ axiom try prd-writer "A dashboard for tracking AI agent run costs"

# Run a custom agent
$ axiom try my-custom-agent "your input"

Flags

Flag	Description
`--no-persist`	Don't save this run to disk
`--json`	Output the result as JSON (useful for piping)

axiom dashboard

Starts the local web dashboard and opens it in your default browser. The dashboard lets you browse the agent catalog, trigger runs, and inspect your full run history — all without leaving your machine.

$ axiom dashboard

  axiom dashboard → http://127.0.0.1:3210
  Ctrl+C to stop

By default the dashboard runs on port 3210. All data is read from and written to your local .axiom/ directory — nothing is sent to any server.

See the Dashboard page for a full walkthrough of what it shows.

axiom create

Launches an interactive prompt to scaffold a new custom agent. You define the name, description, system prompt, and which tools the agent can use.

$ axiom create

  ? Agent name:        Interview Summarizer
  ? Description:      Summarizes customer interview transcripts
  ? Category:         Product
  ? System prompt:    You are an expert at synthesizing ...
  ? Allowed tools:    (select from list)

  ✓ Created .axiom/agents/interview-summarizer.json

The agent definition is saved as a JSON file in .axiom/agents/. It's immediately available via axiom list, axiom try, and the dashboard.

axiom init

Initialises axiom in the current directory. Creates the .axiom/ folder structure and optionally adds it to .gitignore (since run history may be large).

$ axiom init

  ✓ Created .axiom/agents/
  ✓ Created .axiom/runs/
  ✓ Added .axiom/runs/ to .gitignore

Built-in agents

axiom ships with 18+ production-ready agents across 7 categories. They're always available — no configuration needed.

ID	Name	Category
`research`	Research Agent	Research
`data-analyst`	Data Analyst	Research
`code-review`	Code Reviewer	Engineering
`bug-triager`	Bug Triager	Engineering
`documentation-agent`	Documentation Agent	Engineering
`technical-spec-agent`	Technical Spec Agent	Engineering
`test-plan-agent`	Test Plan Agent	Engineering
`release-notes-agent`	Release Notes Agent	Engineering
`prd-writer`	PRD Writer	Product
`customer-feedback-synthesizer`	Customer Feedback Synthesizer	Product
`content-writer`	Content Writer	Marketing
`seo-auditor`	SEO Auditor	Marketing
`competitor-analyzer`	Competitor Analyzer	Business
`sales-prospector`	Sales Prospector	Business
`market-sizing-agent`	Market Sizing Agent	Business
`proposal-writer`	Proposal Writer	Business
`email-drafter`	Email Drafter	Operations
`meeting-summarizer`	Meeting Summarizer	Operations
`customer-support-agent`	Customer Support Agent	Operations
`financial-analyst`	Financial Analyst	Finance

See the full Agent Catalog for descriptions and example commands.

Custom agents

You can build your own agents and axiom will treat them exactly like built-in ones — they appear in axiom list, run with axiom try, and show up in the dashboard.

Creating a custom agent

The easiest way is the interactive wizard:

$ axiom create

Custom agent file format

Custom agents are stored as JSON in .axiom/agents/. You can create or edit them directly:

{
  "id":           "interview-summarizer",
  "name":         "Interview Summarizer",
  "summary":      "Summarizes customer interview transcripts into themes",
  "category":     "Product",
  "tags":         ["interviews", "synthesis"],
  "systemPrompt": "You are an expert at synthesizing customer research...",
  "allowedTools": [],
  "maxLoops":     5
}

Available tools

Tool	Description
`web_search`	Search the web for current information
`web_scrape`	Scrape the content of a URL
`file_reader`	Read files from the local filesystem

Dashboard

The axiom dashboard is a local web app that runs entirely on your machine. Start it with:

$ axiom dashboard

It serves on http://127.0.0.1:3210 and opens automatically in your browser.

What the dashboard shows

Agent Catalog — all built-in and custom agents, filterable by kind and category. Select one, type your input, and run it directly from the browser.
Run History — every persisted run with timestamp, status (success/error), cost, token count, and duration. Filterable by status and date range.
Run Detail — click any run to inspect its full input, output, tool calls, auth mode, and loop count.

Everything is read from .axiom/runs/ on your disk. No data leaves your machine. See the Dashboard page for screenshots and a full feature walkthrough.

Programmatic usage

You can import @axiomcm/agents directly into any Node.js or TypeScript project to run agents programmatically.

$ npm install @axiomcm/agents

Run a built-in agent

import { getBuiltInAgentById, configure } from '@axiomcm/agents';

configure({
  apiKey:      process.env.ANTHROPIC_API_KEY,
  storageDir:  '.axiom',
  persistRuns: true,
});

const agent = getBuiltInAgentById('research');
const result = await agent.run('Latest developments in AI agent frameworks');

console.log(result.output);    // the agent's response
console.log(result.cost);      // e.g. 0.0142
console.log(result.tokensUsed); // { input: 820, output: 4000, total: 4820 }

Run a custom agent

import { loadAgent } from '@axiomcm/agents';

const agent = await loadAgent('interview-summarizer', '.axiom');
const result = await agent.run(transcript);

AgentResult type

Field	Type	Description
`output`	`string`	The agent's final response text
`success`	`boolean`	Whether the run completed without error
`cost`	`number`	Estimated USD cost
`tokensUsed`	`{ input, output, total }`	Token breakdown
`duration`	`number`	Run time in milliseconds
`loops`	`number`	Number of agentic loops executed
`toolCalls`	`ToolCall[]`	All tool calls made during the run

Configuration

Environment variables

Variable	Description
`ANTHROPIC_API_KEY`	Your Anthropic API key (primary auth method)
`CLAUDE_CODE_OAUTH_TOKEN`	Claude Pro/Max OAuth token (alternative)
`AXIOM_API_KEY`	Reserved for v2 proxy tier (coming soon)

.axiom/ directory structure

.axiom/
  agents/        # your custom agent definitions (JSON)
    my-agent.json
  runs/          # persisted run history (one JSON file per run)
    run-1749123456789.json
    ...

Run files contain the full record: input, output, agent metadata, cost, tokens, duration, tool calls, and auth mode. They're plain JSON and safe to read or process programmatically.

Tip: Add .axiom/runs/ to your .gitignore — run history can grow large over time. Agent definitions in .axiom/agents/ are worth committing so your team shares custom agents.