x documentation

Everything you need to use x — the local coding agent that wraps Claude Code with strict-write discipline, static analysis, and persistent memory.

Installation

Download x from the download page. Once installed, launch it from any project directory:

$ x chat

First Run

Run x in any project directory. The agent will:

• Detect your project structure and language
• Read CLAUDE.md for project-specific context and rules
• Initialize the agentic memory layer
• Start an interactive session with Claude

$ cd my-project
$ x
# x reads CLAUDE.md, initializes memory, starts agent loop

Configuration

x is configured through three layers, in order of precedence:

1. CLI flags — --budget, --provider, --model
2. Environment variables — X_BUDGET, X_PROVIDER
3. CLAUDE.md — project-level context and rules

Core Concepts

Strict-Write Discipline

Every file operation in x goes through write verification. When the agent writes a file, x confirms:

• The file was actually written to disk
• The content matches the agent's intent
• No partial writes or corruption occurred
• The file passes static analysis post-write

This eliminates an entire class of silent failures where the agent thinks it wrote code but the file system disagrees. Every write is verified or the agent is notified of the failure.

Static Analysis

x runs AST-grade static analysis on every code change. This catches structural errors — syntax issues, unresolved imports, type mismatches — before they compound into larger problems.

Analysis runs automatically. No configuration needed. Results are fed back into the agent loop so Claude can self-correct in the same turn.

Chat Visualization

Responses stream token-by-token with inline markdown rendering — headers, bold, italic, code, links, and bullets all render in real-time as tokens arrive.

After each turn, file-operation indicators show what changed:

  files: 2 created, 1 modified
    +  src/auth.ts
    +  src/auth.test.ts
    ~  src/index.ts

Status glyphs: + (created), - (removed), ~ (modified), · (pending), ✓ (ok), ✗ (fail). Action counts and confirmation prompts appear for write operations.

A per-project awareness protocol (.x/awareness/protocol.json) tracks stimulus→response→consequence patterns across sessions, emitting insight labels when significant behavioral shifts are detected.

Agentic Memory

x maintains a persistent memory layer at ~/.claude/projects/. Memory is organized semantically by topic, not chronologically. The agent stores:

• Project patterns and conventions confirmed across sessions
• Architectural decisions and key file paths
• Solutions to recurring problems
• User preferences for workflow and tools

Memory persists across sessions and is automatically consulted when relevant context is needed.

Shell Commands

These commands run from your terminal. Most have a corresponding slash command for use inside x chat.

x run

Execute the agent on a task. This is the default command — running x with no subcommand is equivalent to x run.

$ x run [options] "task description"

x bench

Run the benchmark harness against a test suite.

$ x bench [suite.json] [--concurrent N]

x stats

Display session statistics — token usage, cost, duration, and write counts.

$ x stats [--json] [--since 7d]

x budget

View or modify budget limits for the current project or globally.

$ x budget                    # show current limits
$ x budget --set 10.00        # set session limit to $10
$ x budget --global 50.00     # set global daily limit

x build

Generate full-stack applications from domain blueprints using vertical-slice architecture. Each slice delivers an end-to-end feature — migration + API + UI — that builds on the previous one.

$ x build init -d social       # scaffold from domain blueprint
$ x build plan                  # show vertical-slice execution plan
$ x build auto                  # autonomous build via worktrees
$ x build status                # show build progress

In x chat, blueprint context activates automatically from natural language — no commands needed. Say “build me a playful social app” and the intent detector classifies your request, extracts domain and design preferences, and wires up the blueprint engine. Brand docs and PRDs referenced with @file syntax are parsed for colors, fonts, tone, and stack preferences.

Chat Commands

Inside x chat, slash commands and phrase triggers give you control without leaving the conversation.

/ Slash Commands

Type these directly in the chat input. They execute immediately without sending a message to Claude.

Many slash commands mirror shell commands. For example, /scan in chat does the same thing as x scan from your terminal.

Phrase Triggers

You don't need slash commands for everything. Just talk naturally — x recognizes analysis-related phrases and runs the appropriate scan before your message reaches Claude.

Triggers are conservative — x only runs analysis when it's confident you're asking for it. Results are injected as context so Claude can act on the findings directly.

Configuration

CLAUDE.md

The CLAUDE.md file is the project context document that x reads on every run. Place it in your project root. It shapes agent behavior — coding conventions, architectural decisions, file organization rules.

# Project: my-app
# Language: TypeScript
# Framework: Next.js 14

Use named exports, not default exports.
Always use server components unless client interactivity is required.
Run `npm test` before suggesting a commit.
Never modify files in /generated/.

Budget Limits

Budget controls prevent runaway API spend. Set them via CLI flag, environment variable, or the x budget command.

# In .bashrc or .zshrc
export X_BUDGET=10.00          # per-session limit
export X_BUDGET_GLOBAL=50.00   # daily global limit

When the budget is exhausted, x pauses and prompts for confirmation before continuing.

Provider Settings

By default, x auto-selects the provider based on available credentials. Use --provider to force a specific backend:

$ x run --provider anthropic "refactor auth module"
$ x run --provider bedrock "add unit tests"

Advanced

Benchmark Harness

The benchmark harness runs reproducible test suites defined in JSON. Each suite contains cases with a prompt, expected behavior, and pass criteria.

{
  "name": "core-refactors",
  "cases": [
    {
      "prompt": "extract the auth logic into a separate module",
      "expect": "file:src/auth.ts exists",
      "budget": 2.00
    }
  ]
}

Run with x bench bench/example-suite.json. Results include pass/fail, cost, duration, and token usage per case.

Gateway & Sandbox

The gateway proxies API requests through a local server, enabling request logging, rate limiting, and cost tracking. The sandbox provides an isolated execution environment for untrusted operations.

$ x serve --port 8080        # start gateway server
$ x run --sandbox              # run in sandboxed mode

Cron Jobs

Schedule recurring agent tasks with x cron. Useful for nightly test runs, dependency updates, or periodic code audits.

$ x cron --every 24h "run tests and report failures"
$ x cron --list              # show scheduled jobs
$ x cron --delete job_id   # remove a scheduled job