Metadata-Version: 2.4
Name: animaworks
Version: 0.8.0
Summary: AnimaWorks - Digital Anima Framework with library-type memory
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/xuiltul/animaworks
Project-URL: Documentation, https://github.com/xuiltul/animaworks#readme
Project-URL: Repository, https://github.com/xuiltul/animaworks
Project-URL: Issues, https://github.com/xuiltul/animaworks/issues
Project-URL: Changelog, https://github.com/xuiltul/animaworks/blob/main/CHANGELOG.md
Keywords: ai,agent,autonomous,organization,memory,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Framework :: FastAPI
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: claude-agent-sdk>=0.1.40; platform_system != "Windows"
Requires-Dist: anthropic>=0.42.0
Requires-Dist: openai-codex-sdk<0.2,>=0.1.11
Requires-Dist: litellm>=1.82.6
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.34.0
Requires-Dist: apscheduler>=3.10.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: chromadb>=1.0.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: diffusers>=0.35.1
Requires-Dist: Pillow>=10.0.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: orjson>=3.9.0
Requires-Dist: json-repair>=0.30.0
Requires-Dist: pwdlib[argon2]>=0.3.0
Requires-Dist: markdownify>=0.14.1
Requires-Dist: PyNaCl>=1.5.0
Requires-Dist: tzlocal>=5.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: rank-bm25>=0.2
Requires-Dist: datasketch>=1.1.3
Provides-Extra: claude
Requires-Dist: claude-agent-sdk>=0.1.40; platform_system != "Windows" and extra == "claude"
Provides-Extra: communication
Requires-Dist: requests>=2.31; extra == "communication"
Requires-Dist: slack-sdk>=3.27; extra == "communication"
Requires-Dist: slack-bolt>=1.21; extra == "communication"
Requires-Dist: aiohttp>=3.9; extra == "communication"
Provides-Extra: discord
Requires-Dist: discord.py>=2.3; extra == "discord"
Provides-Extra: notification
Requires-Dist: line-bot-sdk>=3.0; extra == "notification"
Provides-Extra: gmail
Requires-Dist: google-api-python-client>=2.0; extra == "gmail"
Requires-Dist: google-auth-oauthlib>=1.0; extra == "gmail"
Requires-Dist: google-auth-httplib2>=0.2; extra == "gmail"
Provides-Extra: transcribe
Requires-Dist: faster-whisper>=1.0; extra == "transcribe"
Provides-Extra: aws
Requires-Dist: boto3>=1.34; extra == "aws"
Provides-Extra: rag
Requires-Dist: networkx>=3.0; extra == "rag"
Requires-Dist: watchdog>=3.0.0; extra == "rag"
Provides-Extra: neo4j
Requires-Dist: neo4j>=5.20.0; extra == "neo4j"
Requires-Dist: datasketch>=1.6.5; extra == "neo4j"
Provides-Extra: codex
Requires-Dist: openai-codex-sdk<0.2,>=0.1.11; extra == "codex"
Provides-Extra: all-tools
Requires-Dist: animaworks[aws,claude,codex,communication,gmail,notification,rag,transcribe]; extra == "all-tools"
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == "redis"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.24; extra == "test"
Requires-Dist: pytest-timeout>=2.2; extra == "test"
Requires-Dist: psutil>=5.9.0; extra == "test"
Requires-Dist: pytest-cov>=5.0; extra == "test"
Requires-Dist: ruff>=0.9; extra == "test"
Provides-Extra: evaluation
Requires-Dist: scipy>=1.11.0; extra == "evaluation"
Requires-Dist: statsmodels>=0.14.0; extra == "evaluation"
Requires-Dist: scikit-learn>=1.3.0; extra == "evaluation"
Requires-Dist: pandas>=2.1.0; extra == "evaluation"
Requires-Dist: matplotlib>=3.8.0; extra == "evaluation"
Requires-Dist: seaborn>=0.13.0; extra == "evaluation"
Dynamic: license-file

# AnimaWorks — Organization-as-Code

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

A framework that treats AI agents not as one-off “tools,” but as team members who keep working with persistent memory. Each Anima has a name, role, personality, memory, and schedule; they coordinate by message, make decisions, and ask humans when confirmation is needed.

Humans can talk to a leader or responsible member, while task breakdown, delegation, progress checks, memory updates, and daily or weekly reflection stay inside the same organization.

<p align="center">
  <img src="docs/images/workspace-dashboard.gif" alt="AnimaWorks Workspace — real-time org tree with live activity feeds" width="720">
  <br><em>Workspace dashboard: each Anima’s role, status, and recent actions are visible in real time.</em>
</p>

<p align="center">
  <img src="docs/images/workspace-demo.gif" alt="AnimaWorks 3D Workspace — agents collaborating autonomously" width="720">
  <br><em>3D office: Animas sit at desks, walk around, and exchange messages when needed.</em>
</p>

**[日本語版 README](README_ja.md)** | **[简体中文 README](README_zh.md)** | **[한국어 README](README_ko.md)**

---

## 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: RAG (Chroma + graph), consolidation, active forgetting, automatic recall, and memory checks before action | Cognitive Memory (manual forget) | Checkpoints + cross-thread store | SuperMemory knowledge graph | Session-scoped only |
| **Autonomy** | Heartbeat (observe → plan → reflect) + Cron + TaskExec — runs 24/7 | Human-triggered | Human-triggered | Cron + heartbeat | Human-triggered |
| **Org structure** | Supervisor → subordinate hierarchy, delegation, audit, dashboard | Flat roles in a crew | — | Single agent | Handoffs only |
| **Process model** | One isolated OS process per agent, IPC, auto-restart | Shared process | Shared process | Single process | Shared process |
| **Multi-model** | Six engines: Claude SDK / Codex / Cursor Agent / Gemini CLI / LiteLLM / Assisted (Anthropic SDK falls back inside Mode A when Agent SDK is not installed) | LiteLLM | LangChain models | OpenAI-compatible | OpenAI-centric |

> 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.

---

## :rocket: Try It Now — Docker Demo

Up and running in about 60 seconds. You only need an API key and Docker.

```bash
git clone https://github.com/xuiltul/animaworks.git
cd animaworks/demo
cp .env.example .env          # paste your ANTHROPIC_API_KEY
docker compose up              # open http://localhost:18500
```

A three-person team (manager + engineer + coordinator) starts immediately, with three days of activity history. [Demo details →](demo/README.md)

> Switch language / style: `PRESET=ja-anime docker compose up` — [full preset list](demo/README.md#presets)

---

## Quick Start

macOS / Linux / WSL:

```bash
curl -sSL https://raw.githubusercontent.com/xuiltul/animaworks/main/scripts/setup.sh | bash
cd animaworks
uv run animaworks start     # start server — setup wizard opens on first run
```

Windows (PowerShell):

```powershell
git clone https://github.com/xuiltul/animaworks.git
cd animaworks
uv sync
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:

1. **Language** — choose the UI display language
2. **User info** — create the owner account
3. **Provider auth** — enter API keys or choose Codex Login for OpenAI
4. **First Anima** — name your first agent

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

The setup script installs [uv](https://docs.astral.sh/uv/), clones the repository, and downloads Python 3.12+ with all dependencies. **macOS, Linux, and WSL** work without a pre-installed Python. On **Windows**, use the PowerShell steps above.

> **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](#api-key-reference).

<details>
<summary><strong>Alternative: inspect the script before running</strong></summary>

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

```bash
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
```

</details>

<details>
<summary><strong>Alternative: manual install with uv (step by step)</strong></summary>

```bash
# 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                 # downloads Python 3.12+ and all dependencies

# Start
uv run animaworks start
```

</details>

<details>
<summary><strong>Alternative: manual install with pip</strong></summary>

> **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](https://brew.sh/) (`brew install python@3.13`) or use the uv method above (uv manages Python for you).

Requires Python 3.12+ on your system.

```bash
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
```

</details>

---

## What You Can Do

### Dashboard

<p align="center">
  <img src="docs/images/dashboard.png" alt="AnimaWorks Dashboard — org chart with 19 Animas" width="720">
  <br><em>Dashboard: four hierarchy levels, 19 Animas running, with real-time status.</em>
</p>

Use the left sidebar to move between main screens (hash router `#/…`).

- **Chat** — Real-time conversation with any Anima. Streaming responses (SSE), image attachments, multi-thread history, full archive. **Meeting mode** gathers multiple Animas in one room with a designated facilitator (up to five participants, dedicated API)
- **Voice chat** — Voice in the browser only (push-to-talk or hands-free). WebSocket-based. VOICEVOX / SBV2 / ElevenLabs
- **Board** — Slack-style shared channels where Animas discuss and coordinate
- **TaskBoard** — A work board for tasks, processing, deferred, suppressed, background work, and results. It also feeds priming so only relevant tasks surface in conversation
- **Dashboard (home)** — Organization overview and status
- **Activity** — Real-time feed for the whole organization
- **Setup** — First run uses the wizard at `http://HOST/setup/`. After setup, `/setup` in the browser redirects to the top level, but you can open the same items (language, auth, etc.) from `#/setup` inside the dashboard
- **Users** — Owner and user profile management
- **Anima management** — Enable/disable, model, and metadata per Anima
- **Process monitoring** — Child process health
- **Server** — Server-side state and settings
- **Memory** — Browse each Anima’s episodes, knowledge, procedures, and more
- **Logs** — Log viewer
- **Assets** — Character images, 3D, and other assets
- **Activity report** — Cross-org auditing and daily LLM-generated narratives from activity data (cached)
- **Prompt settings** — Tune prompts around tool execution
- **AI brainstorm** — LLM sessions with multiple viewpoint presets (realist, challenger, etc.)
- **Team builder / team edit** — Build and adjust multi-Anima role layouts from industry- and goal-oriented presets
- **Settings** — Server, authentication, locale, and more
- **Workspace** — 3D office in a separate tab at `/workspace/` (chat, Board, org tree, etc.); static app split from the main dashboard
- **Multilingual** — **First-run setup wizard** UI copy in 17 languages. **Main dashboard** ships `ja` / `en` / `ko` JSON translations (missing keys fall back to Japanese). Anima-facing templates deploy with Japanese, English, and Korean

### 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
- **Task delegation** — Managers assign work to subordinates, track progress, and receive reports
- **Parallel task execution** — Submit many tasks at once; dependencies are resolved and independent tasks run in parallel
- **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, the system retrieves sender profile, recent activity, important knowledge, related knowledge, tasks, episodes, graph context, and more in parallel. A deterministic gate decides whether each memory appears as body text, a pointer, evidence, or is suppressed
- **Intentional recall** — If automatic recall is not enough, the Anima can call `search_memory` or `read_memory_file` itself. Pointer-style memories are read only when the details are needed
- **Memory checks before action** — Before external sends, memory writes, and other side-effecting operations, related action rules and past rules are checked. If required memories have not been read, execution pauses first
- **Consolidation** — Every night, daytime episodes and resolved events update knowledge and procedures. Weekly consolidation removes duplication and contradictions, and RAG indexes are rebuilt
- **Forgetting** — Little-used memories move through low-activation marking, consolidation, and archiving. Important knowledge and mature procedures are protected while search noise stays under control
- **RAG repair** — If ChromaDB or vector search inconsistency is detected, indexes can be quarantined and rebuilt through the vector worker. The stable default backend is `legacy`; the Neo4j backend is experimental and opt-in

<p align="center">
  <img src="docs/images/chat-memory.png" alt="AnimaWorks Chat — multi-thread conversations with multiple Animas" width="720">
  <br><em>Chat: a manager reviews a code change while an engineer reports progress.</em>
</p>

### Multi-model support

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

| Mode | Engine | Targets | Tools |
|------|--------|---------|--------|
| S (SDK) | Claude Agent SDK | Claude models (recommended) | Claude Code built-ins (Read/Write/Edit/Bash/Grep/Glob, etc.) + **stdio MCP** (`mcp__aw__*`) for AnimaWorks internal tools; external integrations via `skill` → `animaworks-tool` |
| C (Codex) | Codex CLI (SDK wrapper) | OpenAI Codex CLI models | Codex sandbox + **AnimaWorks MCP** (`core/mcp/server.py`) for internal tools |
| D (Cursor) | Cursor Agent CLI | `cursor/*` models | MCP-integrated agent loop |
| G (Gemini CLI) | Gemini CLI | `gemini/*` models | stream-json parsing, tool loop |
| A (Autonomous) | LiteLLM + tool_use | GPT, Gemini, Mistral, Bedrock, Vertex, xAI, etc. | CC-style (Read/Write/Edit/Bash/Grep/Glob, **WebSearch/WebFetch**) + memory, messaging, tasks (**submit_tasks**, etc.), **todo_write**, **skill**, and more (varies with notifications and supervisor tools) |
| B (Basic) | LiteLLM one-shot | Unstable tool_use locals (e.g. small Ollama) | Pseudo tool calls in the prompt; the framework handles memory I/O on the model’s behalf |

Mode resolution: `execution_mode` in `status.json` takes precedence; otherwise the model name pattern (`fnmatch`) is used automatically. For Ollama, **tool_use-capable models** (e.g. `ollama/qwen3:14b`, `ollama/glm-4.7*`) map to A; others tend to fall back to B. Heartbeat, Cron, and Inbox can run on a separate **background_model** from the main model (cost optimization). Extended thinking is supported where available.

### Auto-generated avatars

<p align="center">
  <img src="docs/images/asset-management.png" alt="AnimaWorks Asset Management — realistic avatars and expression variants" width="720">
  <br><em>From personality settings: full-body, bust-up, and expression variants — auto-generated. Includes Vibe Transfer to inherit the supervisor’s art style.</em>
</p>

Supports NovelAI (anime style), fal.ai/Flux (stylized / photorealistic), and Meshy (3D). The product runs without configuring an image service; you simply skip avatars. When avatars exist, it becomes easier to recognize Animas as team members.

---

## Why AnimaWorks?

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.

---

<details>
<summary><strong>API Key Reference</strong></summary>

#### LLM providers

| Key | Service | Mode | Where to get it |
|-----|---------|------|-----------------|
| `ANTHROPIC_API_KEY` | Anthropic API | S / A | [console.anthropic.com](https://console.anthropic.com/) |
| `OPENAI_API_KEY` | OpenAI | A / C (optional with Codex Login) | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
| `GOOGLE_API_KEY` | Google AI (Gemini) | A | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) |

**OpenAI Codex (Mode C)** supports both `OPENAI_API_KEY` and local **Codex Login** (`codex login`). Choose in the setup wizard or Settings.

**Azure OpenAI**, **Vertex AI (Gemini)**, **AWS Bedrock**, and **vLLM** are configured in the `credentials` section of `config.json`. See the [technical specification](docs/spec.md).

**Ollama** and similar local models need no API key. Set `OLLAMA_SERVERS` (default: `http://localhost:11434`).

#### Image generation (optional)

| Key | Service | Output | Where to get it |
|-----|---------|--------|-----------------|
| `NOVELAI_API_TOKEN` | NovelAI | Anime-style character art | [novelai.net](https://novelai.net/) |
| `FAL_KEY` | fal.ai (Flux) | Stylized / photorealistic | [fal.ai/dashboard/keys](https://fal.ai/dashboard/keys) |
| `MESHY_API_KEY` | Meshy | 3D character models | [meshy.ai](https://www.meshy.ai/) |

#### Voice chat (optional)

| Requirement | Service | Notes |
|-------------|---------|-------|
| `pip install faster-whisper` | STT (Whisper) | Model auto-downloads on first use; GPU recommended |
| VOICEVOX Engine running | TTS (VOICEVOX) | Default: `http://localhost:50021` |
| AivisSpeech / SBV2 running | TTS (Style-BERT-VITS2) | Default: `http://localhost:5000` |
| `ELEVENLABS_API_KEY` | TTS (ElevenLabs) | Cloud API |

#### External integrations (optional)

| Key | Service | Where to get it |
|-----|---------|-----------------|
| `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` | Slack | [Setup guide](docs/slack-socket-mode-setup.md) |
| `CHATWORK_API_TOKEN` | Chatwork | [chatwork.com](https://www.chatwork.com/) |
| `DISCORD_BOT_TOKEN` (or per-Anima `DISCORD_BOT_TOKEN__<name>`) | Discord | [Discord Developer Portal](https://discord.com/developers/applications) |
| `NOTION_API_TOKEN` (or `NOTION_API_TOKEN__<name>`) | Notion | [Notion integrations](https://www.notion.so/my-integrations) |

Google Calendar, Google Tasks, Gmail, and similar are configured under `credentials` in `config.json` (OAuth or service account). See the [technical specification](docs/spec.md).

</details>

<details>
<summary><strong>Hierarchy & roles</strong></summary>

Hierarchy is defined by a single `supervisor` field. Unset means top-level.

Role templates apply role-specific prompts, permissions, and default models:

| Role | Default model | Use case |
|------|----------------|----------|
| `engineer` | Claude Opus 4.6 | Complex reasoning, code generation |
| `manager` | Claude Opus 4.6 | Coordination, decision-making |
| `writer` | Claude Sonnet 4.6 | Content creation |
| `researcher` | Claude Sonnet 4.6 | Information gathering |
| `ops` | vLLM (GLM-4.7-flash) | Log monitoring, routine work |
| `general` | Claude Sonnet 4.6 | General-purpose |

Managers automatically receive **supervisor tools**: task delegation, progress tracking, subordinate restart/disable, org dashboard, subordinate state reads — what real managers do.

Each Anima is started by ProcessSupervisor as an isolated process and talks over local IPC (Unix domain sockets on Unix-like systems, loopback TCP on Windows).

</details>

<details>
<summary><strong>Security</strong></summary>

Giving autonomous agents tools demands serious security. We use this in real work, so compromise is not an option. AnimaWorks implements ten layers of defense in depth:

| Layer | What it does |
|-------|----------------|
| **Trust-boundary labeling** | External data (web search, Slack, mail) is tagged `untrusted` — models are instructed not to obey directives from untrusted sources |
| **Five-layer command security** | Shell-injection detection → hardcoded blocklist → per-agent denied commands → per-agent allowlist → path-traversal detection |
| **File sandbox** | Each agent is confined to its own directory. `identity.md` is protected. Command permissions are governed by per-anima `permissions.md` and the mandatory global `permissions.global.json` at server startup |
| **Process isolation** | One OS process per agent, local IPC (Unix socket or loopback TCP) |
| **Three-layer rate limiting** | Per-session deduplication → role-based send caps → self-awareness via recent outbound history injected into the prompt |
| **Cascade prevention** | Depth limits plus cascade detection; five-minute cooldown and deferred handling |
| **Authentication & sessions** | Argon2id hashing, 48-byte random tokens, up to ten sessions |
| **Webhook verification** | Slack HMAC-SHA256 with replay protection; Chatwork signature verification |
| **SSRF mitigation** | Media proxy blocks private IPs, enforces HTTPS, validates Content-Type |
| **Outbound routing** | Unknown recipients fail closed; no arbitrary external sends without explicit configuration |

Details: **[Security architecture](docs/security.md)**

</details>

<details>
<summary><strong>CLI reference (advanced)</strong></summary>

The CLI targets power users and automation. Day-to-day work lives in the Web UI.

### Server

| Command | Description |
|---------|-------------|
| `animaworks start [--host HOST] [--port PORT] [-f]` | Start server (`-f` foreground) |
| `animaworks stop [--force]` | Stop server |
| `animaworks restart [--host HOST] [--port PORT]` | Restart server |

### Initialization

| Command | Description |
|---------|-------------|
| `animaworks init` | Initialize runtime directory (non-interactive) |
| `animaworks init --force` | Merge template updates while keeping data |
| `animaworks migrate [--dry-run] [--list] [--force]` | Runtime data migrations (also on startup) |
| `animaworks reset [--restart]` | Reset runtime directory |

### Anima management

| Command | Description |
|---------|-------------|
| `animaworks anima create [--from-md PATH] [--template NAME] [--role ROLE] [--supervisor NAME] [--name NAME]` | Create new |
| `animaworks anima list [--local]` | List all Animas |
| `animaworks anima info ANIMA [--json]` | Detailed settings |
| `animaworks anima status [ANIMA]` | Process status |
| `animaworks anima restart ANIMA` | Restart process |
| `animaworks anima disable ANIMA` / `enable ANIMA` | Disable / enable |
| `animaworks anima set-model ANIMA MODEL` | Change model |
| `animaworks anima set-background-model ANIMA MODEL` | Set background model |
| `animaworks anima reload ANIMA [--all]` | Hot-reload from `status.json` |

### Communication

| Command | Description |
|---------|-------------|
| `animaworks chat ANIMA "message" [--from NAME]` | Send a message |
| `animaworks send FROM TO "message"` | Inter-Anima message |
| `animaworks heartbeat ANIMA` | Trigger heartbeat manually |

### Configuration & maintenance

| Command | Description |
|---------|-------------|
| `animaworks config list [--section SECTION]` | List configuration |
| `animaworks config get KEY` / `set KEY VALUE` | Get / set values |
| `animaworks status` | System status |
| `animaworks logs [ANIMA] [--lines N] [--all]` | View logs |
| `animaworks index [--reindex] [--anima NAME]` | RAG index management |
| `animaworks repair-rag --anima NAME --full` | Quarantine and rebuild RAG indexes |
| `animaworks memory status` / `migrate` / `backup` / `cleanup` | Operate memory backends and memory data |
| `animaworks skills install` / `list` / `inspect` / `remove` / `quarantine` | Skill Hub operations |
| `animaworks task ...` | TaskBoard / task execution operations |
| `animaworks cost` / `profile` | Cost and profile inspection |
| `animaworks models list` / `models info MODEL` | Model list / details |

</details>

<details>
<summary><strong>Tech stack</strong></summary>

| Component | Technology |
|-----------|------------|
| Agent execution | Claude Agent SDK / Codex CLI / Cursor Agent CLI / Gemini CLI / Anthropic SDK (fallback) / LiteLLM |
| Mode S integration | stdio **MCP** (`python -m core.mcp.server`, tool names `mcp__aw__*`) |
| LLM providers | Anthropic, OpenAI, Google, Azure, Vertex AI, AWS Bedrock, Ollama, vLLM, and more (via LiteLLM) |
| Web framework | FastAPI + Uvicorn |
| HTTP middleware | ASGI middleware for request logging (`structlog` + `X-Request-ID`). Avoids `BaseHTTPMiddleware` so SSE bodies stay intact |
| Real time | WebSocket (dashboard notifications, voice, etc.), SSE (chat, meeting streams, etc.), `StreamRegistry` for stream producer lifetime |
| Task scheduling | APScheduler (orphan Anima detection, asset reconciliation, Claude CLI/SDK auto-update checks, global permission consistency, etc.) |
| Configuration & migration | Pydantic 2.0+ / JSON / Markdown, `core/migrations/` (startup migrations) |
| Internationalization (code) | `core/i18n` `t()` (UI, tool schema strings, etc.) |
| Memory / RAG | ChromaDB + sentence-transformers + NetworkX + optional Neo4j. ChromaDB normally runs through the vector worker and can be rebuilt by RAG repair |
| Task management | TaskBoard + TaskExec + persistent task queue |
| Skill system | Skill Hub, explicit skill activation, router, curator, procedure-to-skill promotion |
| Extended tools | Auto-registration from `core/tools/*.py` plus scans of `~/.animaworks/common_tools/` and `animas/<name>/tools/` |
| Voice chat | faster-whisper (STT) + VOICEVOX / SBV2 / ElevenLabs (TTS) |
| Human notification | Slack, Chatwork, LINE, Telegram, ntfy |
| External messaging | Slack Socket Mode, Chatwork Webhook |
| Image generation | NovelAI, fal.ai (Flux), Meshy (3D) |

</details>

<details>
<summary><strong>Project layout</strong></summary>

```
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, activity)
│   ├── skills/          # Skill Hub, activation, router, curator, promotion
│   ├── taskboard/       # TaskBoard store, state, cleanup
│   ├── execution/       # Execution engines (S/C/D/G/A/B)
│   ├── mcp/             # stdio MCP server for Mode S
│   ├── platform/        # Child processes, locks, Codex/Cursor/Gemini plumbing
│   ├── tooling/         # ToolHandler, schemas, external dispatch
│   ├── prompt/          # System prompt builder (six-group structure)
│   ├── supervisor/      # ProcessSupervisor, IPC, TaskExec, streaming
│   ├── voice/           # Voice chat (STT + TTS)
│   ├── 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, …)
│   ├── anima_factory.py, init.py   # Anima creation & runtime initialization
│   ├── outbound.py      # Recipient resolution (internal / Slack / Chatwork, etc.)
│   ├── org_sync.py      # Org hierarchy sync to config
│   ├── asset_reconciler.py, background.py, schedule_parser.py, messenger.py, paths.py, schemas.py
│   └── …
├── cli/                 # CLI package
├── server/              # FastAPI + static Web UI + Workspace
│   ├── app.py           # App factory, lifespan, auth/setup guards, static mounts
│   ├── websocket.py     # Dashboard WebSocket hub
│   ├── stream_registry.py  # Register/clean up SSE and other stream producers
│   ├── room_manager.py  # Meeting room state (shared-directory persistence)
│   ├── reload_manager.py   # Config hot reload
│   ├── slack_socket.py     # Slack Socket Mode
│   ├── localhost.py        # Local trusted-request detection
│   ├── routes/          # REST/WebSocket routes (chat, room, voice, activity_report, brainstorm, team_presets, …)
│   └── static/          # Dashboard (modules/, pages/, styles/, i18n/), setup/ (multilingual wizard), workspace/ (3D client)
└── templates/           # Initialization templates (ja / en / ko)
```

</details>

---

## Documentation

**[Documentation hub](docs/README.md)** — suggested reading order, architecture deep dives, and specification index.

| Document | Description |
|----------|-------------|
| [Vision](docs/vision.md) | Foundational idea: imperfect individuals collaborating |
| [Features](docs/features.md) | What AnimaWorks can do end to end |
| [Memory system](docs/memory.md) | Episodic, semantic, and procedural memory; priming, action memory gate, active forgetting |
| [Security](docs/security.md) | Defense in depth, data provenance, adversarial threat analysis |
| [Brain mapping](docs/brain-mapping.md) | How modules map to the human brain |
| [Technical specification](docs/spec.md) | Execution modes, prompt construction, configuration resolution |

## License

Apache License 2.0. See [LICENSE](LICENSE) for details.
