Getting started
Install
Section titled “Install”Install the latest release on Linux or macOS:
curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/Cretezy/cagent/main/scripts/install.sh | shThe installer detects Intel/AMD or Arm systems, downloads the matching binary from the latest
GitHub release, verifies its SHA-256 checksum, and installs it to ~/.local/bin. It explains how to
add that directory to PATH when needed.
Set CAGENT_BIN_DIR to use another destination. To build and install from the latest main instead:
curl https://raw.githubusercontent.com/Cretezy/cagent/main/scripts/install-from-source.sh | bashTo install your current checkout, run ./scripts/install-from-local.sh.
Start Cagent
Section titled “Start Cagent”Open the project you want to work on and run:
cd my-projectcagentThe first time you open a workspace, Cagent asks whether you trust it. Trust enables project configuration and MCP servers.
The onboarding screen will then guide you through choosing a provider, model, and reasoning effort.
Before starting, have credentials for one supported provider.
API keys can be entered in /providers or supplied through the provider’s environment variable;
subscription providers guide you through browser or device-code login.
Workspace trust allows .cagent/config.toml and project MCP servers to load. It does not allow
file writes, shell commands, network access, or MCP calls. Those still follow Permissions.
Send your first request
Section titled “Send your first request”Type a request and press Enter:
Explain how this project is structured and cite the files you inspect.Cagent can inspect the workspace, propose edits, run commands, and ask for permission when needed.
Use Shift+Enter or Alt+Enter for a newline.
Modes control whether edits and commands are allowed, as well as allows planning. Use Shift+Tab to cycle to the plan mode to request a plan.
The default mode, edit, allows read and writes within your workspace, and asks for unsafe Bash commands. The auto mode uses a classifier agent to accept safe permission requests.
Start with these commands:
| Command | Purpose |
|---|---|
/help |
Show commands and keybindings. |
/providers |
Connect or enable a provider. |
/model (Alt+P) |
Choose a model and reasoning effort. |
/mode (Shift+Tab) |
Choose how Cagent should work. |
/settings |
Change common settings. |
/resume |
Reopen a conversation. |
Run without the TUI
Section titled “Run without the TUI”Use exec for scripts and CI after trusting the workspace:
cagent --trust exec --output json "Run the tests and summarize failures"Headless runs cannot open questions or permission prompts. Unapproved operations are denied, so configure explicit mode/rules or restrict the task to already allowed tools. See Headless execution for output formats, tool filtering, and exit codes.
Build manually
Section titled “Build manually”Cagent requires Rust 1.97.1 or newer:
cargo build --release -p cagent-cli./target/release/cagentUse --dir DIR to start in another workspace, or explicit paths for a portable setup:
cagent --config ./cagent.toml --data-dir ./cagent-data --dir ./my-projectRelated
Section titled “Related”- Composer covers prompts, attachments, queues, and questions.
- Providers and models covers authentication and model selection.
- ACP integrations covers using Cagent in Zed and other ACP clients.
- Configuration covers UI, CLI, and TOML settings.
- Troubleshooting covers common setup failures.