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:

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.

Workspace dashboard: each Anima's role, status, and recent actions are visible in real time.

The pixel office is not a simulation. It is a live view of the organization at work — every status label is a task actually running.

日本語版 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.

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

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"

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

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 is not a task runner. It is an organization that thinks, remembers, forgets, and gradually grows. I build it while using it as an AI team in real business operations.

What You Can Do

Dashboard

Dashboard: the org chart with real-time status for every Anima.

The web UI is organized around six screens (hash router #/…) plus the Workspace apps:

• Home — Org chart with live status, attention chips for items that need you, LLM usage panels (Claude / OpenAI / nanoGPT), a system status bar, recent activity, and external-task widgets. Per-Anima detail pages (overview, process, schedule, memory, assets) open from here.
• Chat — Real-time conversation with any Anima: streaming responses (SSE), image attachments, multi-thread history, side tabs for state / activity / heartbeat / cron, and memory browsers (episodes, knowledge, procedures). Meeting mode gathers up to five Animas in one room with a designated facilitator. Long-press a chat tab for the voice popup with an animated talking avatar.
• Board — Slack-style shared channels and DMs where Animas discuss and coordinate; bridged Discord channels appear here too.
• Tasks — The task board: queued, processing, deferred, suppressed, background work, and results. It also feeds priming so only relevant tasks surface in conversation.
• Activity — SVG swimlane timeline for the whole organization, a Now board with a live tool ticker, session replay, and logs.
• Settings — Four tabs (general, activity, API/auth, users). First run uses the wizard at /setup/.
• Workspace — Separate apps in their own tabs: the 3D office (/workspace/, with an org-chart view toggle and talking bust-up avatars) and the pixel office (/workspace/pixel/, a live 2D view where every status label is a running task).
• Theming & languages — 11 UI themes plus anime/realistic display modes. The setup wizard ships in 17 languages; the dashboard ships ja / en / ko.

Build an organization and delegate

Tell the leader "I need someone like this" — they infer role, personality, and hierarchy and create new members. You do not need to touch config files or the CLI; the organization can grow from conversation.

Once the team is ready, Animas keep working with their own schedules and memories:

• Heartbeat — Periodically reviews the situation and decides what to do next
• Cron jobs — Daily reports, weekly digests, monitoring — per-Anima schedules, both LLM tasks and plain commands
• Task delegation — Managers assign work with acceptance criteria, track progress, and receive reports
• Parallel task execution — Submit many tasks at once; independent tasks run in parallel while tasks sharing an exclusive key run in order
• GitHub event gateway — CI failures, review comments, and conflicts on watched repositories become agent tasks automatically
• Night consolidation — Daytime episodic memory is distilled into knowledge while "asleep"
• Team coordination — Shared channels and DMs route context to the people who need it

Memory system

Typical AI agents only remember what fits in the context window. AnimaWorks Animas keep file-based long-term memory and search it when needed. Instead of stuffing everything into every prompt, they retrieve only the memories related to the current conversation or action.

• Automatic recall (Priming) — When a message arrives, six channels retrieve in parallel: sender profile, recent activity, important knowledge, related knowledge, pending tasks, and episodes (plus graph context on the Neo4j backend). A deterministic gate decides whether each memory appears as body text, a pointer, evidence, or is suppressed.
• Intentional recall — When automatic recall is not enough, the Anima calls search_memory or read_memory_file itself. Search is hybrid: vector + BM25 + atomic facts + entity registry, with a confidence gate on what gets surfaced.
• Action rules before side effects — Before external sends and other side-effecting operations, matching action rules are checked and surfaced; the gate can be configured to hold execution until the required memories have been read.
• Consolidation — Nightly, the Anima itself runs a two-phase pass (episode extraction, then knowledge extraction through its own tool loop); the framework follows up with index rebuilds and downscaling. Weekly runs propose merges for duplicated or contradictory knowledge and rebuild search indexes.
• Forgetting — Memories unused for months are marked low-activation, then archived on a monthly pass, with important knowledge and mature procedures protected. Failure-driven reconsolidation revises procedures that stopped working.
• Pluggable backends — The stable default is the legacy backend (ChromaDB through an isolated vector worker, with automatic quarantine and rebuild on corruption). A Neo4j graph backend (entity extraction, community detection, graph-aware recall) is experimental and opt-in.

Chat: a manager reviews a code change while an engineer reports progress.

Multi-model support

Works with many LLMs. Each Anima can use a different model.

Mode resolution: execution_mode in status.json takes precedence, then the models.json table, then built-in model-name patterns (fnmatch). Tool_use-capable Ollama models (e.g. ollama/qwen3:14b, ollama/glm-4.7*) map to A; everything else under ollama/* maps to B. Each CLI engine has a fallback chain (rate-guard aware for Codex/Grok) down to LiteLLM. Heartbeat, Cron, and Inbox can run on a separate background_model from the main model (cost optimization). Extended thinking is supported where available.

Voice chat

Talk to an Anima in the browser — push-to-talk or hands-free — over WebSocket.

• STT: faster-whisper (streaming, LocalAgreement-2 partials)
• TTS: VOICEVOX / Style-BERT-VITS2 (AivisSpeech) / ElevenLabs / Irodori, selectable per Anima with voice, speed, and pitch settings
• Low-latency front lane — An optional small local model answers instantly and can escalate to the full agent (ask_anima) or read memory mid-conversation
• Proactive speech — With the front lane enabled, an idle Anima breaks silence on its own
• Animated avatar — The voice popup drives a pseudo-Live2D bust-up (five-frame blink/lip-sync from still images — no rigging, no Live2D SDK)

Auto-generated avatars

From personality settings: full-body, bust-up, and expression variants — auto-generated. Includes Vibe Transfer to inherit the supervisor's art style.

A seven-step pipeline generates full-body art, bust-ups with seven expressions, icons, chibi variants, and (for anime style) a rigged 3D model with idle/sitting/waving/talking animations. Backends: NovelAI (anime), fal.ai/Flux (stylized / photorealistic), Meshy (3D), plus Codex image generation and local Diffusers. Vibe Transfer (NovelAI) lets a new Anima inherit its supervisor's art style. The product runs without any image service configured; you simply skip avatars.

Why AnimaWorks?

No one can do anything alone. So I built an organization.

This project sits at the intersection of three careers.

As a founder — I know that no one can do anything alone. You need strong engineers, people who communicate well, steady operators, and people who occasionally spark a sharp idea. Genius alone does not run an organization. Diverse strengths together achieve what no individual can.

As a psychiatrist — Studying LLM internals, I saw structures surprisingly similar to the human brain. Recall, learning, forgetting, consolidation — implementing the brain's memory mechanisms as an LLM memory system might approximate how we process memory. If we can treat LLMs as pseudo-humans, we should be able to build organizations the same way we do with people.

As an engineer — I have written code for thirty years. I know the pleasure of wiring logic and the rush of automation. Packing those ideals into code lets me build the organization I want.

Excellent "single AI assistant" frameworks already exist. But projects that create human-like units in code and make them function as an organization are still rare. AnimaWorks is an AI organization I grow while using it in my own business every day.

Imperfect individuals collaborating through structure outperform any single omniscient actor.

Three principles hold it up:

• Encapsulation — Thoughts and memory stay invisible from outside. Others connect through text conversation only — like a real organization.
• RAG memory (library model) — Do not cram everything into the context window. Priming pulls related chunks via RAG, and agents recall on their own with search_memory and similar tools.
• Autonomy — No waiting for orders. They run on their own cadence and judge by their own values.

animaworks/
├── main.py              # CLI entry point
├── core/                # Digital Anima core engine
│   ├── anima.py, agent.py  # Core entities & orchestration
│   ├── lifecycle/       # Scheduler, consolidation jobs, inbox watch, etc.
│   ├── memory/          # Memory (priming, consolidation, forgetting, RAG, facts, retrieval)
│   ├── skills/          # Skill Hub, activation, router, curator, promotion
│   ├── taskboard/       # TaskBoard store, state, cleanup
│   ├── execution/       # Execution engines (S/C/D/G/X/A/B) + sanitization
│   ├── mcp/             # stdio MCP server for Mode S and external clients
│   ├── platform/        # Child processes, locks, Codex/Cursor/Gemini/Grok plumbing
│   ├── tooling/         # ToolHandler, schemas, permissions, external dispatch
│   ├── prompt/          # System prompt builder
│   ├── supervisor/      # ProcessSupervisor, IPC, TaskExec, health, streaming
│   ├── voice/           # Voice chat (STT + TTS + front lane)
│   ├── config/          # Configuration (Pydantic, models.json, global permissions)
│   ├── auth/            # UI authentication
│   ├── notification/    # Human notification channels
│   ├── migrations/      # Runtime data migrations
│   ├── i18n/            # Translation strings (`t()`)
│   ├── tools/           # External tool implementations (slack, discord, gmail, github, …)
│   ├── tasks_dispatch.py, review_multipass.py  # GitHub event → task wiring, multi-model review
│   └── …
├── cli/                 # CLI package (incl. demo)
├── server/              # FastAPI + static Web UI + Workspace apps
│   ├── app.py           # App factory, lifespan, auth/setup guards, static mounts
│   ├── github_gateway.py, slack_socket.py, discord_gateway.py, zoom_gateway.py
│   ├── routes/          # REST/WebSocket routes (chat, room, voice, webhooks, …)
│   └── static/          # Dashboard, setup wizard, workspace/ (3D), workspace/pixel/
├── swe/                 # Experimental CI auto-fix loop & SWE harness
├── demo/                # Demo presets and seeded history
└── templates/           # Initialization templates (ja / en / ko) incl. role playbooks

Documentation

Documentation hub — suggested reading order, architecture deep dives, and specification index.

License

Apache License 2.0. See LICENSE for details.