Cersei: a Rust SDK for building coding agents from composable parts

The gap Cersei fills: an agent loop you can call from Rust

Most coding agents ship as terminal applications. Claude Code and OpenCode are CLI apps, and the README's own comparison table marks both as not embeddable. If you want an agent inside a Rust service, a build step, or a desktop tool, you either shell out to a binary and parse its output, or you reimplement the loop. Cersei is the second option made cheaper: a library where the agent loop, the tool registry, the provider clients and the memory layer are ordinary Rust functions you compose yourself.

The intended audience is narrow but real. You should already be comfortable with async Rust, the tokio runtime and trait-based extension. The README's opening example is the whole pitch in eight lines: build an Agent, attach a provider, attach a tool set, set a permission policy, call run_with with a prompt. Everything else in the workspace exists to make those four choices configurable.

How the workspace is split, and why that matters for dependency weight

Cersei is a Cargo workspace, not a single crate. The facade crate cersei re-exports a prelude, and beneath it sit cersei-types for provider-agnostic messages and stream events, cersei-provider for the Provider trait plus Anthropic and OpenAI implementations, cersei-tools for the built-in tool sets, permissions, bash classifier, skills and git utilities, cersei-agent for the builder, agentic loop, compaction, coordinator and effort levels, cersei-memory for the memory trait, memdir, CLAUDE.md handling, sessions and the Grafeo graph, cersei-hooks for middleware, and cersei-mcp for an MCP client speaking JSON-RPC 2.0 over stdio.

The workspace members list goes further than the README's architecture diagram: cersei-lsp, cersei-embeddings, cersei-compression, cersei-skills, cersei-vms, cersei-agentlang, cersei-agentrl, cersei-workflows and cersei-tbench are all members, alongside abstract-cli and a bench/long-mem crate. None of those extra crates are described in the README, so treat their APIs as unverified. The practical consequence is that a dependency on cersei pulls a workspace whose version is declared once at 0.2.6 under [workspace.package]; there are no published release notes in the repository, so the version number is the only signal of where the code stands.

One detail in the workspace dependencies is worth reading closely. The reqwest dependency enables hickory-dns, and the accompanying comment explains why: the default getaddrinfo resolver fails in a static musl build because there is no NSS, which silently breaks every outbound API call. That is a real operational trap for anyone shipping a static binary, and the repository documents the fix at the dependency level.

Installing Cersei as a git dependency and running a first agent

The README gives no crates.io install line. The install section is a Cargo.toml snippet pointing at the GitHub repository, so you are pinning to a git source rather than a version from the registry. Add the facade crate, tokio and anyhow to your manifest:

[dependencies]
cersei = { git = "https://github.com/pacifio/cersei" }
tokio = { version = "1", features = ["full"] }
anyhow = "1"

Graph-backed memory is a separate crate with a feature flag, so it does not come along by default:

cersei-memory = { git = "https://github.com/pacifio/cersei", features = ["graph"] }

The first real use is the README's own example. It builds an agent against Anthropic, loads the coding tool set (filesystem, shell and web), sets a permission policy that allows everything, and runs a prompt. Anthropic::from_env reads the API key from the environment, so export that before running:

use cersei::prelude::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let output = Agent::builder()
        .provider(Anthropic::from_env()?)
        .tools(cersei::tools::coding())
        .permission_policy(AllowAll)
        .run_with("Fix the failing tests in src/")
        .await?;

    println!("{}", output.text());
    Ok(())
}

What you should see is the agent's final text printed to stdout. Note that AllowAll is the README's choice for a demo, not a default you should carry into anything that runs unattended. Swapping providers is a builder change: the README shows OpenAi::builder with base_url set to http://localhost:11434/v1, model llama3.1:70b and api_key "ollama" for a local Ollama server, and any type implementing Provider can be passed instead.

Custom tools are the other extension point. The README's derive example declares a struct with #[derive(Tool)] and attributes for name, description and permission, then implements ToolExecute with an Input type that derives Deserialize and JsonSchema. The README carries a warning here that is easy to miss: the macro generates code referencing #[async_trait::async_trait] and cersei-tools, so both must be in your dependencies, or you alias the crate with use cersei::tools as cersei_tools.

Where the README stops short

The documentation is uneven in a way that will cost you time. The README advertises sessions, compaction, hooks, skills, MCP and twelve slash commands, but shows the API for almost none of them. There is no example of configuring cersei-hooks, no snippet for the MCP client, and no rollback story for a session that a sub-agent corrupts. For a library whose selling point is composability, the composition surface is the least documented part.

Two claims deserve scepticism rather than acceptance. The first is the benchmark table, which the README attributes to run_tool_bench.sh --full and to crates/abstract-cli/benchmarks/REPORT.md. Those numbers compare Abstract, a CLI, against Claude Code, and several of them (memory recall at 98us versus 7,545ms) are comparing a graph index lookup against a full model call. That is a fair architectural contrast, but the headline multipliers invite you to read them as general speed. They are not measurements of the SDK, which has no startup time at all because it is a library.

The second is the origin claim: Cersei is described as built from the architecture of Claude Code, a reverse-engineered Rust port. That tells you the design vocabulary will feel familiar if you know Claude Code, and it also tells you the project inherits assumptions from a closed product. Where the README says Abstract supports Claude Code-compatible JSONL sessions and both .claude/commands/ and .claude/skills/ formats, compatibility is asserted without a conformance test in the repository.

The clearest wrong-tool case is the one the README half-admits. If you want a coding agent in your terminal this afternoon, Cersei is not it. Abstract is, and its only documented install is cargo install --path crates/abstract-cli, which means cloning the repository and building from a local path. There is no published binary in the repository.

Cersei against the provider-agnostic TypeScript option

The obvious alternative for a multi-provider coding agent is OpenCode, which the README's table lists as a TypeScript CLI app with multi-provider support and SQLite-backed memory. The difference in approach is not the feature list, it is where the agent lives. OpenCode is a process you configure and run; its extension points are plugins loaded into that process. Cersei is a crate you depend on; its extension points are Rust traits, and the tool derive macro generates the glue. If your product is a CLI, OpenCode gives you a working one. If your product is a service that happens to need an agent, Cersei lets the agent be a module rather than a subprocess.

Language is the other axis. Choosing Cersei means your agent code compiles with the rest of your Rust workspace, shares its error types and async runtime, and ships in the same binary. The cost is that every provider, tool and memory backend you want has to exist as a Rust implementation or an MCP server. The README lists Anthropic, OpenAI, Ollama, Azure and vLLM as reachable through the OpenAI-compatible path, which covers most self-hosted setups, but there is no Python or JavaScript bridge described.

Licence, maintenance and what an upgrade costs you

The workspace declares license = "MIT" under [workspace.package], and the README states MIT License at the top. For a library you link into a product, that is the permissive end of the spectrum: no copyleft obligation on your own code. It says nothing about the licences of the dependencies you inherit, and the workspace pulls in reqwest, tokio, serde and a tracing stack, so a licence audit of your lockfile is still your job. Nothing here is legal advice.

The repository is not archived, and the last push was on 2026-08-06. That is recent enough that the code is moving, but the repository contains no release history at all, so you cannot see whether 0.2.6 is a tagged release or simply the current workspace version. Plan for a git dependency with no changelog to read: the upgrade cost is reading diffs in cersei-types and cersei-provider, since those define the traits your code implements and the messages it exchanges. The CHANGELOG.md file exists at the repository root, which is the first place to look before bumping the pinned revision.

Editorial conclusion

Adopt Cersei if you are writing a Rust service or CLI that needs an agent loop you can instrument, and you accept pinning to a git dependency because the README documents no crates.io release. Skip it if you want a finished terminal agent today, since Abstract is built from the same workspace and is only installable from a path. Before committing, read the cersei-agent and cersei-tools sources to confirm the permission model and the memory feature flags match what you need.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pacifio/cersei on GitHub
4. Project website
5. README