How itznan/naantree works
Naantree is a Rust CLI and coordination protocol for multiple AI coding agents sharing one repository and branch. Agents join a swarm, plan and claim work, communicate and review changes, then run a verification gate and finish. The map preserves those documented capabilities, including serialized Git and hooks. Core storage, locking, identity, path matching, context, and output formatting form the internal layer. Some command implementations were not excerpted; their subsystem links are included only where the README documents the command or the source index supports the dependency.
Main entry points: cli.rs CLI Interface · task.rs Task Board · lock.rs Atomic Locking · finish.rs Gate & Finish
Components 18
Swarm Workflow
- CLI Interface
src/cli.rs - Join & Lifecycle
src/cmds/lifecycle.rs - Plan & Tasks
src/cmds/plan.rs - Task Board
src/cmds/task.rs - Path Claims
src/cmds/claim.rs - Gate & Finish
src/cmds/finish.rs
Coordination Features
- Messages & Wait
src/cmds/comm.rs - Status & Doctor
src/cmds/status.rs
Git Safety
- Commit & Sync
src/cmds/git_cmds.rs - Git Hooks
src/cmds/hooks.rs
Runtime Core
- Agent Context
src/core/context.rs - Swarm State
src/core/store.rs - Atomic Locking
src/core/lock.rs - Path Matching
src/core/paths.rs - ID Generation
src/core/ids.rs - Git Operations
src/core/git.rs - Command Output
src/core/format.rs
Other components
- AI Agents
Connections 39
- AI Agents → CLI Interface: invoke commands
README.md - CLI Interface → Join & Lifecycle: run join
README.md - CLI Interface → Plan & Tasks: initialize plan
README.md - CLI Interface → Task Board: manage tasks
README.md - CLI Interface → Path Claims: claim paths
README.md - CLI Interface → Messages & Wait: message and wait
README.md - CLI Interface → Status & Doctor: inspect status
README.md - CLI Interface → Gate & Finish: run gate and finish
README.md - CLI Interface → Commit & Sync: commit files
README.md - CLI Interface → Git Hooks: install hooks
README.md - Join & Lifecycle → Agent Context: resolve identity
src/cmds/lifecycle.rs - Join & Lifecycle → Swarm State: save agents
src/cmds/lifecycle.rs - Join & Lifecycle → Atomic Locking: serialize updates
src/cmds/lifecycle.rs - Plan & Tasks → Agent Context: use context
src/cmds/plan.rs - Plan & Tasks → Atomic Locking: serialize updates
src/cmds/plan.rs - Task Board → Path Claims: claim task paths
README.md - Task Board → Swarm State: read and write tasks
src/cmds/task.rs - Task Board → Atomic Locking: serialize updates
src/cmds/task.rs - Task Board → Path Matching: check path overlap
src/cmds/task.rs - Task Board → ID Generation: allocate task IDs
src/cmds/task.rs - Path Claims → Swarm State: read and write claims
src/cmds/claim.rs - Path Claims → Atomic Locking: serialize claims
src/cmds/claim.rs - Path Claims → Path Matching: check overlap
src/cmds/claim.rs - Messages & Wait → Swarm State: read messages
src/cmds/comm.rs - Messages & Wait → Atomic Locking: serialize updates
src/cmds/comm.rs - Gate & Finish → Swarm State: read swarm state
src/cmds/finish.rs - Gate & Finish → Atomic Locking: serialize updates
src/cmds/finish.rs - Gate & Finish → Git Operations: read Git revision
src/cmds/finish.rs - Gate & Finish → Messages & Wait: append human request
src/cmds/finish.rs - Commit & Sync → Git Operations: run Git operations
src/cmds/git_cmds.rs - Commit & Sync → Atomic Locking: serialize commits
src/cmds/git_cmds.rs - Commit & Sync → Path Matching: validate paths
src/cmds/git_cmds.rs - Git Hooks → Git Operations: inspect repository
src/cmds/hooks.rs - Agent Context → Swarm State: initialize store
src/core/context.rs - Agent Context → Atomic Locking: read time
src/core/context.rs - Task Board → Command Output: format results
src/cmds/task.rs - Path Claims → Command Output: format results
src/cmds/claim.rs - Messages & Wait → Command Output: format results
src/cmds/comm.rs - Gate & Finish → Command Output: format results
src/cmds/finish.rs