Quick Start

Install Caudra, connect a provider, and run a first session. Caudra is an independent fork whose release line starts at 0.1.0.

Install

Linux / macOS

# Download and read the script first (don't blindly trust shell scripts).
curl -fsSL https://caudra.ai/install.sh -o install.sh
cat install.sh

# Then run.
chmod +x install.sh && sh install.sh

One-liner:

curl -fsSL https://caudra.ai/install.sh | sh

Installs to ~/.local/bin. Override with CAUDRA_INSTALL_DIR.

Windows (PowerShell)

# Download and read the script first (don't blindly trust remote scripts).
irm https://caudra.ai/install.ps1 -OutFile install.ps1
Get-Content install.ps1

# Then run.
.\install.ps1

One-liner:

irm https://caudra.ai/install.ps1 | iex

Windows (Git Bash)

curl -fsSL https://caudra.ai/install.sh | sh

Both install to %LOCALAPPDATA%\caudra and add it to your user PATH. Override with CAUDRA_INSTALL_DIR / $env:CAUDRA_INSTALL_DIR.

Living on the edge (main branch)

cargo install --locked --git https://github.com/caudra/caudra.git caudra

This build leaves out python_execution, because only release builds, Nix, and just install from a checkout embed its worker. The other tools work as usual.

With Nix

nix run github:caudra/caudra

Or download a pre-built binary from GitHub Releases.

Connect a provider

caudra auth login                           # choose a provider and auth method
caudra auth login anthropic                 # Claude subscription OAuth
caudra auth login openai                    # ChatGPT/Codex subscription OAuth
caudra auth login anthropic --method api-key

Open /login inside the TUI for the same OAuth and API-key choices. You can also set provider environment variables such as ANTHROPIC_API_KEY. Multiple keys in one variable rotate on rate limits. Every env var and model catalog is in Providers.

First session

From a repo:

caudra

Type what you want done, press Enter, watch it work. Worth knowing on day one:

• Permissions. File edits inside the repo run freely. shell and web tools ask first: y allows once, s remembers the scope shown between ‹ and › for the conversation, and a remembers it for the project. ← broadens that scope and → narrows it. Deny rules always win. /yolo skips prompts after deny checks. Details in Permissions.
• Plan mode. Caudra opens here, so the plan file is the only thing the agent writes until you approve. Ctrl+O opens the plan in the workbench to read or edit before you do. The agent reads and searches freely, and runs read-only shell commands like git log and rg. Anything else asks first. You can approve it for the conversation, or keep a narrow scope such as git log * for the project. A broad scope lasts the conversation at most, and nothing allowed while planning applies to all projects. /yolo runs such commands without asking and stores no rule. Tab toggles plan mode, taking effect with your next message: the status bar reads [PLAN→BUILD] while the switch is still pending. The toggle also brings back the model that mode was last used with, shown the same way as [claude-opus-5→claude-sonnet-5]. A resumed session reopens in the mode you left it in.
• Models. /model switches the Chat model and assigns models to jobs such as Plan and Subagent. See Providers.
• Status bar. The footer has two rows. The top row shows what your next message runs with: the mode, the model, and the reasoning level, plus [fast] and [yolo] while they are on. The bottom row shows what is happening now: running tasks, shells, and workflows, any retry or error, and the context and cost meters. When the terminal narrows, each row shortens only its own chips, so a long error never hides the model. A terminal shorter than 20 rows keeps a single row. Clicking a chip changes that setting or opens its view.
• Sessions. /new starts a second session while the first keeps working in the background; /sessions jumps between them. Tomorrow, caudra --continue resumes where you left off.
• Message actions. Click ⋮ beside a conversation message to fork or revert there. Right-clicking the message is an optional shortcut when the terminal forwards it. See Sessions, Forks, and Revert for history boundaries, file revert, conflicts, and unrevert.
• Queue and steering. While Caudra works, Enter sends the prompt next, Ctrl+X g guides the current run, and Ctrl+X x stops and replaces it. See Queue and Steering.
• Tasks. Click a task call to inspect its subagent transcript. Send guidance from the task input while it runs, then click [< Main] to return. /tasks, Ctrl+X a, or the task count above the input opens every task. /shells or the shell count lists the shell commands the agents ran, where you can stop a running one. See task navigation, shell commands, and background tasks.
• Dismissing a modal. Esc closes the panel or picker in front of you, and so does a press anywhere outside it. That press is swallowed, so it does not also act on what is under it. The permission prompt, the question form, the plan form, and the paste editor stay where they are, because each is waiting on an answer or holding text only you have. On the question form, Esc answers nothing and the agent carries on. Ctrl+C stops the agent that asked, so the run waits for your next message.
• Your shell. Prefix input with ! to run a command yourself (!cargo test). !! hides command and output from the agent.
• Escape hatch. Esc Esc stops the main run and all session tasks and workflows. With no session work left, it opens rewind instead. See Stop and replace.
• Help. F1 lists every keybinding, or see Keybindings.
• These docs. /docs opens this manual inside Caudra, for the version you run, and / searches every page. The agent reads the same pages through the caudra-docs skill.

Default model (optional)

~/.config/caudra/caudra.toml

[provider]
default_model = "anthropic/claude-sonnet-4-6"

Without it, Caudra remembers the last model you used in each mode. Pick a strong model while planning and a cheaper one for building, and Tab moves between them with you.

Settings live in caudra.toml (Windows: %APPDATA%\caudra\caudra.toml) and need no Lua. Workflows, managed sandboxes, direct remote Workcell connections, Lua plugins, the decision engine, and cross-session messages are experimental and stay off until you turn them on in the global file. See Experimental features.

Teach it your project

Caudra loads AGENTS.md (or CLAUDE.md, .cursorrules, and friends) from your repo automatically. Per-project settings live under .caudra/:

.caudra/
├── caudra.toml        # overrides global settings
├── permissions.toml   # restrictive project permission policy
├── mcp.toml           # MCP server config
├── commands/          # custom slash commands (.md files)
└── skills/            # project skills (each dir has a SKILL.md)
AGENTS.md              # always in context
AGENTS.local.md        # personal per-project instructions (gitignored)

Which instruction file wins, when subdirectory rules load, and how skills and memory fit together: Context. All settings: Configuration.