AXIOM is an MCP server for AI agent observability and control.

It started as a flight recorder for agent runs: logging reasoning steps, replaying sessions, detecting drift, and exporting shareable reports.

It now also acts as an early control layer:

• guardrails that evaluate a run in progress
• persistent policies that can warn, re-plan, or stop a session
• next-step recommendations
• alternate branch suggestions
• cross-session learning from past runs

If you are building or operating MCP agents, AXIOM gives you a way to inspect what happened and increasingly, to shape what happens next.

Docs:

• CHANGELOG
• CONTRIBUTING

AXIOM is a black box recorder plus early control system for AI agents.

Most agent tooling stops at logs.

AXIOM tries to close the loop:

• record what happened
• detect unhealthy trajectories
• recommend the next move
• gate bad actions before they waste more time or money
• learn from past runs

Most agent runs are hard to debug once they go wrong.

AXIOM helps you answer:

• What did the agent actually do?
• When did it start looping?
• Which prompts, tools, or paths work better?
• Should this run continue, re-plan, or stop?

Practical uses:

• debugging unreliable agent runs
• comparing prompts, workflows, or agent variants
• generating postmortems and audit trails
• detecting repetition and wasted tool calls
• enforcing guardrails before a run gets more expensive

npm install
npm run build
npm run start:http

Open:

• http://localhost:3456/dashboard
• http://localhost:3456/gallery

Or run the stdio server:

npm run start

• Reasoning ledger stored in SQLite
• Auto-tagged receipts and drift scoring
• Session replay, comparison, and search
• HTML/Markdown/JSON exports and share cards
• Browser dashboard, gallery, and report pages
• Guard evaluation and next-move recommendation
• Branch suggestions with predicted outcomes
• Persistent policy system for session control
• Gate checks that can allow, warn, or block proposed moves
• Resume flow for blocked sessions
• Historical learning across recent sessions

npm install
npm run build

Stdio MCP server:

npm run start

HTTP/SSE server with browser UI:

AXIOM_PORT=3456 npm run start:http

Then open:

• http://localhost:3456/dashboard
• http://localhost:3456/gallery

• /dashboard - live browser dashboard for current and recent sessions
• /gallery - featured runs, chaotic failures, and recovery stories
• /reports/:id - polished HTML casefile for a session
• /postmortem/:id?style=professional|roast - HTML postmortem page
• /visualize/:id - Mermaid-ready visualization page
• /arena?session_a=<id>&session_b=<id> - head-to-head HTML arena
• /events - browser SSE stream for live updates

JSON APIs:

• /api/dashboard
• /api/sessions
• /api/sessions/:id
• /api/leaderboard
• /api/gallery

• You are tuning an agent and want to compare two prompt or tool strategies.
• You need to know why an agent kept looping instead of shipping an answer.
• You want a postmortem or HTML report after a failed run.
• You want a policy like "stop if drift is too high" or "don't keep calling the same tool."
• You want to inspect and govern agent behavior across repeated runs, not just one transcript.

Export a session as HTML:

{
  "session_id": "current",
  "format": "html"
}

Generate a roast-style postmortem:

{
  "session_id": "current",
  "style": "roast",
  "format": "markdown"
}

Add a persistent guard policy:

{
  "op": "add",
  "name": "Stop high drift early",
  "scope": "global",
  "condition": "drift",
  "action": "stop",
  "threshold": 0.35
}

Ask AXIOM what to do next:

{
  "session_id": "current",
  "format": "text"
}

Gate a proposed tool call:

{
  "session_id": "current",
  "tool": "search",
  "intent": "search again",
  "enforce": true,
  "format": "text"
}

Resume a blocked session:

{
  "session_id": "current",
  "note": "Human reviewed and replanned"
}

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "axiom": {
      "command": "node",
      "args": ["/absolute/path/to/axiom-mcp/dist/index.js"],
      "env": {
        "AXIOM_WEBHOOK_URL": "https://your-webhook.site/hook",
        "AXIOM_WEBHOOK_THRESHOLD": "0.5"
      }
    }
  }
}

codex mcp add axiom -- node /absolute/path/to/axiom-mcp/dist/index.js

AXIOM is experimental, but the core pieces are already usable:

• session logging and replay
• drift detection
• search and comparison
• browser dashboard and report pages
• policy-based guardrails
• next-step recommendation
• preflight action gating

The shortest honest description is:

AXIOM is a black box recorder and emerging control layer for AI agents.

MIT