# itznan/naantree architecture

> Architecture diagram of the GitHub repository itznan/naantree, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itznan/naantree
- Repository: https://github.com/itznan/naantree

## Overview

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: [`src/cli.rs`](https://github.com/itznan/naantree/blob/main/src/cli.rs) (CLI Interface), [`src/cmds/task.rs`](https://github.com/itznan/naantree/blob/main/src/cmds/task.rs) (Task Board), [`src/core/lock.rs`](https://github.com/itznan/naantree/blob/main/src/core/lock.rs) (Atomic Locking), [`src/cmds/finish.rs`](https://github.com/itznan/naantree/blob/main/src/cmds/finish.rs) (Gate & Finish)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Swarm Workflow"]
  node_cli["CLI Interface<br/>[cli.rs]"]
  node_lifecycle["Join &amp; Lifecycle<br/>[lifecycle.rs]"]
  node_planning["Plan &amp; Tasks<br/>[plan.rs]"]
  node_task_board["Task Board<br/>[task.rs]"]
  node_path_claims["Path Claims<br/>[claim.rs]"]
  node_gate_finish["Gate &amp; Finish<br/>[finish.rs]"]
end

subgraph group_coordination["Coordination Features"]
  node_communication["Messages &amp; Wait<br/>[comm.rs]"]
  node_status["Status &amp; Doctor<br/>[status.rs]"]
end

subgraph group_git_safety["Git Safety"]
  node_git_commands["Commit &amp; Sync<br/>[git_cmds.rs]"]
  node_hooks["Git Hooks<br/>[hooks.rs]"]
end

subgraph group_runtime["Runtime Core"]
  node_context["Agent Context<br/>[context.rs]"]
  node_state_store[("Swarm State<br/>[store.rs]")]
  node_locking["Atomic Locking<br/>[lock.rs]"]
  node_path_matching["Path Matching<br/>[paths.rs]"]
  node_identifiers["ID Generation<br/>[ids.rs]"]
  node_git_runtime["Git Operations<br/>[git.rs]"]
  node_output["Command Output<br/>[format.rs]"]
end

node_agents(("AI Agents"))

node_agents -->|"invoke commands"| node_cli
node_cli -->|"run join"| node_lifecycle
node_cli -->|"initialize plan"| node_planning
node_cli -->|"manage tasks"| node_task_board
node_cli -->|"claim paths"| node_path_claims
node_cli -->|"message and wait"| node_communication
node_cli -->|"inspect status"| node_status
node_cli -->|"run gate and finish"| node_gate_finish
node_cli -->|"commit files"| node_git_commands
node_cli -->|"install hooks"| node_hooks
node_lifecycle -->|"resolve identity"| node_context
node_lifecycle -->|"save agents"| node_state_store
node_lifecycle -->|"serialize updates"| node_locking
node_planning -->|"use context"| node_context
node_planning -->|"serialize updates"| node_locking
node_task_board -->|"claim task paths"| node_path_claims
node_task_board -->|"read and write tasks"| node_state_store
node_task_board -->|"serialize updates"| node_locking
node_task_board -->|"check path overlap"| node_path_matching
node_task_board -->|"allocate task IDs"| node_identifiers
node_path_claims -->|"read and write claims"| node_state_store
node_path_claims -->|"serialize claims"| node_locking
node_path_claims -->|"check overlap"| node_path_matching
node_communication -->|"read messages"| node_state_store
node_communication -->|"serialize updates"| node_locking
node_gate_finish -->|"read swarm state"| node_state_store
node_gate_finish -->|"serialize updates"| node_locking
node_gate_finish -->|"read Git revision"| node_git_runtime
node_gate_finish -->|"append human request"| node_communication
node_git_commands -->|"run Git operations"| node_git_runtime
node_git_commands -->|"serialize commits"| node_locking
node_git_commands -->|"validate paths"| node_path_matching
node_hooks -->|"inspect repository"| node_git_runtime
node_context -->|"initialize store"| node_state_store
node_context -->|"read time"| node_locking
node_task_board -->|"format results"| node_output
node_path_claims -->|"format results"| node_output
node_communication -->|"format results"| node_output
node_gate_finish -->|"format results"| node_output

click node_cli "https://github.com/itznan/naantree/blob/main/src/cli.rs"
click node_lifecycle "https://github.com/itznan/naantree/blob/main/src/cmds/lifecycle.rs"
click node_planning "https://github.com/itznan/naantree/blob/main/src/cmds/plan.rs"
click node_task_board "https://github.com/itznan/naantree/blob/main/src/cmds/task.rs"
click node_path_claims "https://github.com/itznan/naantree/blob/main/src/cmds/claim.rs"
click node_communication "https://github.com/itznan/naantree/blob/main/src/cmds/comm.rs"
click node_status "https://github.com/itznan/naantree/blob/main/src/cmds/status.rs"
click node_gate_finish "https://github.com/itznan/naantree/blob/main/src/cmds/finish.rs"
click node_git_commands "https://github.com/itznan/naantree/blob/main/src/cmds/git_cmds.rs"
click node_hooks "https://github.com/itznan/naantree/blob/main/src/cmds/hooks.rs"
click node_context "https://github.com/itznan/naantree/blob/main/src/core/context.rs"
click node_state_store "https://github.com/itznan/naantree/blob/main/src/core/store.rs"
click node_locking "https://github.com/itznan/naantree/blob/main/src/core/lock.rs"
click node_path_matching "https://github.com/itznan/naantree/blob/main/src/core/paths.rs"
click node_identifiers "https://github.com/itznan/naantree/blob/main/src/core/ids.rs"
click node_git_runtime "https://github.com/itznan/naantree/blob/main/src/core/git.rs"
click node_output "https://github.com/itznan/naantree/blob/main/src/core/format.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_lifecycle,node_planning,node_task_board,node_path_claims,node_gate_finish toneBlue
class node_communication,node_status toneAmber
class node_git_commands,node_hooks toneMint
class node_context,node_state_store,node_locking,node_path_matching,node_identifiers,node_git_runtime,node_output toneRose
class node_agents toneIndigo
```

## Components

### Swarm Workflow

- [CLI Interface](https://github.com/itznan/naantree/blob/main/src/cli.rs): `src/cli.rs`
- [Join & Lifecycle](https://github.com/itznan/naantree/blob/main/src/cmds/lifecycle.rs): `src/cmds/lifecycle.rs`
- [Plan & Tasks](https://github.com/itznan/naantree/blob/main/src/cmds/plan.rs): `src/cmds/plan.rs`
- [Task Board](https://github.com/itznan/naantree/blob/main/src/cmds/task.rs): `src/cmds/task.rs`
- [Path Claims](https://github.com/itznan/naantree/blob/main/src/cmds/claim.rs): `src/cmds/claim.rs`
- [Gate & Finish](https://github.com/itznan/naantree/blob/main/src/cmds/finish.rs): `src/cmds/finish.rs`

### Coordination Features

- [Messages & Wait](https://github.com/itznan/naantree/blob/main/src/cmds/comm.rs): `src/cmds/comm.rs`
- [Status & Doctor](https://github.com/itznan/naantree/blob/main/src/cmds/status.rs): `src/cmds/status.rs`

### Git Safety

- [Commit & Sync](https://github.com/itznan/naantree/blob/main/src/cmds/git_cmds.rs): `src/cmds/git_cmds.rs`
- [Git Hooks](https://github.com/itznan/naantree/blob/main/src/cmds/hooks.rs): `src/cmds/hooks.rs`

### Runtime Core

- [Agent Context](https://github.com/itznan/naantree/blob/main/src/core/context.rs): `src/core/context.rs`
- [Swarm State](https://github.com/itznan/naantree/blob/main/src/core/store.rs): `src/core/store.rs`
- [Atomic Locking](https://github.com/itznan/naantree/blob/main/src/core/lock.rs): `src/core/lock.rs`
- [Path Matching](https://github.com/itznan/naantree/blob/main/src/core/paths.rs): `src/core/paths.rs`
- [ID Generation](https://github.com/itznan/naantree/blob/main/src/core/ids.rs): `src/core/ids.rs`
- [Git Operations](https://github.com/itznan/naantree/blob/main/src/core/git.rs): `src/core/git.rs`
- [Command Output](https://github.com/itznan/naantree/blob/main/src/core/format.rs): `src/core/format.rs`

### Other components

- **AI Agents**

## Connections

- AI Agents → CLI Interface: invoke commands (evidence: `README.md`)
- CLI Interface → Join & Lifecycle: run join (evidence: `README.md`)
- CLI Interface → Plan & Tasks: initialize plan (evidence: `README.md`)
- CLI Interface → Task Board: manage tasks (evidence: `README.md`)
- CLI Interface → Path Claims: claim paths (evidence: `README.md`)
- CLI Interface → Messages & Wait: message and wait (evidence: `README.md`)
- CLI Interface → Status & Doctor: inspect status (evidence: `README.md`)
- CLI Interface → Gate & Finish: run gate and finish (evidence: `README.md`)
- CLI Interface → Commit & Sync: commit files (evidence: `README.md`)
- CLI Interface → Git Hooks: install hooks (evidence: `README.md`)
- Join & Lifecycle → Agent Context: resolve identity (evidence: `src/cmds/lifecycle.rs`)
- Join & Lifecycle → Swarm State: save agents (evidence: `src/cmds/lifecycle.rs`)
- Join & Lifecycle → Atomic Locking: serialize updates (evidence: `src/cmds/lifecycle.rs`)
- Plan & Tasks → Agent Context: use context (evidence: `src/cmds/plan.rs`)
- Plan & Tasks → Atomic Locking: serialize updates (evidence: `src/cmds/plan.rs`)
- Task Board → Path Claims: claim task paths (evidence: `README.md`)
- Task Board → Swarm State: read and write tasks (evidence: `src/cmds/task.rs`)
- Task Board → Atomic Locking: serialize updates (evidence: `src/cmds/task.rs`)
- Task Board → Path Matching: check path overlap (evidence: `src/cmds/task.rs`)
- Task Board → ID Generation: allocate task IDs (evidence: `src/cmds/task.rs`)
- Path Claims → Swarm State: read and write claims (evidence: `src/cmds/claim.rs`)
- Path Claims → Atomic Locking: serialize claims (evidence: `src/cmds/claim.rs`)
- Path Claims → Path Matching: check overlap (evidence: `src/cmds/claim.rs`)
- Messages & Wait → Swarm State: read messages (evidence: `src/cmds/comm.rs`)
- Messages & Wait → Atomic Locking: serialize updates (evidence: `src/cmds/comm.rs`)
- Gate & Finish → Swarm State: read swarm state (evidence: `src/cmds/finish.rs`)
- Gate & Finish → Atomic Locking: serialize updates (evidence: `src/cmds/finish.rs`)
- Gate & Finish → Git Operations: read Git revision (evidence: `src/cmds/finish.rs`)
- Gate & Finish → Messages & Wait: append human request (evidence: `src/cmds/finish.rs`)
- Commit & Sync → Git Operations: run Git operations (evidence: `src/cmds/git_cmds.rs`)
- Commit & Sync → Atomic Locking: serialize commits (evidence: `src/cmds/git_cmds.rs`)
- Commit & Sync → Path Matching: validate paths (evidence: `src/cmds/git_cmds.rs`)
- Git Hooks → Git Operations: inspect repository (evidence: `src/cmds/hooks.rs`)
- Agent Context → Swarm State: initialize store (evidence: `src/core/context.rs`)
- Agent Context → Atomic Locking: read time (evidence: `src/core/context.rs`)
- Task Board → Command Output: format results (evidence: `src/cmds/task.rs`)
- Path Claims → Command Output: format results (evidence: `src/cmds/claim.rs`)
- Messages & Wait → Command Output: format results (evidence: `src/cmds/comm.rs`)
- Gate & Finish → Command Output: format results (evidence: `src/cmds/finish.rs`)
