Get axion running.

Install via Homebrew (recommended) or build from source.

# Homebrew
brew tap terryso/tap
brew install axion

# Build from source
git clone https://github.com/terryso/axion
cd axion
swift build -c release
cp .build/release/axion /usr/local/bin/

Interactive setup walks you through provider, API key, and model. doctor validates the environment. Beyond Anthropic, every feature also runs against any OpenAI-compatible endpoint — including Zhipu GLM (e.g. glm-4.6) — by selecting the openai-compatible provider and pointing baseURL at the gateway.

axion setup
axion doctor

# Example GLM (OpenAI-compatible) config in ~/.config/axion/config.json
{
  "provider": "openai-compatible",
  "baseURL": "https://open.bigmodel.cn/api/paas/v4",
  "apiKey": "your-glm-key",
  "model": "glm-4.6"
}

The default axion command opens an interactive REPL with streaming Markdown output. It reads files, edits code, runs shell commands, searches the web, cleans up storage, reviews app uninstall plans, and when needed, controls macOS desktop apps. External MCP tool calls render with clearer categorization and wide-table layouts. When the agent emits a pause_for_human event the REPL opens an interactive confirmation gate: press Enter to continue, type a note to add context, skip to drop the pending action, or abort to terminate the run.

axion                    # start interactive chat (default command)
axion --accept-edits     # auto-approve file edits
axion resume             # resume last session

> refactor UserService to use async/await
> /help                   # list all commands
> /cost                   # token usage and cost breakdown
> /diff                   # git diff summary for this session
> /status                 # session state card
> /mcp                    # browse configured MCP servers (redacted)
> /mcp --all              # full MCP config with secrets redacted
> /compact                # compress context when it gets long
> /storage                # storage scan, organize, large files, undo
> /apps                   # list uninstallable apps
> /arch                   # audit Intel-only apps and packages
> /clear                  # start fresh
> /model                  # switch model mid-session
> /skills                 # list available skills
> /exit                   # exit

# pause_for_human gate
[pause_for_human] confirm before deleting 12 files in ~/Downloads/old
> <Enter>                  # continue
> use Trash, not rm        # continue with extra context
> skip                     # skip this action
> abort                    # terminate the run

Axion edits files with a diff-based approval flow. You see exactly what changes before they're applied — accept, reject, or request edits. Use --accept-edits to auto-approve, or --dangerously-skip-permissions for full auto mode.

> fix the memory leak in Sources/App/Cache.swift
# → shows diff preview:
#   - func load() -> Data? {
#   + func load() async -> Data? {
#   Apply changes? [y/n/e]

> /diff                   # see all changes this session

Search file contents with Grep (regex), find files by name patterns with Glob, and use LSP for go-to-definition, find-references, hover info, and document symbols.

> find all functions that access the database
> where is UserServiceProtocol defined?
> show me all references to CacheManager
> list all symbols in Sources/App/UserService.swift

Search the web and fetch web pages directly from your conversation. No context switching needed.

> search the web for Swift 6.2 concurrency changes
> fetch and summarize the docs at docs.swift.org/...
> what's the latest version of Vapor?

Use axion run for single-shot tasks. Axion automatically picks the right tool — Bash for CLI tasks, MCP for GUI interactions, or Skills for specialized workflows.

axion run "Open Calculator and compute 123 + 456"
axion run "Compress ~/Downloads/video.mp4 using ffmpeg"
axion run "Search the web for Guangzhou weather today"
axion run --dryrun "Open Calculator and compute 123 + 456"
axion run --fast "Open Calculator"
axion run --max-steps 10 "Create a new note in Notes"

Axion handles Mac maintenance as a reviewable workflow. Architecture scans find Intel-only installed apps, Homebrew packages, and MacPorts packages before you decide what to upgrade. Storage scans read metadata, organization plans require approval before moving files, app uninstall shows bundle and support-data candidates first, and storage operations use Trash by default with manifests for undo.

# Find large files and rebuildable caches
> /storage large
> /storage large --home 1GB
> /storage scan ~/Projects

# Organize a folder after reviewing the plan
> /storage organize ~/Downloads
> /storage undo

# Review app uninstall candidates
> /apps
> /apps Xcode

# Audit Intel-only software
> /arch
> /arch --packages-only
axion arch --all

Every run is persisted as a session. List historical sessions with status, step count, and duration. Resume a previous session to continue from where you left off — the SDK restores the full conversation transcript and re-injects memory context.

# List sessions
axion sessions
axion sessions --active           # only running sessions
axion sessions --limit 10         # cap output

# Resume a session
axion resume abc123
axion resume abc123 --fast        # fast mode
axion resume abc123 --json        # JSON output
axion resume abc123 --no-review   # skip post-run review

When a task finishes, Axion sends a macOS desktop notification with three lines: status (done/failed/cancelled), an AI-generated one-line summary, and stats (time, LLM calls, estimated cost). For UI tasks, the terminal window is automatically brought to the foreground. JSON mode suppresses notifications.

Memory is on by default. Two systems: App operation facts (auto-extracted from tool calls — menu paths, control positions, sequences) and Universal Memory (MEMORY.md for environment knowledge, USER.md for user profile). Both injected into context on subsequent runs. Memory files are scanned for security threats before loading.

axion memory list
axion memory show memory    # MEMORY.md content
axion memory show user      # USER.md content
axion memory clear --app com.apple.calculator
axion memory export --output ~/axion-memory.json
axion memory import --input ~/axion-memory.json
axion run --no-memory "Open Calculator"

Three skill types: Prompt Skills from SKILL.md files, Recorded Skills compiled from recordings, and Built-in Desktop Skills (screenshot-analyze, data-extract, form-fill). Dual-track lookup checks prompt skills first, then falls back to recorded.

# Trigger a built-in skill
axion run "/screenshot-analyze analyze the current screen layout"
axion run "/data-extract extract all prices from the table"

# Record and replay
axion record "open_calculator"
# ...perform desktop operations, Ctrl-C to stop
axion skill compile open_calculator
axion skill run open_calculator
axion skill list
axion run --no-skills "Open Calculator"

Run Axion as a service. SSE delivers live events per run. Skill endpoints let you list and execute skills via API.

axion server --port 4242 --auth-key mysecret --max-concurrent 3

GET  /v1/health
POST /v1/runs                 {"task": "..."}
GET  /v1/runs/{id}
GET  /v1/runs/{id}/events     # SSE stream
GET  /v1/skills               # list all skills
GET  /v1/skills/{name}         # skill detail
POST /v1/skills/{name}/run    # execute a skill

Expose Axion to any MCP client. Other agents (Claude Code, Cursor) gain coding tools plus a desktop body. Axion can also connect to additional MCP servers from config.json across all three transports — stdio, sse, and http — with per-server auth headers for remote endpoints. Use /mcp to browse enabled servers and /mcp --all to print the full configuration.

Security: the /mcp output redacts sensitive fields — every value under headers and env is shown as <redacted>, while keys, url, command, args, and transport stay visible. Safe to share screenshots.

axion mcp
> /mcp
> /mcp --all

# Claude Code config:
{
  "mcpServers": {
    "axion": {
      "command": "/path/to/axion",
      "args": ["mcp"]
    }
  }
}

# Axion config.json — stdio + http + sse with auth headers:
{
  "mcpServers": {
    "linear": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@linear/mcp"],
      "env": { "LINEAR_API_KEY": "lin_api_..." }
    },
    "remote-docs": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ..." }
    },
    "events": {
      "type": "sse",
      "url": "https://example.com/sse",
      "headers": { "Authorization": "Bearer ..." }
    }
  }
}

Always-on remote control via Telegram bot. Streaming responses with live updates, interactive approval keyboards for file edits and destructive operations, and skill browsing with paginated inline keyboards. Network handling retries transient 5xx and connection failures, honors Telegram 429 Retry-After values, stops immediately on 401/403 auth failures with a token-configuration hint, and gracefully degrades repeated 409 polling conflicts.

axion setup                              # configure bot token & allowed users
axion gateway start                      # start gateway
axion daemon install --port 4242 --gateway  # auto-start on login

# Telegram commands:
/help     # getting started guide
/status   # gateway status
/skills   # browse available skills
/new      # start a new session
/stop     # stop current task

Install as a launchd agent that auto-starts on login and restarts on crash. All running task state is persisted — in-flight tasks are recovered after unexpected termination.

axion daemon install --port 4242 --auth-key mysecret
axion daemon status
axion daemon uninstall --keep-logs

When automation gets stuck — or the agent explicitly asks for confirmation via pause_for_human — the REPL opens an interactive gate instead of stalling. Press Enter to continue, type a free-form note to add context for the next step, skip to drop the pending action, or abort to terminate. Your response is recorded as Memory so the same moment resolves faster next time. You can also manually record takeover experiences.

# During a run, Axion pauses on pause_for_human or when stuck
[pause_for_human] confirm before deleting 12 files in ~/Downloads/old
> <Enter>                  # continue
> use Trash, not rm        # continue with extra context
> skip                     # skip this action
> abort                    # terminate the run

# Manually record a takeover experience
axion memory learn-takeover --bundle-id com.apple.finder   --issue "file dialog not accessible via AX"   --summary "used Cmd+Shift+G to enter path directly"

After each run, Axion automatically triggers a background review agent that analyzes the conversation, extracts new memory facts, and evolves skill definitions — no user action required. An intelligent curator periodically manages the skill lifecycle: archiving stale skills, consolidating overlapping ones, and pruning redundancies.

axion run --no-review "Open Calculator"
axion run --review-model claude-haiku-4-5-20251001 "Open Calculator"
axion curator status
axion curator run
axion curator run --dry-run

Located at ~/.config/axion/config.json. Priority: defaults → file → env vars → CLI flags.

{
  "provider": "anthropic",
  "apiKey": "sk-...",
  "model": "claude-sonnet-4-20250514",
  "maxSteps": 20,
  "maxModelCalls": 50,
  "reviewModel": "claude-haiku-4-5-20251001",
  "reviewMemoryInterval": 10,
  "reviewSkillInterval": 15,
  "reviewMinMessages": 4,
  "curatorEnabled": true,
  "curatorIntervalHours": 168,
  "curatorStaleAfterDays": 30,
  "curatorArchiveAfterDays": 90,
  "mcpServers": {
    "linear": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@linear/mcp"]
    },
    "remote-docs": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ..." }
    }
  }
}