animaworks

AnimaWorks — Organization-as-Code

An AI organization that ships software.

AnimaWorks turns persistent AI agents into a working organization. Give it a goal, and its agents break the work down, implement in parallel worktrees, test and review each other's changes, open pull requests, repair failing CI, resolve conflicts, and watch the deployed result — asking a human only when something genuinely needs one.

Task → agent team → parallel worktrees → implement → test → review
     → pull request → CI repair → deploy → observe → repair

AnimaWorks does not hardcode this pipeline. The framework wires GitHub events into agent tasks, serializes work per pull request, and orchestrates multi-model reviews; the agents run the rest the way human engineers do — with git, tests, CI, and role playbooks. That is why the same organization can also answer email, take meeting notes, and post to Slack: it is an organization, not a build script.

Proven in production

For the past six months, an eight-agent AnimaWorks organization has run the day-to-day development of a production SaaS product:

Metric (Mar–Aug 2026)	Value
Pull requests authored by agents	302 (267 merged)
Pull requests operated by agents — review, CI repair, conflict resolution	752 (721 merged)
Tasks the organization started on its own	99.7% (31,215 tasks; 92 initiated by a human)
GitHub events auto-converted into agent tasks, August alone	2,508

These numbers are counted from primary execution records — per-agent activity logs, task queues, and work notes — not from commit authorship, which mixes human and agent pushes under shared credentials. PRs without such evidence are excluded. The product repository is private, so only aggregates are published.

AnimaWorks is developed the same way: the agents defined in this repository review its pull requests, repair its CI, and ship its releases. The humans mostly set direction and handle exceptions.

日本語版 README | 简体中文 README | 한국어 README

---

:rocket: Try It Now

No API key needed if the Claude Code CLI is installed or you are logged into Codex.

First, clone and install with the one-liner:

curl -sSL https://raw.githubusercontent.com/xuiltul/animaworks/main/scripts/setup.sh | bash
cd animaworks

Then launch the demo team:

uv run animaworks demo

Open http://localhost:18501. A three-person team (manager + engineer + assistant) starts right away, pre-loaded with three days of activity history. The first install downloads Python 3.12+ and the ML dependencies, so give it a few minutes; after that, the demo starts in seconds. Demo details →

Presets: en-business (default), en-anime, ja-business, ja-anime — e.g. uv run animaworks demo --preset ja-anime. Switching presets on an existing demo requires --reset. The demo needs the cloned repository (it is not bundled in the pip package).

When you're ready to build your own organization, run uv run animaworks start — the setup wizard below walks you through creating your first agent.

---

Quick Start

macOS / Linux / WSL:

curl -sSL https://raw.githubusercontent.com/xuiltul/animaworks/main/scripts/setup.sh | bash
cd animaworks
uv sync --all-extras        # adds the codex/claude execution extras
animaworks start            # start server — setup wizard opens on first run

animaworks from any directory. setup.sh symlinks the CLI into ~/.local/bin, so you can drop the uv run prefix once that directory is on your PATH (add export PATH="$HOME/.local/bin:$PATH" to your shell rc if it is not). The console script pins this repo's .venv interpreter by absolute path, so animaworks and uv run animaworks always use the same environment. Installing manually? Link it yourself: ln -sfn "$PWD/.venv/bin/animaworks" ~/.local/bin/animaworks.

Windows (PowerShell):

git clone https://github.com/xuiltul/animaworks.git
cd animaworks
uv sync --all-extras
uv run animaworks start

To use OpenAI Codex without an API key, run codex login before the first launch.

Open http://localhost:18500/ — the setup wizard walks you through five steps:

1. Language — choose the UI display language
2. User info — create the owner account
3. Provider auth — enter API keys (or Codex Login for OpenAI) and pick an avatar image style
4. First Anima — name your first agent
5. Confirm — review and finish

You do not need to hand-edit .env. The wizard saves settings to config.json automatically.

The setup script installs uv, clones the repository, installs dependencies, and symlinks the animaworks CLI into ~/.local/bin. macOS, Linux, and WSL work without a pre-installed Python. On Windows, use the PowerShell steps above; note that Mode S (Claude Agent SDK) is not available on Windows — use Codex, Gemini, or API-based modes there.

Always use --all-extras with uv sync. The plain uv sync that setup.sh runs is enough for the core, but Mode C (Codex) needs the codex extra, and a later filtered sync can remove the codex / claude execution packages from the venv and break those modes across the fleet.

Other LLMs: Claude, GPT, Gemini, local models, and more are supported. Enter API keys in the setup wizard, or use Codex Login for OpenAI/Codex. You can change this later under Settings on the dashboard. See API Key Reference.

If you prefer not to pipe curl straight into bash, review the script first:

curl -sSL https://raw.githubusercontent.com/xuiltul/animaworks/main/scripts/setup.sh -o setup.sh
cat setup.sh            # review the script
bash setup.sh           # run after review

# Install uv (skip if already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# Clone and install
git clone https://github.com/xuiltul/animaworks.git && cd animaworks
uv sync --all-extras    # downloads Python 3.12+ and all dependencies (including codex/claude extras)

# Start
uv run animaworks start

git clone https://github.com/xuiltul/animaworks.git && cd animaworks
# Put credentials in .env (kept out of git):
#   ANTHROPIC_API_KEY=...            # API key auth
#   CLAUDE_CODE_OAUTH_TOKEN=...      # or subscription auth: `claude setup-token` (needs a TTY)
#   GH_TOKEN=...                     # optional: lets animas clone/push and open PRs
docker compose up -d --build

Headless setup (skip the browser setup wizard):

docker exec -it <container> animaworks init --skip-anima
docker exec -it <container> animaworks anima create --name alice --template dev-lead
docker exec -it <container> animaworks config set setup_complete true
docker exec -it <container> animaworks send <your-name> alice "hello"

• The image ships git / GitHub CLI / Node.js 22 / the Claude Code CLI, with IS_SANDBOX=1 and --foreground baked in. Data lives in a named volume animaworks-data (/root/.animaworks).
• Hand work to an anima from outside with animaworks send. animaworks-tool task add is for an anima's tool context only.
• Homebrew's docker-compose needs a symlink at ~/.docker/cli-plugins/docker-compose to be recognized as a docker compose subcommand.

macOS users: System Python (/usr/bin/python3) on macOS Sonoma and earlier is 3.9, which does not meet AnimaWorks (3.12+). Install with Homebrew (brew install python@3.13) or use the uv method above (uv manages Python for you).

Requires Python 3.12+ on your system (3.12/3.13 recommended).

git clone https://github.com/xuiltul/animaworks.git && cd animaworks
python3 -m venv .venv && source .venv/bin/activate
python3 --version       # verify 3.12+
pip install --upgrade pip && pip install -e .
animaworks start

Note: a plain pip install -e . does not include the Codex extra; add .[codex] if you plan to use Mode C.

---

How the loop works

A typical change moves through the organization like this:

1. A task arrives — from a human, from another agent, from a schedule (heartbeat / cron), or from a GitHub event. The webhook gateway turns CI failures, review comments, @bot commands, and merge conflicts into agent tasks automatically (gh-ci-*, gh-review-*, gh-comment-*), with per-PR deduplication and bounded retries.
2. A manager decomposes it and delegates pieces to engineers with delegate_task, carrying acceptance criteria, a workspace, and an exclusive key. Tasks that touch the same pull request are serialized on that key so agents never race each other on one branch.
3. Engineers implement and test in isolated worktrees, following role playbooks (PdM / engineer / reviewer / tester) shipped as shared knowledge. The isolation is a working convention the agents follow with git — not a rigid pipeline stage — which is what lets them handle the messy cases too.
4. Reviews are multi-model. For each pull request the framework dispatches one review pass per configured model, collects the findings, then issues a synthesis task that weighs all passes and delivers the verdict (approve / request changes). A new push cancels stale review tasks and starts over.
5. CI failures come back as work. A failed workflow run becomes a repair task for the implementing agent, keyed to the PR and commit so it is never dispatched twice. An experimental standalone loop (python3 -m swe.ci_autofix) can drive fix → lint/test gates → review → commit, escalating to a human after three failed attempts.
6. Deploys and runtime checks are agent work too. Agents deploy branches to isolated environments and read logs, errors, and UI state to catch what tests missed — the production organization logged hundreds of deploy and runtime-observation actions in its activity records.
7. Humans intervene on exceptions. The organization escalates when it is blocked or when a decision is above its authority (call_human); the supervisor process separately watches agent health, restarts hung processes, and repairs its own memory indexes.

The human role shifts from operating agents to owning an organization: state the intent, review what matters, decide the exceptions.

---

How It Compares

	AnimaWorks	CrewAI	LangGraph	OpenClaw	OpenAI Agents
Design philosophy	Organization of autonomous agents	Role-based teams	Graph workflows	Personal assistant	Lightweight SDK
Memory	Neuroscience-inspired: hybrid RAG (vector + BM25 + graph), atomic facts, consolidation, active forgetting, automatic recall	Cognitive Memory (manual forget)	Checkpoints + cross-thread store	SuperMemory knowledge graph	Session-scoped only