# DESIGN
System design document for CodeTree. Covers design principles, architecture decisions, data model, module boundaries, and rationale.
> For the product definition (what/who/why) see [`PRODUCT.md`](PRODUCT.md).
> For the implementation-level module map and data flow see [`ARCHITECTURE.md`](ARCHITECTURE.md).
> For the command/protocol contract see [`SPEC.md`](SPEC.md).
---
## Design Principles
### 1. Operation-Centric, Not Branch-Centric
The primary unit of work is an **operation** — a task with a description, file scope, lifecycle, and owner. Branches are storage implementation details. Agents think "fix the login bug," not "create branch `codetree_1700000000_fix_login_bug`."
**Implication:** Every command, MCP tool, and data structure is framed in terms of operations. The branch name is auto-generated and opaque.
### 2. Isolation by Default
Operations are **parallel by default** — `start` creates a branch ref without switching to it. The agent's working tree is not disrupted. This allows an orchestrator to spawn many operations without interleaving working-tree state.
**Implication:** `--checkout` is opt-in. Worktrees (`--worktree`) provide physical isolation when needed.
### 3. Agent Output Is Untrusted
Agent-produced code is isolated until validated and promoted. The system assumes agents may produce broken, redundant, or conflicting work.
**Implication:** Validation gates, file locking, code freezing, and candidate groups exist to enforce quality and prevent cross-agent interference.
### 4. Append-Only History, Explicit Rewrites
Commits are immutable. History is append-only. Rewriting (`undo`, `rebase`, `split`) is an explicit, logged operation — never silent.
**Implication:** `undo` pushes to a redo stack. `rebase` creates new commits rather than mutating old ones. The operation log (`ops.json`) records every structural change.
### 5. Content-Addressable Storage
Objects (blobs, trees, commits) are keyed by SHA-1 of their canonical representation. This is the same hashing scheme as Git, enabling a future one-way bridge (`codetree export` to Git).
**Implication:** Deduplication is automatic. Object integrity is verifiable. No dependency on Git libraries.
### 6. No Git Dependency
CodeTree is a complete VCS. It does not shell out to `git` or link against `libgit2`. All operations (commit, merge, diff, rebase, checkout) are implemented natively in Rust.
**Implication:** Smaller dependency tree. No subprocess overhead. Full control over semantics. The trade-off is that CodeTree must implement its own merge algorithm, diff engine, and rebase logic.
### 7. Agent-First API
Core CLI commands have an MCP twin that returns typed JSON. Agents drive CodeTree via JSON-RPC, never shell parsing.
**Implication:** The MCP layer operates at the same level as the CLI command layer — both call the `VcsManager`/`BranchManager` primitives. Output is structured, not text-scraped. A few CLI commands (`redo`, `split`, `smartlog`, `switch`/`next`/`prev`, `watch`, `resolve`, `worktree`, `agents`) do not yet have MCP twins — see `TODO.md`.
---
## Architecture Decisions
### ADR-1: Native VCS vs. Git Wrapper
**Decision:** Build a native VCS engine instead of wrapping Git.
**Rationale:** A Git wrapper would bolt agent concepts (ownership, locking, lifecycle, gates) on top as metadata. CodeTree makes them first-class in the data model. Ownership and locking live in the store, enforced at commit time. Rollback is a structured object-graph operation, not a fragile `git reset`. The operation lifecycle is part of history.
**Trade-off:** CodeTree must implement its own object store, merge algorithm, diff engine, and rebase logic. This is significant complexity, but it gives full control over semantics and eliminates the `git2` dependency.
### ADR-2: SHA-1 Object Hashing (Git-Compatible)
**Decision:** Use the same SHA-1 content-addressing scheme as Git (`"<type> <len>\0<content>"`).
**Rationale:** A future `codetree export` can map objects directly to a Git repository without re-hashing. Objects are stored in the same fan-out layout (`objects/<first-2-hex>/<remaining-38-hex>`).
**Trade-off:** SHA-1 has known collision weaknesses. For an AI-agent VCS with local-first operation, this is acceptable. A future version could migrate to SHA-256.
### ADR-3: File-Based State (No Daemon)
**Decision:** All state lives in `.codetree/` as files. No daemon, no service, no database.
**Rationale:** Offline-first. Works on any filesystem. No port conflicts. Simple backup (copy `.codetree/`). The trade-off is no concurrent multi-process writes — but agents typically interact through the MCP server, which is a single process.
### ADR-4: Operation Log for Undo/Redo
**Decision:** Maintain an explicit operation log (`ops.json`) with a redo stack, rather than using `git reflog` or similar.
**Rationale:** The log records structural operations (`Start`, `Save`, `Merge`, `Withdraw`) — not low-level ref changes. This makes undo/redo semantically meaningful: "undo the start of this operation" rather than "undo the last ref update."
### ADR-5: File Locking at Operation Level
**Decision:** Locks are per-file, per-operation. An operation claims files at `start` time; other operations cannot modify them until the owner finishes or withdraws.
**Rationale:** Prevents merge conflicts by design. Agents working on the same file are forced into a queue. The trade-off is reduced parallelism when files overlap — but this is the desired behavior for AI agents that would otherwise produce conflicting work.
### ADR-6: Candidate Groups for Solution Selection
**Decision:** Model multiple solutions to the same problem as a **candidate group** — a named set of operations. `promote` merges the winner and withdraws the rest.
**Rationale:** Agents may produce different solutions with different trade-offs. Rather than merging blindly or requiring human arbitration, CodeTree stores all candidates, allows evaluation, and promotes the best one. The losers are cleanly withdrawn.
### ADR-7: MCP as First-Class Interface
**Decision:** The MCP server is a first-class interface operating at the same layer as the CLI commands. It calls the same `VcsManager`/`BranchManager` primitives that `commands::*` uses.
**Rationale:** Agents should not parse CLI text. The MCP interface provides typed JSON for core operations. Caveat: the MCP layer currently re-implements some orchestration rather than calling `commands::*` directly, so CLI and MCP behavior can drift (e.g. MCP `start_op` lacks `--wait`). Consolidating on shared command functions is future work, as is adding MCP twins for the remaining CLI commands (`redo`, `split`, `smartlog`, `switch`/`next`/`prev`, `watch`, `resolve`, `worktree`, `agents`).
---
## Data Model Design
### Object Store
```
Blob → { content: Vec<u8> } → SHA-1
Tree → { entries: Vec<(mode, name, blob_hash)> } → SHA-1
Commit → { tree_hash, parents: Vec<hash>, author, message, timestamp } → SHA-1
```
Objects are immutable. Writing the same content always produces the same hash and is a no-op if the object already exists.
### Refs
```
refs/heads/<branch-name> → commit hash
HEAD → symbolic ref to branch name
```
Refs are mutable pointers. `HEAD` is a symbolic ref — it always points to a branch, never directly to a commit.
### Operation Metadata (branches.json)
```
BranchInfo {
name: String
created_at: u64
updated_at: u64
change_group: { description, files: Vec<String> }
status: Active | Merged | Archived
template: Option<String>
worktree: Option<PathBuf>
branchless: bool
depends_on: Vec<String>
last_commit: Option<String>
tags: Vec<String>
parent_branch: Option<String>
agent_id: Option<String>
}
```
This is the operation-centric metadata layer. It tracks what the operation is, who owns it, what files it touches, what it depends on, and its lifecycle status.
### Operation Log (ops.json)
```
Operation ::= Start { branch, timestamp, agent_id }
| Save { branch, message, timestamp }
| Merge { branch, into, timestamp }
| Withdraw { branch, timestamp }
ops: Vec<Operation> // undo history
redo_stack: Vec<Operation> // redo history
```
### Supporting State
| `locks.json` | File locks: `path → operation_name` |
| `frozen.json` | Frozen paths: read-only protection |
| `candidates.json` | Candidate groups: `group_name → [operation_names]` |
| `resolutions.json` | Conflict resolution cache: `(path, our_blob, their_blob) → resolved_blob` |
| `pending_resolution.json` | Active merge conflict metadata for `resolve` command |
| `config.toml` | User configuration (base branch, templates, validation, hooks) |
---
## Module Design
### Layering
```
┌─────────────────────────────────────────────┐
│ CLI (main.rs) MCP (mcp.rs) │ Entry points
├─────────────────────────────────────────────┤
│ commands/ │ Command logic
│ ├── mod.rs (shared utils + re-exports) │
│ ├── init.rs, operations.rs, save.rs │
│ ├── merge.rs, finish.rs, status.rs │
│ ├── undo.rs, rebase.rs, compare.rs │
│ ├── worktree.rs, freeze.rs, lock.rs │
│ └── agents.rs │
├─────────────────────────────────────────────┤
│ branch.rs ops.rs config.rs │ Metadata layer
│ lock.rs freeze.rs candidates.rs │
│ resolution.rs │
├─────────────────────────────────────────────┤
│ vcs/ │ VCS engine
│ ├── objects.rs refs.rs index.rs │
│ ├── repo.rs manager.rs (core) │
│ ├── merge.rs rewrite.rs │
│ └── query.rs worktree.rs │
├─────────────────────────────────────────────┤
│ error.rs lib.rs (utils) │ Foundation
└─────────────────────────────────────────────┘
```
### Module Boundaries
- **`vcs/`** — Pure VCS primitives. No knowledge of operations, agents, or locking. Knows about blobs, trees, commits, refs, and the index.
- **`branch.rs`** — Operation metadata. Knows about operations, their status, tags, dependencies, and parent relationships. Does not know about VCS internals.
- **`commands/`** — Orchestration layer. Calls `vcs/` for storage operations and `branch.rs` for metadata. Enforces policies (locking, freezing, validation).
- **`mcp.rs`** — MCP protocol layer. Calls `commands::*` directly. Translates between JSON-RPC and Rust types.
- **`lock.rs`, `freeze.rs`, `candidates.rs`** — Policy modules. Independent of each other and of `vcs/`. Enforced by the command layer.
### Command Module Split
The original `commands.rs` (2,692 lines) is split into 14 focused modules under `commands/`:
| `mod.rs` | Shared utilities (`load_config`, `run_hooks`, `staleness_label`, `format_ts`, `withdraw_single`) + `pub use` re-exports |
| `init.rs` | Repository initialization |
| `operations.rs` | Operation creation (`start`), navigation (`switch`, `next`, `prev`) |
| `save.rs` | Committing changes (`save`, `split`, `watch`) |
| `merge.rs` | Merging (`merge`, `resolve`) |
| `finish.rs` | Lifecycle completion (`finish`, `withdraw`) |
| `status.rs` | Inspection (`status`, `list`, `smartlog`, `whereami`) |
| `undo.rs` | History correction (`undo`, `redo`) |
| `rebase.rs` | Branch maintenance (`rebase`, `restack`) |
| `compare.rs` | Comparison and publishing (`compare`, `publish`) |
| `worktree.rs` | Linked worktree management |
| `freeze.rs` | Code freezing (`freeze`, `unfreeze`, `frozen`) |
| `lock.rs` | Lock management (`unlock`, `locks`) |
| `agents.rs` | Agent tracking and candidates (`agents`, `evaluate`, `promote`) |
All modules use `pub use` re-exports from `mod.rs`, so `crate::commands::*` and `codetree::commands::*` paths remain unchanged.
---
## Design Rationale
### Why Parallel by Default?
Human VCS workflows assume a single developer at a keyboard who switches branches to work. AI agents are spawned by orchestrators that may create 10 operations in parallel. If `start` checked out the new branch by default, the orchestrator's working tree would thrash. Parallel-by-default means `start` creates the branch ref and returns; the agent (or orchestrator) decides when to switch.
### Why File Locking Instead of Merge Conflict Resolution?
Merge conflicts require human arbitration in traditional VCS. AI agents cannot reliably resolve conflicts — they may pick the wrong side or produce broken merges. File locking prevents conflicts by design: if agent A is working on `auth.rs`, agent B cannot touch it. B either waits (`--wait` flag) or works on a different file. This trades parallelism for correctness.
### Why a Native VCS Instead of Git Metadata?
Adding agent concepts as a metadata layer on top of Git would mean:
- Locking is advisory (Git doesn't enforce it).
- Rollback is `git reset` (fragile, loses history).
- The operation lifecycle is external to the VCS (inconsistent state on crash).
- MCP tools would parse `git` CLI output (brittle).
A native VCS makes locking, freezing, validation, and lifecycle **enforced at the storage layer**. The trade-off is implementation complexity — but the result is a coherent system where the data model matches the product model.
### Why Not Use a Database?
CodeTree is offline-first and single-process (the MCP server). A database would add a dependency, require a daemon, and complicate backup. File-based state (JSON + content-addressable objects) is simpler, portable, and sufficient for the workload.
### Why SHA-1 Instead of SHA-256?
Git compatibility. A future `codetree export` can map objects directly to a Git repository. SHA-1's collision weakness is not a security concern for local-first operation. A migration to SHA-256 is possible in the future.
---
## Future Design Directions
- **Remote protocol** — Push/pull/clone for agent-to-agent and agent-to-human collaboration.
- **Git interop** — One-way bridge: `codetree import` from Git, `codetree export` to Git.
- **First-class conflicts** — Store conflict metadata in commits (like Jujutsu) instead of aborting.
- **Auto-snapshot** — Snapshot the working copy before every command, so agent crashes never lose work.
- **JSON output mode** — `--json` flag on every CLI command for machine-readable output without MCP.