Documentation

Getting started

Everything you need to install, configure, and extend Aurict.

Installation

npm (recommended)

Install the global binary via npm. The correct platform binary (macOS arm64/x64, Linux x64/arm64, Windows x64) is selected automatically — no separate download needed.

npm install -g aurict

First run

Navigate to any project directory and launch. A setup wizard runs on first launch — pick a provider, enter your API key, and choose a model. Takes about 30 seconds.

cd your-project
aurict

Build from source

Clone the repo and build with Bun. Requires Bun >= 1.1.

git clone https://github.com/aurict/aurict
cd aurict
bun install
bun run build

Configuration

Project config — .aurict/config.json

Place a config file in your project root or in ~/.aurict/ for global defaults. Project config overrides global config, CLI flags override both.

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "maxTokens": 8192,
  "stream": true
}

API keys via /config

Set API keys from inside the terminal UI. Keys are encrypted and saved to ~/.aurict/config.json, persisting across sessions.

# Inside the Aurict terminal:
/config set anthropic sk-ant-...
/config set openai sk-...
/config set google AIza...

# Show current config
/config

Environment variables

API keys can also be set via environment variables. They take precedence over config file keys.

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_GENERATIVE_AI_API_KEY=AIza...
OPENROUTER_API_KEY=sk-or-...
XAI_API_KEY=xai-...

Providers & Models

Switching providers

Use /providers inside the TUI to see all available providers and their key status, then switch between them. A model picker opens automatically after switching.

/providers

Supported providers

9 providers are built in. Ollama requires no API key and works with any locally running model (llama3, mistral, deepseek-r1, etc).

anthropic   → Claude 4 Opus, Sonnet, Haiku
openai      → GPT-4o, o1, o3, o4-mini
google      → Gemini 1.5 Pro/Flash, 2.0
openrouter  → 200+ models via one key
xai         → Grok 2, Grok 3
azure       → Azure OpenAI deployments
bedrock     → Claude via AWS
ollama      → Local models (no key needed)
opencode    → OpenCode / Zenmux

Thinking / reasoning mode

Models that support extended thinking (claude-opus-4, o3, deepseek-r1) show a reasoning budget picker after model selection. Use /models to adjust at any time.

/models
# → select model → select effort (off / low / med / high / max)

Custom Tools

Creating a tool

Drop a .js ESM file in ~/.aurict/tools/ (global) or .aurict/tools/ (project). Project tools override global tools with the same id. Tools are loaded at startup.

// .aurict/tools/my-tool.js
export default {
  id: "my-tool",
  description: "What this tool does",
  parameters: {
    type: "object",
    properties: {
      input: { type: "string", description: "Input text" }
    },
    required: ["input"]
  },
  async execute({ input }, ctx) {
    return { output: input.toUpperCase() }
  }
}

Tool context (ctx)

The execute function receives a ctx object with the current working directory, session ID, and an abort signal.

async execute({ input }, ctx) {
  const { workdir, sessionId, signal } = ctx
  // workdir: current project path
  // signal:  AbortSignal for cancellation
}

Custom Skills

Creating a skill

Skills are Markdown files injected into the system prompt when their trigger conditions match. Place them in ~/.aurict/skills/ or .aurict/skills/.

<!-- .aurict/skills/conventions.md -->
---
name: conventions
description: Our team coding conventions
---

Always use 2-space indentation.
Prefer functional components over class components.
Never use var — always const or let.
All async functions must handle errors explicitly.

Auto-injected skills

Aurict scans your project on startup and auto-injects relevant skills from its 218+ built-in library based on detected frameworks, languages, and config files.

# Aurict detects and injects skills for:
next.js, react, vue, svelte, astro
python, fastapi, django, flask
rust, go, java, kotlin
docker, kubernetes, terraform
bun, deno, node
# ...and 200+ more combinations

MCP Integration

Using your existing MCP config

Aurict reads your claude_desktop_config.json automatically on startup. Any MCP server you have configured for Claude Desktop works immediately — no re-configuration needed.

# macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Linux
~/.config/Claude/claude_desktop_config.json

# Windows
%APPDATA%\Claude\claude_desktop_config.json

Listing connected servers

Use /mcp inside the TUI to see all connected MCP servers and their available tools.

/mcp

Session Management

Browsing sessions

All sessions are persisted automatically. Use /sessions to open an interactive picker with fuzzy search, or Ctrl+R to open QuickSearch from anywhere.

/sessions        # interactive picker
Ctrl+R           # QuickSearch (fuzzy)

Checkpoints & undo

Aurict creates a checkpoint before every AI action. Use /undo to roll back N steps (files + conversation), or /checkpoints to list all saved states.

/undo            # undo last step
/undo 3          # undo last 3 steps
/checkpoints     # list all checkpoints
/replay <id>     # jump to any checkpoint

Forking & branching

Fork the current session to create an independent copy, or branch the conversation to explore different approaches without losing your current state.

/fork            # create independent copy
/branch          # branch conversation
/branch list     # list branches

Context compaction

When approaching the context window limit, Aurict can compact old messages while preserving critical context. Use /compact to view or change the compaction strategy.

/compact         # show current strategy
/compact auto    # auto-compact at 80% usage
/compact manual  # prompt before compacting
/ctx             # show context usage

Hooks

What are hooks?

Hooks are shell commands that run automatically at specific lifecycle events — before a tool call, after a response, or when a session starts. Place hook configs in .aurict/hooks.json.

{
  "hooks": [
    {
      "event": "pre-tool",
      "tool":  "bash",
      "run":   "echo \"About to run: $TOOL_ARGS\""
    },
    {
      "event": "post-response",
      "run":   "notify-send \"Aurict finished\""
    }
  ]
}

Available hook events

Hooks can fire on these events. Environment variables provide context about the triggering event.

pre-tool        → before any tool executes ($TOOL_NAME, $TOOL_ARGS)
post-tool       → after tool completes ($TOOL_NAME, $TOOL_RESULT)
pre-response    → before AI generates text
post-response   → after AI response ($RESPONSE_TEXT)
session-start   → on launch ($SESSION_ID, $WORKDIR)
session-end     → on exit

Multi-Agent

Specialist agents

Aurict ships 9 built-in specialist agents, each pre-configured with domain-specific tools and system prompts. Switch with /agent.

/agent           # show agent picker

# Available agents:
omni        → General-purpose (default)
explore     → Codebase exploration & analysis
code        → Implementation & refactoring
review      → Code review & best practices
test        → Test writing & coverage
docs        → Documentation generation
security    → Security audit & hardening
debug       → Root cause analysis
perf        → Performance profiling

Coordinator mode

In coordinator mode, Aurict decomposes complex tasks and delegates subtasks to specialist agents running in parallel worker threads. Enable with /coordinator.

/coordinator     # toggle coordinator mode
/agents          # list custom agents

Custom agents

Define custom agents in .aurict/agents/ as JSON files. Each agent can have a custom system prompt, tool restrictions, and a default model.

// .aurict/agents/my-agent.json
{
  "id": "my-agent",
  "name": "My Agent",
  "description": "Specialized for X",
  "system": "You are an expert in...",
  "tools": ["bash", "read", "write"],
  "model": "claude-sonnet-4-6"
}

Background tasks

Send long-running tasks to the background so you can continue chatting. Background tasks run in a separate worker and notify you when done.

/background      # move current task to background
/background list # list running background tasks

Token & Cost Tracking

Viewing session cost

Use /cost to see a full breakdown of token usage and estimated cost for the current session. Cache reads are shown at their discounted rate.

/cost

# Example output:
# Fresh input:   12,430 tokens   $0.037
# Output:         3,210 tokens   $0.048
# Cache reads:   48,200 tokens   $0.014  (10× cheaper)
# Cache writes:   8,400 tokens   $0.031
# ──────────────────────────────────────
# Total:         72,240 tokens   $0.130
# Cache savings: $0.686 saved vs no caching

Context window usage

The context bar in the status line shows real-time context window usage. It counts fresh input + cache reads + cache writes — the true context consumed.

/ctx             # detailed context breakdown

Worktrees

Parallel development with worktrees

Use /worktree to create and manage git worktrees — each worktree gets its own Aurict session, letting you work on multiple branches simultaneously without stashing.

/worktree create feature/auth   # new worktree + session
/worktree list                  # show active worktrees
/worktree switch feature/auth   # switch to existing
/worktree remove feature/auth   # clean up