Install and first run

Building from source, pointing it at a model, and the first conversation.

Take the binary

On Linux x86-64 there is a prebuilt binary and no toolchain is needed. The installer downloads the archive of the newest release, verifies it against the published SHA256SUMS, and unpacks the binary into ~/.local/bin, or into $PREFIX/bin when that is set. It never needs root, it touches nothing else, and it says afterwards whether the directory it wrote to is on your PATH.

curl -fsSL https://gitlab.com/porky11/revolve-agent/-/raw/master/install.sh | sh

The binary is statically linked against musl, so it runs on any distribution. Windows is coming: the build is cross-compiled with mingw and waits on the session socket being ported to named pipes. Every release, its archives and its checksums are on the releases page, and tools/release.sh in the repository builds and packages the same archives on your own machine.

Build it

Everywhere else, build it yourself. Revolve is a Rust program and is built with cargo. A stable toolchain new enough for edition 2024 is required.

git clone https://gitlab.com/porky11/revolve-agent
cd revolve-agent
cargo install --path tui

That puts a revolve binary in ~/.cargo/bin. The repository root is a virtual cargo workspace of three members and holds no package of its own, so the path names the member you want: tui is the terminal binary, gui is the revolve-gui window, and core is the task-agent library both are built on. To try it without installing, cargo run -p revolve inside the clone starts the terminal binary — a bare cargo run cannot choose between revolve and revolve-gui — and everything on these pages that says revolve can be written cargo run -q -p revolve -- instead.

The terminal front end is a crate rather than a feature: core/ never links a terminal library, so a host program embedding the agent depends on task-agent and gets no ratatui, crossterm or idet in its graph. One cargo feature exists:

Give it a model

The quickest start is an API key in the environment and no config file at all. Revolve reads the key of every provider in the compiled catalog and offers every model those keys reach. Which one it starts on is the first provider a key reaches, preferring anthropic, openai, deepseek, zai, zhipuai and mistral in that order and falling back to any other provider whose key is set, and within that provider the model with the widest context window. A Claude Code login counts as a credential of its own, so revolve login alone is enough as well. It names the model it picked at startup, so you know you are on the fallback.

export ANTHROPIC_API_KEY=sk-...
revolve

For anything beyond that — a different endpoint, several providers, a thinking effort, a declared context window — write ~/.config/task-agent/config.cfg as described under Configuration.

The first conversation

Run revolve in the directory you want worked on. That directory is the sandbox: it is what the agent may read and write, and nothing above it.

cd ~/projects/my-thing
revolve

You get a full-screen view with your input at the bottom and the conversation above it. Type a message and press Enter. The answer streams in as it is written. Esc stops a turn that is running; Ctrl+Q quits.

Some things worth doing in that first session:

• /help lists every chat command and every skill installed.
• /info prints which model you are on, where the session file is, and what the turn has cost so far.
• /name my-session gives the conversation a name, so revolve my-session brings it back later.

Without a terminal

If standard input is a pipe rather than a terminal, revolve runs one turn per input line and prints to standard output. This is the shortest way to check that a build works:

printf '/help\nWhat is 2+2?\n' | revolve

And a single question with a single answer:

revolve -p "Read README.md and tell me the first heading."

In both of these nobody can answer a permission prompt, so an unknown command is denied with a note instead of asking. --allow-all runs it anyway, and never overrides a deny rule.

Where it keeps things

$XDG_CONFIG_HOME and $XDG_STATE_HOME are honored where they are set.