claux

A terminal-based AI coding assistant written in Rust. Streams responses, executes tools, manages sessions, and stays out of your way.

Features

• Streaming chat with tool execution (Read, Write, Edit, Glob, Grep, Bash, WebFetch, Agent)
• Interactive permissions — prompts before writes, y/n/a; type a message at the prompt instead to deny the tool and steer the model with it
• Mid-turn steering — type while claux is running tools and press Enter; the running tool is cancelled, remaining queued tools are skipped, and your message reaches the model immediately
• Interrupt anywhere — Ctrl+C during a turn cancels it cleanly (in-flight tool calls are paired with interrupted results, so the conversation stays valid); press Ctrl+C twice within 2s to quit the app (Ctrl+D still exits immediately)
• Session persistence — SQLite-backed with search; full transcripts including tool calls and results, so /resume and --resume restore exactly what the model saw. Histories from older versions are repaired on load
• Safe turn checkpoints — /diff shows exactly what the last turn changed; /undo-turn restores it only when no file has been edited since, so later human work is never overwritten
• Compaction — /compact summarizes conversation to free context
• Model switching — /model <name> mid-conversation
• Sub-agents — Agent tool spawns scoped sub-conversations. Sub-agents inherit the parent session's permission mode, so a sub-agent can't act with more authority than you granted the session. Because sub-agents run non-interactively, any tool the mode would prompt for is denied rather than auto-run (Plan denies all writes; Bypass allows all)
• Auto-compact — triggers when conversation gets large
• Cost tracking — per-model token usage and USD estimates
• Prompt caching — automatic Anthropic cache breakpoints on the system prompt and conversation, cutting input cost and latency on long sessions
• Context assembly — git status, CLAUDE.md, environment info in system prompt
• TUI mode — full-screen ratatui interface with --tui
• Multi-provider — Anthropic, OpenAI, Ollama, or any OpenAI-compatible endpoint
• Native system prompt — claux speaks as claux; the full prompt is readable in src/context.rs, and what you read is what the model gets
• Markdown rendering — code blocks, bold, headers in the TUI

Screenshots

The TUI in action. These are generated by tuishot from claux's own code — cargo test fails if they drift, so they can't go stale.

Install

# From crates.io
cargo install claux

# From source
cargo install --path .

Requires Rust 1.88+. A shell.nix is included.

First run

Create a starter configuration for Anthropic, OpenAI, or Ollama, then verify authentication, required executables, configured hooks/MCP servers, project trust, and provider connectivity:

claux config init --provider anthropic
claux doctor

# Other examples
claux config init --provider openai --model gpt-5.6-sol
claux config init --provider ollama --model llama3
claux doctor --offline  # configuration checks without a network request

The generated file contains environment-variable names, never API keys. Claux creates it with private permissions and refuses to overwrite an existing file unless --force is explicit.

Auth

claux resolves authentication in order:

1. api_key in ~/.config/claux/config.toml
2. api_key_cmd (shell command that returns a key)
3. ANTHROPIC_API_KEY environment variable

Claude Free, Pro, and Max subscription credentials are not supported. Use an Anthropic API key or an OpenAI-compatible endpoint such as OpenRouter.

OpenAI-compatible providers

For Ollama, vLLM, LMStudio, OpenAI, or any hosted endpoint:

model = "llama3"
openai_base_url = "http://localhost:11434/v1"
openai_provider_name = "ollama"

API keys via command (works with 1Password, Vault, etc.):

model = "gpt-4o"
openai_base_url = "https://api.openai.com/v1"
openai_api_key_cmd = "op read 'op://vault/OpenAI/key'"
openai_provider_name = "openai"

Usage

# Interactive REPL (default)
claux

# Full-screen TUI
claux --tui

# One-shot
claux -p "explain this error"

# Resume a session
claux --resume 20260401-143022

Commands

Turn checkpoints cover Git-tracked files and non-ignored untracked files. Ignored files and paths outside the repository are deliberately excluded. /undo-turn first verifies that every affected file still matches the end of the turn; if anything changed afterward, it refuses the entire undo.

Config

Global: ~/.config/claux/config.toml

model = "claude-sonnet-5"
permission_mode = "default"  # default | accept-edits | bypass | plan

# Project-local .claux.toml files may tighten this mode without trust, but
# cannot loosen it unless their directory is listed here or --trust-project
# is passed for the invocation. Project-local .mcp.json uses the same boundary.
trusted_projects = ["/absolute/path/to/a/trusted/project"]

# OpenAI Responses API (recommended for current reasoning and coding models).
# The key is read from OPENAI_API_KEY by default; do not store it here.
# model = "gpt-5.6-sol"
# openai_base_url = "https://api.openai.com/v1"
# openai_protocol = "responses"
# openai_provider_name = "openai"
# openai_reasoning_effort = "medium"

# Optional pricing overrides, in USD per million tokens. Built-in prices are
# used for known models; unknown models display "Cost: unavailable".
# [model_pricing."gpt-5.6-sol"]
# input = 5.0
# output = 30.0
# cache_read = 0.5
# cache_write = 6.25

Per-project: .claux.toml in the project root (overrides global).

Hooks

Run a command on a lifecycle event. Each [[plugins]] entry runs its command when the matching trigger fires. Nothing about the command lives in claux - it's your config, so a hook can drive anything: a status light, a notification, a logger, a metrics counter.

[[plugins]]
name = "lamp-idle"
command = "glow-hook"
args = ["purple"]
trigger = "on_session_start"

[[plugins]]
name = "lamp-working"
command = "glow-hook"
args = ["blue"]
trigger = "on_tool_start"

[[plugins]]
name = "lamp-your-turn"
command = "glow-hook"
args = ["green"]
trigger = "on_turn_end"

[[plugins]]
name = "lamp-needs-you"
command = "glow-hook"
args = ["orange"]
trigger = "on_permission_request"

The example above is a glow status lamp: your keyboard's RGB tracks what claux is doing. on_context_build is special - its stdout is added to the system prompt; the rest are bounded side effects. Hook commands run concurrently with a 10-second timeout and bounded captured output.

Permission Modes

In accept-edits mode, Agent, MCP, and other non-read-only tools still require explicit approval. Sub-agents inherit the parent permission mode; because they are non-interactive, operations that would require another prompt are denied.

Agent evaluations

Claux has fixture-driven behavioral evaluations for complete multi-round turns, including real tool execution in isolated workspaces, permissions, steering, file outcomes, recovery, and provider stream failures:

cargo test evals::deterministic_agent_contracts -- --nocapture

They require no credentials or network and run as a dedicated CI check. An ignored paid-provider smoke test and manual workflow are also available; see evals/README.md.

License

MIT