xuiltul/animaworks

그 누구도 혼자서는 아무것도 할 수 없습니다. 그래서 저는 조직을 만들었습니다.

AI 에이전트(AI agents)를 단순한 "도구"가 아니라 자율적으로 일하는 사람으로 취급하는 프레임워크입니다. 각 Anima는 이름, 성격, 기억, 그리고 일정을 가지고 있습니다. 이들은 메시지로 협업하고, 스스로 결정하며, 하나의 팀으로서 움직입니다. 리더에게 말을 거세요. 나머지는 알아서 돌아갑니다.

워크스페이스 대시보드: 각 Anima의 역할, 상태, 최근 활동을 실시간으로 확인할 수 있습니다.

3D 오피스: Anima들이 책상에 앉아 돌아다니며 스스로 메시지를 주고받습니다.

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

비교 항목	AnimaWorks	CrewAI	LangGraph	OpenClaw	OpenAI Agents
설계 철학 (Design philosophy)	자율 에이전트 조직 (Organization of autonomous agents)	역할 기반 팀 (Role-based teams)	그래프 워크플로우 (Graph workflows)	개인 비서 (Personal assistant)	경량 SDK (Lightweight SDK)
기억 (Memory)	신경과학 영감: RAG (Chroma + graph), 공고화 (consolidation), 3단계 망각 (three-stage forgetting), 6채널 자동 프라이밍 (six-channel automatic priming, 신뢰 태그 포함)	인지 기억 (Cognitive Memory, 수동 망각)	체크포인트 (Checkpoints) + 교차 스레드 저장소 (cross-thread store)	SuperMemory 지식 그래프 (knowledge graph)	세션 범위 한정 (Session-scoped only)
자율성 (Autonomy)	하트비트 (Heartbeat: 관찰 → 계획 → 성찰) + Cron + TaskExec — 24/7 가동	인간 트리거 (Human-triggered)	인간 트리거 (Human-triggered)	Cron + 하트비트 (heartbeat)	인간 트리거 (Human-triggered)
조직 구조 (Org structure)	관리자 → 부하 계층 구조 (Supervisor → subordinate hierarchy), 위임 (delegation), 감사 (audit), 대시보드	크루 내 평면적 역할 (Flat roles in a crew)	—	단일 에이전트 (Single agent)	핸드오프만 지원 (Handoffs only)
프로세스 모델 (Process model)	에이전트당 하나의 격리된 OS 프로세스, IPC, 자동 재시작 (auto-restart)	공유 프로세스 (Shared process)	공유 프로세스 (Shared process)	단일 프로세스 (Single process)	공유 프로세스 (Shared process)
멀티 모델 (Multi-model)	6개 엔진: Claude SDK / Codex / Cursor Agent / Gemini CLI / LiteLLM / Assisted (Agent SDK가 설치되지 않은 Mode A 내부에서는 Anthropic SDK로 폴백)	LiteLLM	LangChain 모델	OpenAI 호환 (OpenAI-compatible)	OpenAI 중심 (OpenAI-centric)

AnimaWorks는 단순한 작업 실행기(task runner)가 아닙니다. 생각하고, 기억하고, 잊고, 성장하는 조직입니다. 팀으로서 운영을 지원할 수 있으며, 마치 회사처럼 운영될 수 있습니다. 저는 이것을 실제 AI 회사처럼 운영합니다.

약 60초면 실행할 수 있습니다. API 키와 Docker만 있으면 됩니다.

git clone https://github.com/xuiltul/animaworks.git
cd animaworks/demo
cp .env.example .env # ANTHROPIC_API_KEY를 붙여넣으세요
...

3인 팀(매니저 + 엔지니어 + 코디네이터)이 3일간의 활동 이력과 함께 즉시 시작됩니다. 데모 상세 정보 →

언어 / 스타일 전환:

PRESET=ja-anime docker compose up

— 전체 프리셋(preset) 목록

macOS / Linux / WSL:

curl -sSL https://raw.githubusercontent.com/xuiltul/animaworks/main/scripts/setup.sh | bash
cd animaworks
uv run animaworks start # 서버 시작 — 첫 실행 시 설정 마법사(setup wizard)가 열립니다

Windows (PowerShell):

git clone https://github.com/xuiltul/animaworks.git
cd animaworks
uv sync
...

API 키 없이 OpenAI Codex를 사용하려면, 첫 실행 전에 codex login을 실행하세요.

http://localhost:18500/ 을 여세요 — 설정 마법사가 다음 단계를 안내합니다:

Language (언어)— UI 표시 언어를 선택하세요
User info (사용자 정보)— 소유자 계정을 생성하세요
Provider auth (제공자 인증)— API 키를 입력하거나 OpenAI를 위해 Codex Login을 선택하세요
First Anima (첫 번째 Anima)— 첫 번째 에이전트(agent)의 이름을 지정하세요

.env 파일을 직접 편집할 필요는 없습니다. 마법사가 설정을 config.json에 자동으로 저장합니다.

설정 스크립트는 uv를 설치하고, 저장소(repository)를 클론하며, 모든 종속성(dependencies)이 포함된 Python 3.12+ 버전을 다운로드합니다. macOS, Linux, WSL은 Python이 미리 설치되어 있지 않아도 작동합니다. Windows의 경우 위의 PowerShell 단계를 사용하세요.

기타 LLM: Claude, GPT, Gemini, 로컬 모델 등이 지원됩니다. 설정 마법사에서 API 키를 입력하거나, OpenAI/Codex의 경우 Codex Login을 사용하세요. 이는 나중에 대시보드의 Settings(설정)에서 변경할 수 있습니다. API Key Reference(API 키 참조)를 확인하세요.

대안: 실행 전 스크립트 검토

curl을 bash로 바로 파이프(pipe) 연결하는 것을 선호하지 않는다면, 먼저 스크립트를 검토하세요:

curl -sSL https://raw.githubusercontent.com/xuiltul/animaworks/main/scripts/setup.sh -o setup.sh
cat setup.sh # 스크립트 검토
bash setup.sh # 검토 후 실행

대안: uv를 이용한 수동 설치 (단계별 안내)

# uv 설치 (이미 설치되어 있다면 건너뛰세요)
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
...

대안: pip를 이용한 수동 설치

macOS 사용자: macOS Sonoma 및 이전 버전의 시스템 Python (/usr/bin/python3)은 3.9 버전이며, 이는 AnimaWorks의 요구 사항(3.12+)을 충족하지 않습니다. Homebrew (brew install python@3.13)를 사용하여 설치하거나, 위의 uv 방식(uv가 Python을 대신 관리해 줍니다)을 사용하세요.

시스템에 Python 3.12+ 버전이 필요합니다.

git clone https://github.com/xuiltul/animaworks.git && cd animaworks
python3 -m venv .venv && source .venv/bin/activate
python3 --version # 3.12+ 버전 확인
...

대시보드(Dashboard): 4개의 계층 구조(hierarchy levels), 19개의 Anima가 실행 중이며 실시간 상태를 표시합니다.

왼쪽 사이드바를 사용하여 주요 화면 간에 이동할 수 있습니다 (해시 라우터 #/… 사용).

채팅 (Chat)— 모든 Anima와 실시간 대화가 가능합니다. 스트리밍 응답 (SSE), 이미지 첨부, 멀티 스레드 히스토리(multi-thread history), 전체 아카이브를 지원합니다.
회의 모드 (Meeting mode)— 지정된 퍼실리테이터(facilitator)와 함께 한 방에 여러 Anima를 모읍니다 (최대 5명의 참가자, 전용 API 사용).
음성 채팅 (Voice chat)— 브라우저에서만 음성 기능을 사용합니다 (Push-to-talk 또는 핸즈프리). WebSocket 기반입니다. VOICEVOX / SBV2 / ElevenLabs를 지원합니다.
보드 (Board)— Anima들이 서로 토론하고 조율하는 Slack 스타일의 공유 채널입니다.
대시보드 (Dashboard/home)— 조직의 개요 및 상태를 보여줍니다.
활동 (Activity)— 조직 전체의 실시간 피드입니다.
설정 (Setup)— 첫 실행 시 http://HOST/setup/에 있는 위저드(wizard)를 사용합니다. 설정 완료 후, 브라우저에서 /setup은 최상위 레벨로 리다이렉트되지만, #/setup을 통해 동일한 항목(언어, 인증 등)을 열 수 있습니다.

대시보드 내부
Users (사용자) — 소유자 및 사용자 프로필 관리
Anima management (Anima 관리) — Anima별 활성화/비활성화, 모델 및 메타데이터 설정
Process monitoring (프로세스 모니터링) — 자식 프로세스(Child process) 상태 확인
Server (서버) — 서버 측 상태 및 설정
Memory (메모리) — 각 Anima의 에피소드, 지식, 절차 등을 탐색
Logs (로그) — 로그 뷰어
Assets (에셋) — 캐릭터 이미지, 3D 및 기타 에셋
Activity report (활동 보고서) — 조직 간 감사(Cross-org auditing) 및 활동 데이터를 기반으로 LLM이 매일 생성하는 내러티브 (캐싱됨)
Prompt settings (프롬프트 설정) — 도구 실행(Tool execution) 관련 프롬프트 조정
AI brainstorm (AI 브레인스토밍) — 다양한 관점 프리셋(현실주의자, 도전론자 등)을 활용한 LLM 세션
Team builder / team edit (팀 빌더 / 팀 편집) — 산업 및 목표 지향적 프리셋을 통해 다중 Anima 역할 레이아웃을 구축하고 조정
Settings (설정) — 서버, 인증, 로캘(Locale) 등
Workspace (워크스페이스) — /workspace/ 경로에서 별도의 탭으로 열리는 3D 사무실

(채팅, 보드, 조직 트리 등); 메인 대시보드와 분리된 정적 앱
Multilingual (다국어 지원) — UI 문구가 17개 언어로 제공됩니다.
First-run setup wizard (첫 실행 설정 마법사) — ja(일본어), en(영어), ko(한국어)를 지원합니다.
JSON 번역을 사용하며 (누락된 키는 일본어로 대체됩니다). Anima용 템플릿은 일본어와 영어를 기본값으로 배포됩니다.

리더에게 "이런 사람이 필요해"라고 말하세요. 리더는 역할, 성격, 계층 구조를 추론하여 새로운 멤버를 생성합니다. 설정 파일이나 CLI(명령줄 인터페이스)가 필요하지 않습니다. 조직은 오직 대화를 통해 성장합니다.

팀이 준비되면, 인간의 개입(Human in the loop) 없이도 계속해서 움직입니다:

Heartbeat (하트비트) — 주기적으로 상황을 검토하고 다음 행동을 결정
Cron jobs (크론 잡) — 일일 보고서, 주간 요약, 모니터링 — Anima별 스케줄링
Task delegation (작업 위임) — 관리자가 부하 직원에게 업무를 할당하고, 진행 상황을 추적하며, 보고를 받음
Parallel task execution (병렬 작업 실행) — 많은 작업을 한 번에 제출; 의존성(Dependencies)이 해결되며 독립적인 작업들은 병렬로 실행됨
Night consolidation (야간 통합) — 낮 동안의 에피소드 기억은 "잠든" 동안 지식으로 정제됨
Team coordination (팀 협업) — 공유 채널과 DM을 통해 모두가 자동으로 정렬된 상태를 유지

일반적인 AI 에이전트(AI agents)는 컨텍스트 윈도우(context window)에 들어가는 정보만을 기억합니다. AnimaWorks의 Anima는 영구적인 메모리(persistent memory)를 유지하며, 필요할 때 마치 선반에서 책을 꺼내듯 이를 검색합니다.

자동 프라이밍 (Automatic priming, Priming) — 메시지가 도착하면 여섯 가지 병렬 검색이 실행됩니다: 발신자 프로필, 최근 활동, 관련 지식 및 에피소드에 대한 RAG 벡터 검색 (RAG vector search), 기술(skills), 보류 중인 작업(pending tasks) 등. 명시적인 지시 없이도 회상(Recall)이 이루어집니다.

공고화 (Consolidation) — 매일 밤, 낮 동안의 에피소드들이 지식으로 변환됩니다. 이는 신경과학(neuroscience)에서 수면 중에 일어나는 기억 공고화(memory consolidation)와 유사합니다. 해결된 문제들은 자동으로 절차(procedures)가 됩니다.

망각 (Forgetting) — 사용 빈도가 낮은 기억은 3단계(표시 → 병합 → 아카이브)를 거쳐 희미해집니다. 중요한 절차와 기술은 보호됩니다. 인간의 뇌와 마찬가지로, 망각 또한 중요합니다.

채팅: 매니저가 코드 변경 사항을 검토하는 동안 엔지니어가 진행 상황을 보고합니다.

다양한 LLM과 함께 작동합니다. 각 Anima는 서로 다른 모델을 사용할 수 있습니다.

모드 (Mode)	엔진 (Engine)	대상 (Targets)	도구 (Tools)
S (SDK)	Claude Agent SDK	Claude 모델 (권장)	Claude Code 내장 기능 (Read/Write/Edit/Bash/Grep/Glob 등) + AnimaWorks 내부 도구를 위한 stdio MCP (mcp__aw__*) ; skill → animaworks-tool을 통한 외부 통합
...	MCP 통합 에이전트 루프 (MCP-integrated agent loop)
G (Gemini CLI)	Gemini CLI	gemini/* 모델	stream-json 파싱, 도구 루프 (tool loop)
A (Autonomous)	LiteLLM + tool_use	GPT, Gemini, Mistral, Bedrock, Vertex, xAI 등	CC 스타일 (Read/Write/Edit/Bash/Grep/Glob, WebSearch/WebFetch) + 메모리, 메시징, 작업 (submit_tasks 등), todo_write, skill 및 기타 (알림 및 감독 도구에 따라 다름)
B (Basic)	LiteLLM one-shot	불안정한 tool_use 로컬 모델 (예: 소형 Ollama)	프롬프트 내 의사 도구 호출 (Pseudo tool calls); 프레임워크가 모델을 대신하여 메모리 I/O를 처리함

모드 결정(Mode resolution): status.json에 있는 execution_mode가 우선순위를 가집니다. 그렇지 않으면 모델 이름 패턴 (fnmatch)이 자동으로 사용됩니다. Ollama의 경우, 도구 사용이 가능한 모델 (tool_use-capable models) (예: ollama/qwen3:14b)

, ollama/glm-4.7*)

)는 A로 매핑됩니다. 다른 모델들은 B로 폴백 (fallback)되는 경향이 있습니다. Heartbeat, Cron, 그리고 Inbox는 메인 모델과 분리된 별도의 **백그라운드 모델 (background_model)**에서 실행될 수 있습니다 (비용 최적화). 사용 가능한 경우 확장된 사고 (Extended thinking) 기능이 지원됩니다.

성격 설정(personality settings)으로부터: 전신(full-body), 상반신(bust-up), 그리고 다양한 표정 변형이 자동 생성됩니다. 감독자(supervisor)의 화풍을 상속받는 바이브 전송 (Vibe Transfer) 기능이 포함되어 있습니다.

NovelAI (애니메이션 스타일), fal.ai/Flux (스타일리시 / 실사), 그리고 Meshy (3D)를 지원합니다. 이 제품은 이미지 서비스를 별도로 설정할 필요 없이 실행할 수 있으며, 단순히 아바타 단계를 건너뛰면 됩니다. 일단 아바타가 생성되고 나면, 정이 들 수도 있습니다.

이 프로젝트는 세 가지 직업의 교차점에 위치합니다.

창업자로서 — 저는 아무도 혼자서 무엇인가를 할 수 없다는 것을 알고 있습니다. 유능한 엔지니어, 소통을 잘하는 사람, 안정적인 운영자, 그리고 가끔 날카로운 아이디어를 던지는 사람들이 필요합니다. 천재성만으로는 조직을 운영할 수 없습니다. 다양한 강점들이 모였을 때 비로소 개인이 이룰 수 없는 일을 달성합니다.

정신과 의사로서 — LLM (대규모 언어 모델)의 내부 구조를 연구하며, 저는 인간의 뇌와 놀라울 정도로 유사한 구조를 보았습니다. 회상(Recall), 학습(Learning), 망각(Forgetting), 공고화(Consolidation) — 뇌의 기억 메커니즘을 LLM 기억 시스템으로 구현하는 것은 우리가 기억을 처리하는 방식과 유사할 수 있습니다. 만약 우리가 LLM을 유사 인간(pseudo-humans)으로 취급할 수 있다면, 사람과 마찬가지로 조직을 구축할 수 있을 것입니다.

엔지니어로서 — 저는 30년 동안 코드를 작성해 왔습니다. 로직을 연결하는 즐거움과 자동화가 주는 짜릿함을 알고 있습니다. 그러한 이상들을 코드에 담음으로써 제가 원하는 조직을 구축할 수 있습니다.

훌륭한 “단일 AI 어시스턴트 (single AI assistant)” 프레임워크는 이미 존재합니다. 하지만 아직 코드상에서 사람을 재현하고 그들이 조직으로서 기능하게 만든 프로젝트는 없었습니다. AnimaWorks는 제가 자신의 비즈니스에서 사용하며 함께 성장시켜 나가는 실제 조직입니다.

구조를 통해 협업하는 불완전한 개인들은 그 어떤 단일한 전지전능한 행위자보다 뛰어난 성과를 냅니다.

세 가지 원칙이 이를 지탱합니다:

캡슐화 (Encapsulation)— 생각과 기억은 외부에서 보이지 않게 유지됩니다. 다른 이들은 실제 조직처럼 오직 텍스트 대화를 통해서만 연결됩니다.

RAG 메모리 (도서관 모델, RAG memory (library model))— 모든 것을 컨텍스트 윈도우 (context window)에 쑤셔 넣지 마세요. 프라이밍 (Priming)은 RAG를 통해 관련 청크 (chunks)를 가져오며, 에이전트 (agents)는 search_memory 및 이와 유사한 도구들을 사용하여 스스로 회상합니다.

자율성 (Autonomy)— 명령을 기다리지 않습니다. 그들은 자신만의 리듬으로 실행되며 자신만의 가치에 따라 판단합니다.

API 키 참조 (API Key Reference)

키 (Key)	서비스 (Service)	모드 (Mode)	획득처 (Where to get it)
ANTHROPIC_API_KEY	Anthropic API	S / A	console.anthropic.com
OPENAI_API_KEY	OpenAI	A / C (Codex 로그인 시 선택 사항)	platform.openai.com/api-keys
GOOGLE_API_KEY	Google AI (Gemini)	A	aistudio.google.com/apikey

**OpenAI Codex (Mode C)**는 OPENAI_API_KEY와 로컬 Codex 로그인 (Codex Login) (codex login)을 모두 지원합니다. 설정 마법사 또는 설정 (Settings)에서 선택하십시오.

Azure OpenAI, Vertex AI (Gemini), AWS Bedrock, 그리고 vLLM은 config.json의 credentials 섹션에서 구성됩니다. 기술 사양을 참조하십시오.

Ollama 및 이와 유사한 로컬 모델들은 API 키가 필요하지 않습니다. OLLAMA_SERVERS를 설정하십시오 (기본값: http://localhost:11434).