Documentation

Getting Started

One command to install. One command to setup. Then use Claude Code as usual — AXME Code works in the background.

Prerequisites

✓

Claude Code CLI or VS Code extension

AXME Code runs as an MCP server inside Claude Code. You need either the CLI or the VS Code extension.

✓

Node.js ≥ 20

Required for the MCP server runtime. Check with node --version.

Install

Run a single curl command. It downloads the binary and adds it to your PATH.

# Install AXME Code

curl -fsSL https://raw.githubusercontent.com/AxmeAI/axme-code/main/install.sh | bash

Setup

Navigate to your project and run setup. This is a one-time operation per project.

cd your-project && axme-code setup

Here is what axme-code setup does:

Scans your project — reads the codebase structure, language, framework, and key files.

Builds the oracle — generates a structured overview of your stack, architecture, patterns, and conventions.

Extracts decisions, memories, and safety rules — from any existing CLAUDE.md, README, or project docs.

Installs hooks — PreToolUse, PostToolUse, and SessionEnd hooks in Claude Code that enforce safety rules on every tool call.

Configures the MCP server — registers AXME Code with Claude Code so tools are available automatically.

First Session

After setup, just launch Claude Code as you normally would.

claude

The agent automatically calls axme_context at session start, which loads the full knowledge base: oracle, decisions, memories, safety rules, and the handoff from the previous session. You do not need to prompt it — the CLAUDE.md instructions handle this.

What Gets Created

Setup creates a .axme-code/ directory in your project root with this structure:

.axme-code/

oracle/# Project overview — stack, structure, patterns

decisions/# Architectural decisions with enforcement levels

memory/# Learned patterns, mistakes, validated approaches

safety/# Safety rules and blocked command patterns

backlog/# Persistent cross-session task tracking

sessions/# Per-session meta.json and audit data

plans/# Session handoffs and work plans

worklog.jsonl# Structured event log

worklog.md# Narrative session summaries

config.yaml# AXME Code configuration

This directory is gitignored by default. Setup adds .axme-code/ to your .gitignore automatically. The knowledge base stays local to your machine.

Available Tools

AXME Code provides 19 MCP tools that the agent can call during sessions.

Tool	Description
`axme_context`	Load full project knowledge base at session start
`axme_oracle`	Read the project oracle (stack, architecture, conventions)
`axme_decisions`	List all architectural decisions with enforcement levels
`axme_memories`	Retrieve saved memories (patterns, mistakes, approaches)
`axme_safety`	Read safety rules and blocked command patterns
`axme_save_memory`	Save a new memory (discovery, validated approach, correction)
`axme_save_decision`	Record an architectural decision with enforcement level
`axme_update_safety`	Add or modify a safety rule
`axme_status`	Show current session status and knowledge base stats
`axme_worklog`	Append an entry to the project work log
`axme_workspace`	Load workspace-level context for multi-repo setups
`axme_backlog`	View the project backlog of planned work items
`axme_backlog_add`	Add a new item to the project backlog
`axme_backlog_update`	Update status or details of a backlog item
`axme_ask_question`	Ask the user a question and record it for follow-up
`axme_answer_question`	Record the user's answer to a previously asked question
`axme_list_open_questions`	List all unanswered questions pending user response
`axme_begin_close`	Start the session close process (get close checklist)
`axme_finalize_close`	Complete session close with handoff, memories, decisions

CLI Commands

The axme-code CLI provides these commands:

Command	Description
`axme-code setup`	Initialize AXME Code for a project (scan, build oracle, install hooks, configure MCP)
`axme-code serve`	Start the MCP server manually (usually not needed — Claude Code starts it automatically)
`axme-code status`	Show knowledge base stats: oracle size, decisions, memories, sessions
`axme-code stats`	Detailed statistics about sessions, tool usage, and audit results
`axme-code audit-kb`	Run a manual audit of the knowledge base for consistency
`axme-code audit-session`	Run LLM audit on a session transcript

Troubleshooting

`axme-code: command not found`

The binary is not on your PATH. The installer places it in ~/.local/bin/ by default.

export PATH="$HOME/.local/bin:$PATH"

Add this to your ~/.bashrc or ~/.zshrc to make it permanent.

`Hooks not working`

If safety hooks are not intercepting commands, re-run setup to reinstall them:

axme-code setup

This is non-destructive — it will not overwrite existing knowledge base data.

`MCP tools not appearing in Claude Code`

The MCP server configuration may not have been registered. Check that .mcp.json exists in your project root and contains the axme-code entry. If using VS Code, reload the window after setup.

`Agent not calling axme_context at start`

Ensure your project has a CLAUDE.md with the AXME Code instructions. Setup creates this automatically, but if it was removed, re-run axme-code setup.

Ready to get started?

Install AXME Code and give your Claude Code agent persistent memory in 30 seconds.