AnimaWorks
Run a 24/7 autonomous AI organization you talk to like a messenger app: persistent agents with long-term memory, identity and schedules that code, review, repair CI and report back.
- Source repo
- xuiltul/animaworks
- Stars
- ★ 269
- Last updated
- 1d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 48/100 · Major gaps
At a glance
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API · Claude API
- You'll need
- Typical use
- Solo founders or small teams: let a 3–8 Anima organization maintain a production SaaS around the clock, automatically consuming CI failures and PR review comments (README logs 302 autonomously authored PRs over 6 months).
- Main limitation
- No native Windows support — Unix-only APIs (fcntl, pty, os.killpg) require WSL.
- Source review
- 48/100 · Major gaps
What does this agent do, and when should you use it?
AnimaWorks is an open-source Organization-as-Code framework that assembles persistent AI agents (Digital Animas) into a virtual organization running around the clock. Each Anima has a filesystem-first, brain-inspired long-term memory: 6-channel automatic priming, hybrid retrieval over ChromaDB vectors + BM25 + atomic facts (with optional Neo4j graph memory), nightly sleep-cycle consolidation, and active forgetting. The runtime pairs a FastAPI control plane with one OS process per Anima and isolated IPC v2 task-runner subprocesses, backed by a SQLite TaskStore atomic task board, Heartbeat/Cron autonomous patrols, and a GitHub webhook gateway. The surface is a LINE-style web chat (WebSocket/SSE) with one-tap approval cards, a D3 memory bubble graph, voice calls, and 3D/pixel-office visualization. Seven execution engines are supported — Claude Agent SDK, Codex, Cursor, Gemini CLI, Grok, and LiteLLM — covering subscription logins, cloud APIs, or local Ollama. Security comes from an Enclave that isolates secrets and PII in a separate OS user domain with egress PII scrubbing.
AnimaWorks starts a FastAPI server (default port 18500) that spawns a root OS process per Anima, with heavy work delegated to TaskRunner subprocesses over IPC v2 (STDIN/STDOUT JSON-RPC + binary framing). When a message, GitHub webhook, or Heartbeat/Cron trigger arrives, a Manager Anima decomposes the goal and dispatches tasks through the SQLite TaskStore (shared/taskboard.sqlite3), using mutex_key to prevent concurrent edits, delegated_tasks contracts with automatic supervisor review, and automatic retry for stalled workers. Engineer Animas implement in isolated git worktree sandboxes, run tests, perform multi-model PR reviews on each other's work, self-repair CI failures, and verify deployments. Before every turn, 6-channel priming recalls sender profile, recent activity, related knowledge, pending tasks, episodes, and atomic facts; the hybrid retrieval pipeline fuses vector search (ChromaDB), BM25, FactRecord records, and RRF. A nightly maintenance process consolidates daily logs into structured knowledge and prunes low-value memories under protection rules. When human sign-off is needed, call_human surfaces an approval card in chat; for critical incidents, Twilio integration can place a real phone call. The CLI exposes animaworks start / demo / init / chat / task / memory / enclave / company command families.
- Solo founders or small teams: let a 3–8 Anima organization maintain a production SaaS around the clock, automatically consuming CI failures and PR review comments (README logs 302 autonomously authored PRs over 6 months).
- Tech leads: spin up a division-of-labor coding org from dev-lead / engineer / researcher / ops role templates with parallel development in isolated git worktrees.
- Unattended ops: run Heartbeat/Cron patrols on a cheap background_model for log monitoring and health checks, with Twilio voice calls for critical incidents.
- Support and admin workflows: handle customer inquiries and Zoom meeting minutes, synced bidirectionally over Slack/Discord/Chatwork.
- Privacy-conscious users: run fully local via LiteLLM mode A with Ollama/vLLM, no cloud API dependency.
- Multi-business operators: use the animaworks company command suite to define multiple companies or business units within one runtime, with split and export.
How do you install or deploy this agent?
One-line install on macOS/Linux:
curl -sSL https://raw.githubusercontent.com/xuiltul/animaworks/main/scripts/setup.sh | bash
cd animaworks
uv run animaworks startWindows (auto-installs WSL):
irm https://raw.githubusercontent.com/xuiltul/animaworks/main/scripts/setup.ps1 | iex
cd animaworks
uv run animaworks startDocker deployment (image bundles Node.js, GitHub CLI, Playwright, Claude Code/Codex/Gemini CLIs):
git clone https://github.com/xuiltul/animaworks.git && cd animaworks
docker compose up -d --buildManual pip install (Python 3.12/3.13 recommended):
git clone https://github.com/xuiltul/animaworks.git && cd animaworks
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip && pip install -e ".[all-tools]"
animaworks startCredentials: Claude Code subscription login, codex login, ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY, or local Ollama (no API key needed).
How do you use this agent?
Try the pre-built 3-Anima demo in 60 seconds (no API key required if Claude Code CLI is installed or Codex is logged in):
curl -sSL https://raw.githubusercontent.com/xuiltul/animaworks/main/scripts/setup.sh | bash
cd animaworks
uv run animaworks demoOpen http://localhost:18501 to chat with a team that is already at work. For a real organization, open http://localhost:18500 and follow the setup wizard: pick language & theme (en/ja/zh/ko) → configure the LLM connection → create your first Anima from templates like dev-lead, full-stack, or assistant. Everything can also run headlessly:
uv run animaworks init
uv run animaworks start
uv run animaworks chat alice "Check our sprint goals for today and delegate tasks to the team"Creating members and messaging from a container:
docker exec -it <container> animaworks anima create --name alice --template dev-lead
docker exec -it <container> animaworks send <your-name> alice "Hello!"Day to day, chat in the web UI; approval requests appear as Approve/Reject/Comment cards, and background activity is auto-collapsed (toggle via the Background header button).
What are this agent's strengths and limitations?
- Backed by real production numbers: an 8-Anima org continuously developed and operated a SaaS for over six months, with 99.7% of 31,215 tasks self-initiated.
- The brain-inspired memory architecture is a clear differentiator: 6-channel priming, vector+BM25+atomic-fact hybrid retrieval, nightly consolidation and active forgetting — not a stateless session wrapper.
- Fine-grained fault isolation: per-Anima root processes plus TaskRunner subprocesses over IPC v2, so a hung tool only reaps its own subprocess.
- Seven execution engines with front/background model routing — cheap models for patrols, frontier models for coding — and a fully local Ollama path.
- Security depth beyond peers: Enclave (separate OS user + Unix socket allowlist), egress PII scrubbing, 5-stage command inspection, and trust-boundary labeling.
- No native Windows support — Unix-only APIs (fcntl, pty, os.killpg) require WSL.
- Heavy deployment surface: process tree, ChromaDB, SQLite TaskStore, optional Neo4j/vector services — real operational and comprehension cost.
- Continuously running Heartbeat/Cron patrols and concurrent Animas consume LLM quota/cost steadily, and advanced features depend on Claude/Codex subscriptions or API keys.
- The built-in comparison table (vs CrewAI/LangGraph, etc.) is the project's own claim, and the production stats come from the author's own product — no third-party verification.
- Image/voice/3D generation and Twilio phone alerts each require additional keys (NovelAI, fal.ai, ElevenLabs, Twilio, etc.).
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| AnimaWorks This agent | 48 · Major gaps | — | ★ 269 | 1d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| Dive into LangGraph | 69 · Some gaps | Library / SDKFree + model costs | ★ 467 | 1mo ago | Jupyter Notebook | Claude Code |
| Agentica | 63 · Some gaps | CLIFree + model costs | ★ 360 | 1d ago | Python | OpenAI API · Claude API |
| Agent Craft | 49 · Major gaps | CLIFree + model costs | ★ 533 | 9d ago | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
The security docs (docs/en/security.md and translations) describe trust boundaries, a centralized command policy, file access policy, Enclave with egress PII scrubbing, and internal API token validation, which is a reasonably solid least-privilege design (least_privilege=2). User confirmation is only shown via call_human approval cards and some approval gates; there is no evidence of mandatory confirmation for high-impact external effects such as messaging, phone calls, or git push (user_confirmation=1). Data-flow transparency is supported by provenance trust tags and wrapping (data_flow_transparency=2). Sensitive data handling has egress PII scrubbing and a Vault, but the enclave masker depends on optional extras (sensitive_data_handling=2). Dependency security pins mcp<2 and a litellm upper bound and notes a known chromadb issue, but the dependency surface is very broad (chromadb, sentence-transformers, litellm, multiple CLI SDKs) with no lockfile or vulnerability-scan evidence (dependency_security=1). External effects: the docs explicitly admit there is no per-destination count, time, or daily send budget, only same-run dedupe (external_effects=1). Rollback: GlobalPermissionsCache reverts runtime changes and processes restart, but there is no general rollback story for autonomous code/deploy actions (rollback=1). Source attribution: Apache-2.0 with copyright notice, but publisher identity is unverified and there is no NOTICE or third-party attribution list (source_attribution=1).
Self-consistency: README claims production metrics (302 PRs, 99.7% autonomous) but no logs or data in the repo substantiate them, and the security doc's verified commit (581e20f1) differs from the reviewed revision (e7f0d47), indicating doc drift (self_consistency=1). Dependency availability: many optional extras and external CLIs (Claude/Codex/Cursor/Gemini/Grok), no native Windows support requiring WSL, making install paths fragile (dependency_availability=1). Failure messages: docs describe deny-on-config-failure, rate_guard retries, and process isolation/reaping, showing clear error-handling intent (failure_messages=2).
Audience and scenarios cover developers, operators, and multilingual users with four presets and multiple engines (audience_and_scenarios=2). Capability boundaries are documented with residual risks, no guarantee against arbitrary host compromise, and heuristic Bash checks (capability_boundaries=2). Trigger precision: Heartbeat/Cron/Webhook are described but without concrete thresholds, dedupe, or false-trigger evidence (trigger_precision=1). Environment fit supports macOS/Linux/WSL/Docker but explicitly not native Windows (environment_fit=2).
Information architecture is clear with multilingual README, docs tree, and security/architecture/reference docs (information_architecture=2). Install notes are thorough (setup.sh, PowerShell, Docker, pip) (install_notes=2). Naming stability shows legacy renames (core.supervisor.runner to core.runtime.runner) and 'until 2026-11' comments, indicating names are still moving (naming_stability=1). Examples and FAQ include a 60-second demo, Demo Guide, and comparison table (examples_and_faq=2). Known limitations appear in residual-risk sections and pyproject comments (known_limitations=2). License is full Apache-2.0 text consistent with pyproject (license=3). Versioning/changelog only shows version 0.17.0 and a CHANGELOG link with no content (versioning_changelog=1). Maintenance responsibility: publisher unverified, no explicit maintainer/governance statement (maintenance_responsibility=1).
Output usability is good with chat UI, approval cards, file attachments, and CLI (output_usability=2). Marginal value: 'organization-as-code plus brain-inspired memory' is differentiated, but many multi-agent frameworks exist and the core value claim rests on unverified production metrics (marginal_value=1). Cost-benefit: multi-engine, multi-process, ChromaDB, and voice/3D asset generation imply high resource and configuration cost with no cost comparison evidence (cost_benefit=1).
Claim traceability: README metrics are labeled 'aggregated from primary execution logs' but no logs or data files are in the repo to check (claim_traceability=1). Cross-source corroboration: security docs, pyproject comments, and CI workflows corroborate some engineering practices, but production metrics have no second source (cross_source_corroboration=1). Fact/inference separation: README mixes marketing assertions with engineering facts without clear separation (fact_inference_separation=1).
- README production metrics (302 PRs, 99.7% autonomous tasks) cannot be checked in the repo and should be treated as unverified marketing claims.
- The security doc's verified commit differs from the reviewed revision, so docs may have drifted; verify actual code behavior yourself.
- External sending lacks rate or budget caps beyond same-run dedupe, creating mis-send and abuse risk.
- Broad dependency surface with multiple external CLIs and optional extras raises install and supply-chain risk; no lockfile or vulnerability scan is shown.
- Publisher identity is unverified; maintenance responsibility and update path are unclear.
- No native Windows support (requires WSL); multi-process and ChromaDB imply high resource and configuration cost.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Highlights - Standard workspace file names. Anima workspaces now follow the de-facto convention used by OpenClaw and Hermes Agent: SOUL.md (personality, voice, values), IDENTITY.md (name, profile, appearance), AGENTS.md (role and operating instructions), HEARTBEAT.md, and BOOTSTRAP.md. - Export to other agent runtimes. animaworks anima export NAME --format openclaw|hermes --out DIR writes an Anima in OpenClaw or Hermes layout (credentials redacted). The OpenClaw / Hermes importers can now apply SOUL.md, IDENTITY.md, AGENTS.md, and HEARTBEAT.md directly. …View on GitHub ↗ -
Release notes excerpt
AnimaWorks v0.16.0 This release redesigns the web chat as a messenger-style talk screen with file attachments and a memory browser, adds a Twilio phone channel, an isolated enclave mode for sensitive data, and execution mode Y for the Antigravity CLI. It also makes tasks, inbox handling and cron quieter, and restructures the runtime so each process owns its own state. Highlights …View on GitHub ↗ -
Release notes excerpt
AnimaWorks v0.15.0 This release adds background memory review and peer notes, a task board that Animas triage themselves, a skill ledger with rollback, and per-caller internal API tokens. It also shortens prompts and reorganizes the code into single-purpose packages. Highlights - Background memory review: after a context compaction, at the end of a task and every 10 chat turns, the background model makes up to 3 knowledge or peer-note updates without blocking the conversation. Peer notes (animas/{name}/peers/) are recalled whenever that person or Anima writes in. …View on GitHub ↗