Documentation

Getting started

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

Product Surfaces

┌

Terminal agent

The CLI is the primary Aurict runtime: BYOK providers, project context, typed tools, checkpoints, sessions, skills, MCP, hooks, local API access, and multi-agent workflows run where developers already work.

aurict
/config
/providers
/sessions
/agent
/mcp

┌

Web platform

The web app is the public trust and onboarding surface. It contains the landing page, docs, roadmap, changelog, manifesto, Firebase-backed auth, browser login flow, privacy policy, terms, and account deletion direction.

apps/web
/routes: /docs /roadmap /changelog /about /privacy /terms /auth/device

┌

Mobile BYOK assistant

The Flutter app extends Aurict beyond the terminal: BYOK chat, provider sessions, research and document workflows, PDF generation, scoped assistant-answer reporting, and Android release hardening.

mobile/lib/main.dart
mobile/lib/agent/mobile_chat_stream.dart
mobile/lib/agent/mobile_feedback_report.dart

Security & Privacy

┌

Secret boundaries

Provider keys, Firebase service files, Android keystores, key properties, local env files, SQLite runtime data, and backend prototype files are excluded from source control. CI restores release secrets from GitHub Actions secrets when producing Android artifacts.

.env
.env.local
google-services.json
*.jks
*.keystore
key.properties
apps/backend/

┌

Account and feedback flows

The web and mobile surfaces include privacy, terms, account deletion, and report-feedback paths. Reported assistant answers are treated as scoped feedback events for review, not as a blanket upload of a user's project.

POST /feedback/reports
POST /account/delete
/privacy
/terms

Installation

┌

macOS and Linux

Download the matching self-contained release binary without installing Node.js or Bun. The installer verifies the release SHA-256 checksum before installing to ~/.local/bin.

curl -fsSL https://aurict.com/install.sh | bash

┌

npm

Use npm when you prefer package-manager updates or are on Windows. The correct platform binary (macOS arm64/x64, Linux x64/arm64, Windows x64) is selected automatically.

npm install -g aurict

┌

Direct release binary

Use a GitHub Release when you need a portable binary, an offline-friendly deployment, or a fully manual installation. Download the asset for your operating system and CPU architecture, then compare its SHA-256 hash with the matching entry in checksums.txt before you run it.

# Linux x64
curl -LO https://github.com/aurict/aurict/releases/latest/download/aurict-linux-x64
curl -LO https://github.com/aurict/aurict/releases/latest/download/checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x aurict-linux-x64
./aurict-linux-x64

# Windows PowerShell
Invoke-WebRequest https://github.com/aurict/aurict/releases/latest/download/aurict-win32-x64.exe -OutFile aurict.exe
Invoke-WebRequest https://github.com/aurict/aurict/releases/latest/download/checksums.txt -OutFile checksums.txt
Get-FileHash .\aurict.exe -Algorithm SHA256

┌

Versioned, custom-directory, and removal options

The one-line installer accepts a release version and an installation directory through environment variables. It installs only the Aurict binary; removing that binary removes this installation method. npm users can uninstall with npm.

# Install a specific version into a custom user directory
AURICT_INSTALL_VERSION=1.2.0 AURICT_INSTALL_DIR=~/.local/bin curl -fsSL https://aurict.com/install.sh | bash

# Remove the curl-installer binary
rm ~/.local/bin/aurict

# Remove the npm package
npm uninstall -g aurict

┌

First run

Navigate to any project directory and launch. On first run, choose a provider, enter an API key, choose a model, then decide whether Project Auto may approve bounded file changes in this project for this session.

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

12 providers are built in. Ollama requires no API key and works with locally running models. Use /providers and /models for the current models available to your configured providers.

anthropic    → Anthropic
openai       → OpenAI
openrouter   → OpenRouter
google       → Google
opencode     → OpenCode (Zen)
ollama       → Ollama
xai          → xAI
azure        → Azure OpenAI
bedrock      → AWS Bedrock
nvidia       → NVIDIA NIM
zai          → Z.AI (GLM)
alibaba      → Alibaba (Qwen)

┌

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 can import compatible servers from claude_desktop_config.json on startup. Use /mcp to confirm each connection and inspect the tools it exposes; server compatibility, credentials, and local dependencies still apply.

# 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

┌

Project Auto

Project Auto removes repeated prompts only for bounded write, edit, and apply_patch requests inside the active project. The grant is session-scoped and resets when the workdir changes. Shell commands, secrets, .git and .aurict paths, project escapes, dangerous operations, and broad deletions still require direct approval.

/auto            # toggle Project Auto
/autopilot       # alias

# On startup: choose Yes or No for this project session

┌

Completion proof

Use /proof to inspect the durable completion record: changed files, verification evidence, open work, and explicit waivers. Required work stays gated while its evidence is pending or failed.

/proof
/proof json
/proof waive verification test runner unavailable in this environment

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