aurict/aurict: runs entirely in your terminal

A terminal-native AI coding assistant built for the way developers actually work.

aurict.com · npm · Docs · Changelog · Android APK

❯ aurict

Aurict runs entirely in your terminal. No browser tabs, no Electron overhead, no clipboard juggling between windows. You stay in the environment where you already write code, and the AI meets you there — with full access to your files, shell, language servers, and running processes.

The wider Aurict system now includes a public web surface, a BYOK mobile assistant, and a local backend control-plane prototype. The terminal remains the core product, while the web and mobile layers handle authentication, documentation, roadmap visibility, account deletion, feedback reporting, Android release distribution, and future console workflows.

Why Aurict?

Most AI coding tools are built around a chat interface that happens to have a code block. Aurict is built around a coding environment that happens to have a chat interface.

It understands your project before you say a word. Aurict scans your repository on startup — framework, language, package manager, config files, existing conventions — and injects that context into every request. You don't have to explain that you're using Next.js with Tailwind and Drizzle. It already knows.

It works with real tools, not simulated ones. Every file read, shell command, and code edit happens through a typed, permission-controlled tool layer. Commands are classified as safe, warning, or dangerous before execution. Risky execution is constrained by a low-overhead policy sandbox: permission gates, protected paths, timeouts, output limits, and audit trails. You always know what's happening and why.

At TUI startup, Aurict asks whether to enable Project Auto for the current folder. Choosing Yes removes repeated prompts for bounded write, edit, and apply_patch operations in that project for the current session. Shell commands, secrets, internal state, paths outside the project, dangerous operations, and broad deletions still require direct approval.

It thinks in parallel, not in sequence. Long tasks — refactoring a module, writing a test suite, auditing security — are broken into subtasks and distributed across a pool of specialized worker agents: code, review, test, docs, performance, security, debug, analytics, explore. Results flow back into a shared context.

It speaks your stack's language. 218+ skills cover specific frameworks, tools, and patterns. A skill isn't a prompt template — it's a structured context injection that shapes how the AI reasons about your particular combination of technologies.

It stays out of your way. The TUI is built on Ink (React for terminals). It renders cleanly, scrolls correctly, handles wide output, and gets out of the way when you're not interacting with it. No flickering, no full-screen takeovers.

It exposes a local API. Every session is reachable over HTTP with bearer-token auth. Pipe output from scripts, drive Aurict from CI, or build your own tooling on top.

Features

Product Surfaces

Core Agent

Tools

Security

Design Agent

Integrations

Installation

Android mobile build

Release APKs are produced by the manual Mobile Android Release workflow.

1. Open Mobile Android Release.
2. Run the workflow with apk or both.
3. Download the aurict-android-release-apk artifact from the completed run.

The APK is signed during CI with the configured Android release keystore and Firebase google-services.json restored from GitHub Actions secrets. Signing files are not committed to the repository.

One-line installer (macOS and Linux)

Downloads the matching self-contained binary from GitHub Releases and verifies its SHA-256 checksum. No Node.js, Bun, or sudo is required.

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

Install a specific release or choose another directory by passing variables to bash:

curl -fsSL https://aurict.com/install.sh | AURICT_INSTALL_VERSION=1.2.21 AURICT_INSTALL_DIR=/path/to/bin bash

Compile from source

Produces a single self-contained binary with the Bun runtime embedded — no runtime dependencies.

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

# Run
./dist/aurict

Global install via npm

npm install -g @aurict/cli
aurict

Requirements

• Bun 1.3+ (for building from source)
• Node.js 20+ (for the npm package)
• An API key for at least one supported provider

Quick Start

# Set your API key
aurict /config set anthropic sk-ant-...

# Start the TUI (always runs in the current directory)
aurict

# Pipe mode — non-interactive single query
echo "What does this function do?" | aurict

# Machine-readable pipe result
echo "Summarize this repository" | aurict --format json --audience agent

# Open a specific directory
cd ~/projects/myapp && aurict

# Run diagnostics without launching the TUI
aurict doctor

# Run an automated recipe
aurict run recipe.yaml

# Inspect build provenance or install shell completion
aurict version --json
aurict completion zsh

CLI Flags

aurict [options]

  -p, --provider <id>    Provider to use (anthropic, openai, openrouter, google, ollama)
  -m, --model <id>       Model to use
  -s, --system <text>    System prompt override
      --undercover       Hide AI identity in responses
      --stream           Enable streaming
      --no-stream        Disable streaming
      --format <mode>    Output format: text or json
      --audience <type>  Output audience: human or agent
  -q, --quiet            Suppress non-essential diagnostics
  -v, --version          Print version
  -h, --help             Show help

Root commands and versioned output contracts are documented in docs/cli.md.

Providers

Slash Commands

Full reference: docs/slash-commands.md

Session & Navigation

Agent & Model

Code & Git

Memory & Context

Config & Setup

Tools & Skills

Utilities

Keyboard Shortcuts

MCP Integration

Aurict reads MCP server configuration from .aurict/mcp.json, using the same format as claude_desktop_config.json.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-token>"
      }
    }
  }
}

MCP tools appear alongside built-in tools and are subject to the same permission system.

HTTP API

Aurict exposes a REST/SSE API on 127.0.0.1:7777. All endpoints except /v1/health require bearer-token authentication.

# Read the auto-generated token
TOKEN=$(cat ~/.aurict/server-token)

# Health check (no auth required)
curl http://localhost:7777/v1/health

# Create a session
curl -X POST http://localhost:7777/v1/session \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider":"anthropic","model":"claude-sonnet-4-6"}'

# List sessions
curl http://localhost:7777/v1/session \
  -H "Authorization: Bearer $TOKEN"

# Send a message (SSE stream)
curl -N http://localhost:7777/v1/session/<id>/message \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"refactor the auth module"}'

The token is stored at ~/.aurict/server-token (mode 600) and regenerated if deleted.

Configuration

Aurict stores global configuration in ~/.aurict/ and project configuration in <workdir>/.aurict/:

~/.aurict/
├── aurict.db           # SQLite database (sessions, config, MCP servers, memory)
├── server-token        # HTTP API bearer token (chmod 600)
├── config.json         # Provider defaults and global settings
└── plugins/            # Installed plugins

<workdir>/.aurict/
├── config.json         # Project-level overrides
├── todos.json          # Task list (per working directory)
├── decisions/          # Architecture decision records (/adr)
└── diagnostics/        # Tool failure records (/diag)

To set a default provider and model:

aurict /config set default.provider anthropic
aurict /config set default.model claude-sonnet-4-6

Development

bun install              # install dependencies
bun run dev              # start in development mode (hot reload)
bun run test             # run the test suite
bun run eval -- --smoke  # deterministic reference eval smoke
bun run typecheck        # TypeScript strict check (both packages)
bun run build            # compile to standalone binary → dist/aurict

Project Structure

aurict/
├── packages/
│   ├── core/            # Agent engine, tools, providers, storage, server
│   │   ├── src/
│   │   │   ├── agent/       # Agent loop, compaction, protocol
│   │   │   ├── tool/        # Tool registry, built-ins, classifier, sandbox
│   │   │   ├── provider/    # Anthropic, OpenAI, Google, OpenRouter, Ollama
│   │   │   ├── server/      # Hono HTTP API, auth middleware
│   │   │   ├── storage/     # SQLite, Drizzle ORM, schema
│   │   │   └── design/      # Design systems, skill templates, matcher
│   │   └── test/            # 92 unit tests
│   └── cli/             # Ink TUI, commands, keybindings
│       ├── src/
│       │   ├── tui/         # React components (Ink)
│       │   ├── commands/    # Slash command registry
│       │   └── utils/       # Theme, highlight, token display
│       └── test/            # 39 TUI component tests
├── scripts/
│   └── build.ts         # bun build --compile → dist/aurict
└── dist/
    └── aurict          # Compiled binary (~103 MB, Bun runtime embedded)

Running Tests

# All tests
bun run test

# Core only
bun run test:core

# CLI and terminal tests
bun run test:cli

# Desktop tests
bun run test:desktop

# Coverage and randomized repeat gates
bun run test:coverage
bun run test:stability

# Single file
bun test packages/core/test/classifier.test.ts

# Agent eval harness
bun run eval -- --list
bun run eval -- --json

Each suite runs with isolated state under the operating-system temporary directory; tests do not write to the user's Aurict state. Test coverage includes: bash classifier, token counting, permission system, context compaction, sandbox detection, agent pool, HTTP server auth, and TUI components (Spinner, Markdown, StatusBar, StartupBanner).

Eval coverage includes small repo fixtures for bug fixes, multi-file refactors, policy sandbox documentation honesty, and string utility changes.

Tech Stack