convez.ai
Agente
xuiltul

animaworks

xuiltul/animaworks

Ver no GitHub
BomPluginScore · de 0 a 100

Organization-as-Code for autonomous AI agents. Brain-inspired memory that grows, consolidates, and forgets. Multi-model (Claude/Codex/Gemini/Cursor/Ollama).

Instalação

$npx convez-ai xuiltul/animaworks

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
269
Forks
48
Acompanhando
2
Saúde
71%
Último commit
há 3 dias
Versão
v0.18.0
Issues abertas
1
Contribuidores
15

README

A tradução para o português deste README ainda está na fila.

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.

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


How It Compares

AnimaWorksCrewAILangGraphOpenClawOpenAI Agents
Design philosophyOrganization of autonomous agentsRole-based teamsGraph workflowsPersonal assistantLightweight SDK
MemoryNeuroscience-inspired: RAG (Chroma + graph), consolidation, active forgetting, automatic recall, and memory checks before actionCognitive Memory (manual forget)Checkpoints + cross-thread storeSuperMemory knowledge graphSession-scoped only
AutonomyHeartbeat (observe → plan → reflect) + Cron + TaskExec — runs 24/7Human-triggeredHuman-triggeredCron + heartbeatHuman-triggered
Org structureSupervisor → subordinate hierarchy, delegation, audit, dashboardFlat roles in a crew—Single agentHandoffs only
Process modelOne isolated OS process per agent, IPC, auto-restartShared processShared processSingle processShared process
Multi-modelSix engines: Claude SDK / Codex / Cursor Agent / Gemini CLI / LiteLLM / Assisted (Anthropic SDK falls back inside Mode A when Agent SDK is not installed)LiteLLMLangChain modelsOpenAI-compatibleOpenAI-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.

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 →

Switch language / style: PRESET=ja-anime docker compose up — full preset list


Quick Start

macOS / Linux / WSL:

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):

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

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

# Start
uv run animaworks start

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.

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

What You Can Do

Dashboard

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

Multi-model support

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

ModeEngineTargetsTools
S (SDK)Claude Agent SDKClaude 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 modelsCodex sandbox + AnimaWorks MCP (core/mcp/server.py) for internal tools
D (Cursor)Cursor Agent CLIcursor/* modelsMCP-integrated agent loop
G (Gemini CLI)Gemini CLIgemini/* modelsstream-json parsing, tool loop
A (Autonomous)LiteLLM + tool_useGPT, 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-shotUnstable 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

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.

LLM providers

KeyServiceModeWhere to get it
ANTHROPIC_API_KEYAnthropic APIS / Aconsole.anthropic.com
OPENAI_API_KEYOpenAIA / C (optional with Codex Login)platform.openai.com/api-keys
GOOGLE_API_KEYGoogle AI (Gemini)Aaistudio.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.

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

Image generation (optional)

KeyServiceOutputWhere to get it
NOVELAI_API_TOKENNovelAIAnime-style character artnovelai.net
FAL_KEYfal.ai (Flux)Stylized / photorealisticfal.ai/dashboard/keys
MESHY_API_KEYMeshy3D character modelsmeshy.ai

Voice chat (optional)

RequirementServiceNotes
pip install faster-whisperSTT (Whisper)Model auto-downloads on first use; GPU recommended
VOICEVOX Engine runningTTS (VOICEVOX)Default: http://localhost:50021
AivisSpeech / SBV2 runningTTS (Style-BERT-VITS2)Default: http://localhost:5000
ELEVENLABS_API_KEYTTS (ElevenLabs)Cloud API

External integrations (optional)

KeyServiceWhere to get it
SLACK_BOT_TOKEN / SLACK_APP_TOKENSlackSetup guide
CHATWORK_API_TOKENChatworkchatwork.com
DISCORD_BOT_TOKEN (or per-Anima DISCORD_BOT_TOKEN__<name>)DiscordDiscord Developer Portal
NOTION_API_TOKEN (or NOTION_API_TOKEN__<name>)NotionNotion integrations

Google Calendar, Google Tasks, Gmail, and similar are configured under credentials in config.json (OAuth or service account). See the technical specification.

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

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

RoleDefault modelUse case
engineerClaude Opus 4.6Complex reasoning, code generation
managerClaude Opus 4.6Coordination, decision-making
writerClaude Sonnet 4.6Content creation
researcherClaude Sonnet 4.6Information gathering
opsvLLM (GLM-4.7-flash)Log monitoring, routine work
generalClaude Sonnet 4.6General-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).

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:

LayerWhat it does
Trust-boundary labelingExternal data (web search, Slack, mail) is tagged untrusted — models are instructed not to obey directives from untrusted sources
Five-layer command securityShell-injection detection → hardcoded blocklist → per-agent denied commands → per-agent allowlist → path-traversal detection
File sandboxEach 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 isolationOne OS process per agent, local IPC (Unix socket or loopback TCP)
Three-layer rate limitingPer-session deduplication → role-based send caps → self-awareness via recent outbound history injected into the prompt
Cascade preventionDepth limits plus cascade detection; five-minute cooldown and deferred handling
Authentication & sessionsArgon2id hashing, 48-byte random tokens, up to ten sessions
Webhook verificationSlack HMAC-SHA256 with replay protection; Chatwork signature verification
SSRF mitigationMedia proxy blocks private IPs, enforces HTTPS, validates Content-Type
Outbound routingUnknown recipients fail closed; no arbitrary external sends without explicit configuration

Details: Security architecture

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

Server

CommandDescription
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

CommandDescription
animaworks initInitialize runtime directory (non-interactive)
animaworks init --forceMerge 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

CommandDescription
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 ANIMARestart process
animaworks anima disable ANIMA / enable ANIMADisable / enable
animaworks anima set-model ANIMA MODELChange model
animaworks anima set-background-model ANIMA MODELSet background model
animaworks anima reload ANIMA [--all]Hot-reload from status.json

Communication

CommandDescription
animaworks chat ANIMA "message" [--from NAME]Send a message
animaworks send FROM TO "message"Inter-Anima message
animaworks heartbeat ANIMATrigger heartbeat manually

Configuration & maintenance

CommandDescription
animaworks config list [--section SECTION]List configuration
animaworks config get KEY / set KEY VALUEGet / set values
animaworks statusSystem status
animaworks logs [ANIMA] [--lines N] [--all]View logs
animaworks index [--reindex] [--anima NAME]RAG index management
animaworks repair-rag --anima NAME --fullQuarantine and rebuild RAG indexes
animaworks memory status / migrate / backup / cleanupOperate memory backends and memory data
animaworks skills install / list / inspect / remove / quarantineSkill Hub operations
animaworks task ...TaskBoard / task execution operations
animaworks cost / profileCost and profile inspection
animaworks models list / models info MODELModel list / details
ComponentTechnology
Agent executionClaude Agent SDK / Codex CLI / Cursor Agent CLI / Gemini CLI / Anthropic SDK (fallback) / LiteLLM
Mode S integrationstdio MCP (python -m core.mcp.server, tool names mcp__aw__*)
LLM providersAnthropic, OpenAI, Google, Azure, Vertex AI, AWS Bedrock, Ollama, vLLM, and more (via LiteLLM)
Web frameworkFastAPI + Uvicorn
HTTP middlewareASGI middleware for request logging (structlog + X-Request-ID). Avoids BaseHTTPMiddleware so SSE bodies stay intact
Real timeWebSocket (dashboard notifications, voice, etc.), SSE (chat, meeting streams, etc.), StreamRegistry for stream producer lifetime
Task schedulingAPScheduler (orphan Anima detection, asset reconciliation, Claude CLI/SDK auto-update checks, global permission consistency, etc.)
Configuration & migrationPydantic 2.0+ / JSON / Markdown, core/migrations/ (startup migrations)
Internationalization (code)core/i18n t() (UI, tool schema strings, etc.)
Memory / RAGChromaDB + sentence-transformers + NetworkX + optional Neo4j. ChromaDB normally runs through the vector worker and can be rebuilt by RAG repair
Task managementTaskBoard + TaskExec + persistent task queue
Skill systemSkill Hub, explicit skill activation, router, curator, procedure-to-skill promotion
Extended toolsAuto-registration from core/tools/*.py plus scans of ~/.animaworks/common_tools/ and animas/<name>/tools/
Voice chatfaster-whisper (STT) + VOICEVOX / SBV2 / ElevenLabs (TTS)
Human notificationSlack, Chatwork, LINE, Telegram, ntfy
External messagingSlack Socket Mode, Chatwork Webhook
Image generationNovelAI, fal.ai (Flux), Meshy (3D)
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)

Documentation

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

DocumentDescription
VisionFoundational idea: imperfect individuals collaborating
FeaturesWhat AnimaWorks can do end to end
Memory systemEpisodic, semantic, and procedural memory; priming, action memory gate, active forgetting
SecurityDefense in depth, data provenance, adversarial threat analysis
Brain mappingHow modules map to the human brain
Technical specificationExecution modes, prompt construction, configuration resolution

License

Apache License 2.0. See LICENSE for details.

Ver o original no GitHub

Bom para

Relacionados