Anima

Anima is a command centre for AI-driven software development. A human defines a unit of work precisely; AI coding agents implement it as tightly-scoped vertical slices. The quality comes from the plan, not from the implementer's exploration.

It is not a chat wrapper and not an autonomous "do my project" agent. It is the scheduling, review and bookkeeping layer around agent sessions: what gets dispatched, to which agent, with what prompt, under what budget, and what has to be true before the work moves on.

• Licence: MPL-2.0
• Canonical repository: https://code.aopc.cloud/toasterson/Anima
• Status: v0.1.1, pre-release and self-hosted. First commit 11 April 2026; ~1300 commits since. Anima runs its own development — most merges in the log are agent sessions dispatched by the system on its own repository.

The model

Six nouns carry the whole system. They are defined once, in CONTEXT.md, and the code uses no synonyms for them.

Term	Meaning
Plan	The human-defined intent and its decomposition. The Define-side anchor.
Slice	The 1:1 execution wrapper for a Plan; the operator's monitoring surface.
Work Item	One small vertical slice of implementation — a thin path through the layers. Carries its own forcing prompt.
Workflow	A reusable ordered set of Phases, attached to the Define side, the Implement side, or both.
Phase	One step in a Workflow, carrying the prompt that drives it.
Phase kind	Who acts: Agent (an ACP session, consumes a slot), Human (opens a thread message and waits), Machine (triggers CI).

Three design decisions are worth calling out, because they are what make the loop safe to leave running:

Forcing prompts. A Work Item is not handed to an agent as a title. It carries a prompt assembled from the Plan plus the Phase's own prompt, so the agent's context is constructed rather than discovered. anima-ai is the assembler.

Graph versioning. A Work Item is pinned on entry to an immutable revision of the phase graph. Rewiring a workflow never moves in-flight items — they finish on their version, new items start on the current one. This is what lets an operator edit the flow while work is running, and what lets per-(item, phase) counters survive the rewire.

Bounded redispatch. Phases have exit bars and a loop guard, so an item that cannot pass its own gate strands visibly instead of burning tokens in a cycle. Agent lanes carry quotas; a lane that is failing is backed off rather than probed.

The reasoning behind these is recorded as 37 ADRs in docs/adr/, starting at 0001 — plan/slice one-to-one.

Agents are pluggable — Anima is not tied to a vendor

Agent sessions are hosted over the Agent Client Protocol (ACP) on stdio, one subprocess per slot. The executors are configuration, not code: claude-code, gemini-cli, codex, opencode and ollama-cloud lanes are all driven through the same path, and the runner never spawns containers of its own — the server assigns work to advertised slots.

The separate anima-ai service, used for prompt assembly and summarisation rather than for coding, addresses three configurable tiers (MINIMAL, STANDARD, REASONING), each with its own base URL, key and model name. Pointing a tier at a local or self-hosted endpoint is an environment variable, not a patch.

Architecture

A Rust workspace of twelve crates, a gRPC/Protobuf API, PostgreSQL, and a React PWA speaking Connect-Web to the same schema.

Crate	Role
anima-core	Domain types, auth, RBAC, the diff gate
anima-proto	Generated types for 27 .proto service and message files
anima-db	SQLx repositories and 100 ordered migrations
anima-server	The gRPC service surface, plus an MCP endpoint exposing Anima's own tool catalogue
anima-ai	Forcing-prompt assembly and the tiered model client
anima-runner	Static stateful ACP runner; advertises slots, hosts agent subprocesses over stdio
anima-forgejo	Forgejo REST client — pull requests and repository metadata
anima-git	A VcsClient trait with a shell-out git implementation
anima-solstice	Dispatch and log retrieval against the Solstice CI system
anima-mq	RabbitMQ topology for the execution and streaming fabrics
anima-bridge	Diagnostic CLI for inspecting work item state
anima-anthropic	Thin Messages API client. Not a workspace member — present in-tree, unwired.

Cross-cutting: tokio, tonic 0.13 for gRPC and gRPC-Web, sqlx 0.8 against PostgreSQL 18, lapin for AMQP, axum, and OpenTelemetry 0.31 for OTLP traces and metrics. The PWA is React 19 with @connectrpc/connect-query, TanStack Query, Tailwind and Vite, tested with Vitest and Testing Library.

Running Anima

Anima runs on Kubernetes everywhere. The services come from the Helm chart in deploy/helm/anima (anima-server, the streaming edge, optional anima-ai and mail workers), applied by Flux from the homelab GitOps repo, which also owns PostgreSQL, RabbitMQ, the grpc-web proxy and the PWA. The runner fleet is not in the chart: it runs as k0s pods on archibald (with a dind sidecar for in-container builds) and as native launchd services on the operator's Mac, both deployed from the same GitOps repo. There is no Docker Compose stack any more; a docker compose file or command anywhere in this repo is a regression.

For local development run PostgreSQL 18 and RabbitMQ however you like and start the server from source; migrations run on server start:

DATABASE_URL=postgres://anima:anima@localhost/anima \
ANIMA_LIVE_BUS_URL=amqp://guest:guest@localhost:5672/%2f \
LISTEN_ADDR=0.0.0.0:50051 MCP_LISTEN_ADDR=0.0.0.0:50054 \
BOOTSTRAP_ADMIN_PASSWORD=admin \
cargo run -p anima-server

The model tiers need MINIMAL_API_URL / MINIMAL_API_KEY and their STANDARD_ and REASONING_ counterparts in the environment. To develop against the cluster instead, port-forward the service: kubectl -n anima port-forward svc/anima-server 50051:50051 50054:50054.

The runner is a long-lived process that dials out to the server's RunnerService and needs the agent CLIs on its own PATH. Dockerfile.runner is the pod image CI publishes, and deploy/runner/ holds the per-executor harness wrappers the image and the launchd fleet share. The PWA in anima-pwa/ is a normal Vite app (npm install && npm run dev).

The Ptah opportunistic lane runbook documents its opt-in outage policy and prepared hephaistos gateway configuration.

Licensing, dependencies and IP boundaries

• Anima itself is MPL-2.0 (LICENSE) — file-level copyleft. You can link it into a larger work under other terms; modifications to Anima's own files stay MPL.
• All dependencies are third-party upstream packages pulled from crates.io and npm at their published versions, under their own licences (predominantly MIT/Apache-2.0). None are vendored-and-modified; Cargo.lock and package-lock.json pin the exact set.
• No proprietary code, datasets or model weights are included, and none are required to build. Anima trains nothing and ships no weights.
• Model providers are external services reached over their public APIs. Anima holds no provider credentials of its own; keys are supplied by the operator through the environment. ACP agents (claude-code, gemini-cli, codex, opencode) are separately installed third-party programs under their own licences and terms — Anima executes them, does not redistribute them, and does not depend on any single one.
• Anima's own outputs — plans, prompts, work items, generated diffs — belong to the operator. Nothing is transmitted to the project's authors; there is no telemetry callback, and the OpenTelemetry exporter points wherever the operator configures it.