chekusu/wanman

Agent Matrix 프레임워크 — 당신의 머신에서 협업하는 Claude Code 또는 Codex 에이전트의 감독 네트워크를 실행합니다.

wanman은 오픈 소스 로컬 모드 에이전트 매트릭스 (agent matrix) 프레임워크입니다. JSON-RPC 감독관 (supervisor)을 통해 조정되는 Claude Code 또는 Codex 에이전트의 감독 네트워크를 당신의 머신에서 실행합니다.

wanman이라는 이름은 일본어 ワンマン電車 / one-man train(1인 승무원 열차)에서 유래되었습니다. 이는 차장 없이 운전사 한 명이 운영하는 열차를 의미합니다. wanman의 설계 목표도 이와 정신적으로 유사합니다. 즉, 인간 사용자는 관찰자 역할로 물러나 에이전트 매트릭스가 모든 각도에서 자동으로 실행되는 것을 지켜보게 됩니다.

wanman.ai는 Sandbank Cloud의 샌드박스 클라우드에서 무료로 실행되는, 완전히 자동화된 24/7 샌드박스 에디션의 wanman을 제공합니다.

• 조종/후속 조치 (steer/follow-up) 우선순위를 가진 비동기 메시지 버스 (async message bus)를 통해 여러 에이전트 (CEO, dev, devops, marketing, feedback 등)를 조정합니다.
• 각 에이전트를 실제 Claude Code 또는 Codex CLI 서브프로세스 (subprocess)로 실행합니다 — 사용자가 직접 CLI 인증을 가져오면, wanman이 생성, 프롬프팅 (prompting) 및 라이프사이클 (lifecycle)을 오케스트레이션 (orchestrate)합니다.
• 모든 에이전트를 에이전트별 워크트리 (worktree)와 에이전트별 $HOME에 격리하므로, 에이전트가 당신의 더러운 체크아웃 (dirty checkout)이나 쉘 프로필 (shell profile)을 변경하지 않습니다.
• CLI 우선 (CLI-first) 방식입니다: 모든 것은 wanman 명령과 JSON-RPC 감독관을 통해 스크립트화, 관찰 및 재현이 가능합니다.
• API 자격 증명 인벤토리, 제공업체 비용 동기화, Stripe 수익 동기화, 제품/회사 ROI 요약을 위한 실험적인 @wanman/finops 툴킷을 포함합니다.

wanman.ai는 호스팅 전용 기능을 추가합니다:

• 각 에이전트 런타임 그룹을 자체 샌드박스 환경에 격리하여 대규모, 고동시성 작업 실행을 지원합니다.
• 인터넷상의 고품질 에이전트 역할 카탈로그에서 역할을 자동으로 추출하는 것을 포함하여, 에이전트 역할을 동적으로 구성합니다.
• 동적인 기술 자기 진화 (skill self-evolution)를 지원합니다.
• db9 기반의 글로벌 검색 및 스토리 검색을 지원합니다.

# Prerequisites: Node 20+, pnpm 9+, git, a logged-in Claude Code or Codex CLI.
git clone git@github.com:chekusu/wanman.git wanman.dev
cd wanman.dev
...

단일 파일 CLI 번들 (single-file CLI bundle)을 원하는 경우:

pnpm --filter @wanman/cli standalone
node packages/cli/dist/wanman.mjs takeover /path/to/any/git/repo

만약 wanman이 이미 PATH에 설정되어 있다면, 대상 저장소(repository) 내부에서 wanman takeover .를 실행할 수도 있습니다.

전체 과정을 확인하려면 docs/quickstart.md를 참조하세요.

비용 및 수익 회계 (cost and revenue accounting)에 대해서는 docs/finops.md를 참조하세요. 로컬 FinOps 리뷰 앱은 pnpm --filter @wanman/finops dev -- --host 127.0.0.1 --port 4173으로 실행됩니다.

명령어	기능
wanman send <agent> <msg>	에이전트 (agent)에게 메시지를 보냅니다 (--steer 옵션은 대상을 중단시킵니다).
wanman recv [--agent <name>]	대기 중인 메시지를 수신하고 전달됨으로 표시합니다.
wanman agents	등록된 에이전트 목록과 현재 상태를 나열합니다.
wanman context get / context set	공유된 키/값 (key/value) 컨텍스트를 읽거나 씁니다.
wanman escalate <msg>	CEO 에이전트에게 에스컬레이션 (escalate) 합니다.
wanman task …	태스크 풀 (task pool)을 관리합니다: create, list, get, update, done. --after 의존성을 지원합니다.
wanman initiative …	장기적인 이니셔티브 (initiatives)를 관리합니다: create, list, get, update.
wanman capsule …	변경 캡슐 (change capsules)을 관리합니다: create, list, mine, get, update.
wanman artifact …	구조화된 아티팩트 (artifacts)를 저장하고 검색합니다: put, list, get.
wanman hypothesis …	상태 전이가 포함된 가설 (hypotheses)을 추적합니다: create, list, update.
wanman watch	감독자 (supervisor) 및 에이전트 활동을 라이브 스트리밍합니다.
wanman run <goal>	단발성 목표 (one-shot goal)에 대해 매트릭스 (matrix)를 시작합니다.
wanman takeover <path>	전체 에이전트 매트릭스로 기존 git 저장소를 인수 (take over) 합니다.
wanman skill:check [path]	스킬 문서가 실제 CLI 명령어만 참조하는지 검증합니다.

전체 최신 목록을 보려면 wanman --help를 실행하세요.

+----------------+ +--------------------+ +-----------------+
| wanman CLI | JSON | Supervisor | spawn | Agent process |
| (host shell) | ---RPC-->| (local process) | -------> | (Claude/Codex) |
...

wanman <subcommand>

Supervisor 프로세스에 JSON-RPC 2.0 방식으로 통신합니다.

• Supervisor는 메시지 저장소 (message store), 컨텍스트 저장소 (context store), 태스크 풀 (task pool), 아티팩트 저장소 (artifact store)를 소유하며, 에이전트당 하나의 자식 프로세스 (child process)를 생성합니다.
• 각 에이전트 자식은 에이전트별 워크트리 (worktree)에 바인딩되고 $HOME이 격리된 로컬 Claude Code 또는 Codex 서브프로세스 (subprocess)입니다.

심층 분석: docs/architecture.md

환경 변수 (Env var)	의미 (Meaning)
WANMAN_URL	CLI를 위한 Supervisor HTTP URL (기본값 http://localhost:3120)
WANMAN_AGENT_NAME	현재 에이전트를 식별하며, 에이전트 프로세스 내부에서 기본 송신자/수신자로 사용됨
WANMAN_RUNTIME	claude (기본값) 또는 codex — 에이전트별 CLI 어댑터 (adapter)를 선택
WANMAN_MODEL, WANMAN_CODEX_MODEL, WANMAN_CODEX_REASONING_EFFORT	런타임별 모델 재정의 (overrides)
WANMAN_CODEX_FAST	설정 시, Codex 어댑터를 낮은 지연 시간 (lower-latency) 기본값으로 편향시킴
WANMAN_SKILL_SNAPSHOTS_DIR	런타임이 스킬 활성화 스냅샷 (skill-activation snapshots)을 생성하는 위치 재정의 (기본값: shared-skills 디렉토리의 형제 디렉토리, 실패 시 $TMPDIR/wanman-skill-snapshots 사용)

교차 실행 메모리 (cross-run memory)를 위해 선택 사항인 @sandbank.dev/db9 브레인 어댑터 (brain adapter)를 연결할 수 있습니다 — docs/architecture.md 참조.

에이전트 정의는 단일 JSON 파일에 저장됩니다:

{
"agents": [
{ "name": "echo", "lifecycle": "24/7", "model": "standard", "systemPrompt": "..." },
...

각 에이전트 항목은 다음을 포함합니다:

name — 메시지 버스 (message bus)에서 사용되는 고유 식별자.

lifecycle — 24/7 (지속적인 재생성 루프), on-demand (트리거될 때까지 유휴 상태), 또는 idle_cached (트리거될 때까지 유휴 상태이지만, 이전 Claude session_id가 claude --resume을 통해 트리거 간에 보존되어 유휴 기간 동안 컨텍스트가 유지됨). idle_cached와 결합하는 것은 Claude 전용입니다. runtime: codex (또는 WANMAN_RUNTIME=codex)는 시작 시 거부되는데, 이는 Codex가 이 런타임에서 그에 상응하는 재개 (resume) 메커니즘을 가지고 있지 않기 때문입니다.

model — 일반적으로 추상화된 티어 (high 또는 standard)이며, 런타임 어댑터가 이를 Claude 또는 Codex 기본값으로 매핑합니다. 환경 변수를 통한 재정의가 가능합니다.

systemPrompt

— 내장된 페르소나/미션 (baked-in persona/mission); 에이전트는 또한 ~/.claude/skills/에서 공유 스킬 파일을 자동으로 발견합니다.

• 선택 사항 (Optional)
  cron, events, 그리고 tools 필드 — 전체 스키마(schema)는 아키텍처 문서(architecture doc)를 참조하세요.

pnpm typecheck
pnpm test
pnpm exec vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary --coverage.exclude='**/dist/**'

현재 커버리지(coverage) 목표는 최소 90% 라인 커버리지(line coverage)입니다. 최근 검증된 로컬 실행 결과는 Lines: 90.17%를 보고합니다.

; 기계 판독 가능한 요약(machine-readable summary)은 coverage/coverage-summary.json에 기록됩니다.

wanman.dev/
packages/
cli/ wanman CLI (send/recv/task/artifact/run/takeover/...)
...

오늘 배포된 공유 스킬 (Shared skills) (packages/core/skills/):

artifact-naming, artifact-quality — 에이전트가 생성한 아티팩트(artifact)를 위한 컨벤션 (conventions).
cross-validation — 에이전트 출력물 전반에 대한 CEO 일관성 체크.
research-methodology — 시장/데이터 조사 방법론.
wanman-cli — 런타임(runtime) 시 에이전트가 사용하는 CLI 명령어 참조.
workspace-conventions — 에이전트 워크스페이스(workspace) 내부의 파일 시스템 컨벤션.

• Quickstart — 모든 git 리포지토리(repo)를 대상으로 하는 첫 실행 가이드.
• Architecture — 에이전트 라이프사이클 (agent lifecycle), JSON-RPC, 스토어 (stores), 어댑터 (adapters).
• Contributing — 테스트, 타입 체크 (typecheck), 커밋 컨벤션 (commit conventions).

Apache-2.0 — LICENSE를 참조하세요.