AnimaWorks — Organization-as-Code

An AI organization that ships software.

AnimaWorks is a framework that turns persistent AI agents into a "living organization." Give it a goal, and the agents break down the work, implement it in parallel worktrees, test and review each other's code, open pull requests, fix CI failures, resolve conflicts, and see deployments through to the end. They only ask a human for confirmation when a human is truly needed.

タスク → エージェントチーム → 並列worktree → 実装 → テスト → レビュー
     → Pull Request → CI修復 → デプロイ → 観測 → 修復

AnimaWorks doesn't hardcode this pipeline. What the framework handles is turning GitHub events into tasks, serializing execution per pull request, and orchestrating multi-model reviews. Everything else is run by the agents the same way human engineers do it — with git, tests, CI, and role-specific working conventions. That's why the same organization can also handle email replies, meeting minutes, and Slack posts. Because it's an organization, not a build script.

Production track record

Over the past six months, an AnimaWorks organization of eight Animas has handled the day-to-day development and operations of a production SaaS product:

These numbers are aggregated from primary execution records (per-agent activity logs, task queues, and work notes), not from commit author information — because under shared credentials, human and agent pushes get mixed together. Pull requests without verifiable evidence are excluded. The target repositories are private, so only aggregate figures are published.

AnimaWorks itself is developed the same way. The agents defined in this repository review this repository's pull requests, fix its CI, and ship its releases. The human's job is mainly direction-setting and exception handling.

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

The pixel-art office is not a simulation. It's a live view of the running organization — every status label is a task that's actually in motion.

English README | 简体中文 README | 한국어 README

🚀 Try it now

If you have the Claude Code CLI installed or are logged into Codex, no API key is needed.

First, clone and install with a one-liner:

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

Then start the demo team:

uv run animaworks demo

Open http://localhost:18501 and you're ready. A team of three (manager + engineer + assistant) starts running with three days of activity history. The first install takes a few minutes because it downloads Python 3.12+ and ML-related dependencies, but subsequent demo startups take seconds. See demo details here →

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 a cloned repository (it's not bundled with the pip package).

To create your own organization, run uv run animaworks start — the setup wizard below will guide 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        # codex/claude実行系のextraを追加
animaworks start            # サーバー起動 — 初回はセットアップウィザードが開きます

You can launch from any directory with animaworks. setup.sh symlinks the CLI to ~/.local/bin, so if that directory is on your PATH, you can omit uv run (if it's not, add export PATH="$HOME/.local/bin:$PATH" to your shell's rc). The console script points to this repository's .venv interpreter via an absolute path, so animaworks and uv run animaworks always run in the same environment. For manual installs, create the link 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's Codex without an API key, run codex login before the first startup.

Open http://localhost:18500/ and the setup wizard will guide you through five steps:

1. Language — choose the UI display language
2. User info — create the owner account
3. Provider authentication — enter the API key (OpenAI also supports Codex Login) and choose an avatar art style
4. First Anima — name your first agent
5. Confirmation — review and finish

You don't need to write .env by hand. The wizard saves it automatically to config.json.

The setup script handles installing uv, cloning the repository, installing dependencies, and creating the link for the animaworks command in ~/.local/bin. On macOS, Linux, and WSL it works 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 / API-based modes instead.

Always use --all-extras with uv sync. The bare uv sync that setup.sh runs will still work for the core, but Mode C (Codex) needs the codex extra. Also, if you later run a sync without extras, the codex / claude execution packages will be removed from the venv and all Animas in those modes will break at once.

Want to use other LLMs? Claude, GPT, Gemini, local models, and more are supported. Enter an API key in the setup wizard, or use Codex Login at OpenAI/Codex. You can change this later under Settings in the dashboard. See the API key reference for details.

curl -sSL https://raw.githubusercontent.com/xuiltul/animaworks/main/scripts/setup.sh -o setup.sh
cat setup.sh            # スクリプトの中身を確認
bash setup.sh           # 確認後に実行

# uvをインストール（インストール済みならスキップ）
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# クローンとインストール
git clone https://github.com/xuiltul/animaworks.git && cd animaworks
uv sync --all-extras    # Python 3.12+と全依存パッケージ（codex/claude extras含む）を自動ダウンロード

# 起動
uv run animaworks start

git clone https://github.com/xuiltul/animaworks.git && cd animaworks
# 資格情報を .env に置く（git管理外）:
#   ANTHROPIC_API_KEY=...            # APIキー認証
#   CLAUDE_CODE_OAUTH_TOKEN=...      # またはサブスクリプション認証: `claude setup-token` (要TTY)
#   GH_TOKEN=...                     # 任意: animaがclone/pushやPR作成を行うために必要
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       # 3.12+ であることを確認
pip install --upgrade pip && pip install -e .
animaworks start

How the loop works

A typical change flows 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 automatically converts CI failures, review comments, @bot commands, and merge conflicts into agent tasks (gh-ci-* / gh-review-* / gh-comment-*), with per-PR deduplication and retry limits.
2. The manager breaks it down — delegates to an engineer via delegate_task with acceptance criteria, a working location, and an exclusive key. Tasks touching the same PR are serialized by the exclusive key, so agents never collide on the same branch.
3. The engineer implements and tests in an isolated worktree — following role-specific working conventions (PdM / engineer / reviewer / tester) bundled as shared knowledge. This isolation isn't a fixed pipeline stage; it's an operating convention the agents execute with git — which is why it can handle tricky cases too.
4. Review is multi-model — for each PR, one review pass is issued per configured model, and an integration task consolidates all passes into a final verdict (approve / request changes). When a new push arrives, old review tasks are automatically cancelled and redone.
5. CI failures come back as work — a failed workflow run lands on the implementing agent as a repair task tied to the PR number and commit (no duplicates). The experimental standalone loop (python3 -m swe.ci_autofix) cycles through fix → lint/test gate → review → commit, and escalates to a human after three failures.
6. Deployment and runtime verification are also the agent's job — agents deploy branches to isolated environments, read logs, errors, and UI state, and find problems the tests missed. The production organization's activity records include hundreds of deployment and runtime observation actions.
7. Humans step in for exceptions — the organization escalates when it's stuck or when a decision exceeds its permissions (call_human). A separate supervisor process monitors agent health, restarts hung processes, and repairs its own memory index.

The human role shifts from "operating agents" to "owning the organization." Convey intent, review what matters, and judge exceptions.

Differences from Other Frameworks

AnimaWorks is not a task runner. It is an organization that thinks, remembers, forgets, and grows gradually. I develop it while using it as an AI team in real business operations.

What It Can Do

Dashboard

Dashboard: Organization chart with real-time status of all Anima.

The Web UI consists of 6 screens (hash router #/…) and the Workspace app:

• Home — Organization chart with live status, attention chips indicating items needing response, LLM usage panel (Claude / OpenAI / nanoGPT), system status bar, recent activity, external task widget. Detail pages for each Anima (overview / process / schedule / memory / assets) open from here
• Chat — Real-time conversation with any Anima: streaming responses (SSE), image attachments, multi-thread history, right-side tabs (state / activity / heartbeat / cron), memory browser (episodes / knowledge / procedures). Meeting mode gathers up to 5 Anima in the same room with a moderator. Long-press a chat tab for a voice popup (with a speaking animated avatar)
• Board — Slack-style shared channels and DMs. Anima discuss and collaborate here. Bridged Discord channels also appear here
• Tasks — Task board: queue, processing, pending, suppressed, background execution, results. Also linked to priming, surfacing only the tasks that need attention now in conversation
• Activity — Organization-wide SVG swimlane timeline, Now board with live tool ticker, session replay, logs
• Settings — 4 tabs (general / activity / API・authentication / users). First-time setup uses the /setup/ wizard
• Workspace — Standalone app opened in a separate tab: 3D office (/workspace/, with organization chart view switching and speaking bust-up) and pixel-art office (/workspace/pixel/, a live 2D view where all status labels are real tasks)
• Theme and language — 11 UI themes plus anime/realistic display modes. Setup wizard in 17 languages, dashboard itself in ja / en / ko

Build an Organization and Delegate

Tell the leader "I want someone like this," and it will create a new member by determining the role, personality, and reporting relationships. You can grow the organization through conversation without directly touching configuration files or the CLI.

Once the team is assembled, Anima works continuously using its own schedule and memory:

• Heartbeat — Periodically checks the situation and decides what to do next on its own
• Cron jobs — Daily reports, weekly summaries, monitoring. Configurable per Anima, supporting both LLM tasks and command execution
• Task delegation — Managers assign tasks with acceptance criteria, track progress, and receive reports
• Parallel task execution — Multiple tasks can be submitted at once. Independent tasks run in parallel; tasks sharing an exclusive key run sequentially
• GitHub event gateway — CI failures, review comments, and conflicts in monitored repositories automatically become tasks
• Nightly consolidation — Daytime episodic memories are sublimated into knowledge while sleeping
• Team collaboration — Shares status with the right people via shared channels and DMs

Memory System

Traditional AI agents only remember what fits in the context window. Anima in AnimaWorks has file-based long-term memory and retrieves it when needed. Instead of cramming everything in every time, it only pulls out memories relevant to the current conversation or action.

• Automatic recall (Priming) — When a message arrives, 6 channels run in parallel: sender profile, recent activity, important knowledge, related knowledge, pending tasks, episodes. Related knowledge search can also use legacy NetworkX graph diffusion depending on configuration. A deterministic gate decides whether retrieved memories are presented as body text, pointers, evidence, or suppression
• Intentional recall — When automatic recall is insufficient, Anima itself searches memory using search_memory or read_memory_file. Search is hybrid (vector + BM25 + atomic facts + entity registry) with a confidence gate
• Pre-action rule matching — Before operations with side effects like external sends, relevant action rules are matched and presented. It can also be configured to hold execution until the necessary memories are read
• Consolidation — Daily processing summarizes episodes, and Anima extracts knowledge through tool loops. The framework assists with index maintenance and candidate collection. Weekly processing presents potentially duplicate or contradictory knowledge as review candidates, and Anima judges the content
• Forgetting — Daily processing marks low-activity memories as candidates, and weekly processing presents memories for archival consideration to Anima. Candidates are not automatically deleted; protection rules apply to important memories and mature procedures. Reconsolidation also exists, where failures trigger procedure review
• Memory search — Combines vector search via the legacy vector worker with BM25. NetworkX graph diffusion can supplement search results depending on configuration

Chat: A manager reviews code fixes while an engineer reports progress.

Multi-Model Support

Works with any LLM. Different models can be assigned to different Anima.

Mode resolution follows status.json's execution_mode, the models.json table, then built-in model name patterns. Unknown models are assigned to A. Fallback follows per-engine configuration and error classification. Heartbeat, Cron, and Inbox can run on a separate background_model (for cost optimization). Extended thinking is also supported.

Voice Chat

You can talk to Anima by voice using only a browser (push-to-talk or hands-free, via WebSocket).

• STT: faster-whisper (streaming, sequential confirmation via LocalAgreement-2)
• TTS: VOICEVOX / Style-BERT-VITS2 (AivisSpeech) / ElevenLabs / Irodori. Voice, speed, and pitch can be configured per Anima
• Low-latency front lane — A small local model responds immediately, delegating to the main agent (ask_anima) or reading memory as needed
• Spontaneous speech — When the front lane is enabled, Anima starts speaking on its own if silence continues
• Animated avatar — The voice popup drives a pseudo-Live2D bust-up (blinking and lip sync from 5 static frames. No rigging or Live2D SDK used)

Automatic Avatar Generation

Automatically generates full-body, bust-up, and expression variants from personality settings. Includes Vibe Transfer that automatically inherits the supervisor's art style.

A 7-step pipeline generates full-body art, bust-ups with 7 expressions, icons, chibi characters, and (in anime style) idle/sitting/waving/talking rigged 3D models with animation. Backends include NovelAI (anime style), fal.ai/Flux（ stylized/photorealistic), Meshy (3D), plus Codex image generation and local Diffusers. Vibe Transfer (NovelAI) lets new Anima inherit the supervisor's art style. The core works even without configuring an image service.

Why AnimaWorks

One person alone can do nothing. That's why we built an organization.

This project was born at the intersection of three careers.

As a business owner — I know that "one person alone can do nothing." You need excellent engineers, and you need staff who are good at communication. There are workers who toil quietly, and there are people who occasionally come up with sharp ideas. Genius alone doesn't keep an organization running. When diverse strengths come together, things that could never be achieved alone are achieved.

As a psychiatrist — When I observed the internal structure of LLMs, I noticed a structure surprisingly similar to the human brain. Recall, learning, forgetting, consolidation — if I could implement the brain's memory-processing mechanisms directly as an LLM's memory system, I might be able to reproduce the human brain. And if I could treat an LLM as a "pseudo-human," I should be able to build an organization just like with humans.

As an engineer — I've been writing code for 30 years. I know the joy of building logic and the thrill of automation. If I can pack all my ideals into code, I can build my ideal organization.

There are already many excellent frameworks for a "standalone AI secretary." But I felt there were still few projects that create human-like units in code and make them function as an organization. AnimaWorks is an AI organization that I've built into my own business and nurture through daily use.

The collaboration of imperfect individuals creates a more robust organization than a single omnipotent one.

Three principles support this:

• Encapsulation — Internal thoughts and memories are invisible from the outside. Connection with others happens only through text conversation. Just like a real organization.
• RAG memory (archive-based) — We don't cram everything into the window. Priming picks up relevant chunks via RAG, and agents recall on their own using search_memory etc.
• Autonomy — They don't wait for instructions. They operate on their own clock and judge by their own values.

animaworks/
├── main.py              # CLIエントリポイント
├── core/                # Digital Animaコアエンジン
│   ├── anima.py, agent.py  # コアエンティティ・オーケストレーション
│   ├── lifecycle/       # スケジューラ・統合ジョブ・inboxウォッチ等
│   ├── memory/          # 記憶（priming, consolidation, forgetting, RAG, facts, retrieval）
│   ├── skills/          # Skill Hub・activation・router・curator・promotion
│   ├── taskboard/       # TaskBoard ストア・状態・クリーンアップ
│   ├── execution/       # 実行エンジン（S/C/D/G/X/A/B）＋サニタイズ
│   ├── mcp/             # Mode S・外部クライアント向け stdio MCP サーバー
│   ├── platform/        # 子プロセス・ロック・Codex/Cursor/Gemini/Grok 周辺
│   ├── tooling/         # ToolHandler・スキーマ・権限・外部ディスパッチ
│   ├── prompt/          # システムプロンプト構築
│   ├── supervisor/      # ProcessSupervisor・IPC・TaskExec・死活監視・ストリーミング
│   ├── voice/           # 音声チャット（STT + TTS + フロントレーン）
│   ├── config/          # 設定（Pydantic・models.json・グローバル権限）
│   ├── auth/            # UI 認証まわり
│   ├── notification/    # 人間通知チャネル
│   ├── migrations/      # ランタイムデータマイグレーション
│   ├── i18n/            # 翻訳文字列（`t()`）
│   ├── tools/           # 外部ツール実装（slack, discord, gmail, github, …）
│   ├── tasks_dispatch.py, review_multipass.py  # GitHubイベント→タスク配線、マルチモデルレビュー
│   └── …
├── cli/                 # CLIパッケージ（demo含む）
├── server/              # FastAPI + 静的Web UI + Workspaceアプリ
│   ├── app.py           # アプリ生成・lifespan・認証/セットアップガード・静的マウント
│   ├── github_gateway.py, slack_socket.py, discord_gateway.py, zoom_gateway.py
│   ├── routes/          # REST/WebSocketルート（chat, room, voice, webhooks, …）
│   └── static/          # ダッシュボード、setupウィザード、workspace/（3D）、workspace/pixel/
├── swe/                 # 実験的CI自動修復ループ・SWEハーネス
├── demo/                # デモプリセットと同梱履歴
└── templates/           # 初期化テンプレート（ja / en / ko）ロール別作業規約を含む

Documentation

Documentation Master Index — Reading order guide, architecture deep dive, and list of design specifications.

License

Apache License 2.0. See LICENSE for details.