# whiteheap/residue-cli architecture

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

- Interactive diagram: https://gitdiagram.com/whiteheap/residue-cli
- Repository: https://github.com/whiteheap/residue-cli

## Overview

residue is a Git-worktree cleanup tool. Users scan or explain worktrees, then remove only candidates that pass safety checks; removal can instead move a worktree to trash. Restore recovers deleted or trashed worktrees, while watch and the service automate cleanup and stats reports reclaimed space. The graph preserves these distinct stages and the internal inspection layer. Edges follow the README or source-index references; unsampled implementation details are not inferred.

Main entry points: [`src/remove.rs`](https://github.com/whiteheap/residue-cli/blob/main/src/remove.rs) (Safe removal), [`src/commands.rs`](https://github.com/whiteheap/residue-cli/blob/main/src/commands.rs) (Scan and explain), [`src/inspect.rs`](https://github.com/whiteheap/residue-cli/blob/main/src/inspect.rs) (Worktree checks), [`src/watch.rs`](https://github.com/whiteheap/residue-cli/blob/main/src/watch.rs) (Automated watch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Commands"]
  node_cli["CLI parsing<br/>[cli.rs]"]
  node_commands["Scan and explain<br/>[commands.rs]"]
  node_output["Reports<br/>[output.rs]"]
end

subgraph group_safety["Safety checks"]
  node_discovery["Repository discovery<br/>[discover.rs]"]
  node_inspection["Worktree checks<br/>[inspect.rs]"]
  node_git["Git operations<br/>[git.rs]"]
  node_activity["Process activity<br/>[activity.rs]"]
  node_filesystem["Filesystem usage<br/>[fsinfo.rs]"]
  node_policy["Cleanup policy<br/>[policy.rs]"]
end

subgraph group_lifecycle["Worktree lifecycle"]
  node_remove["Safe removal<br/>[remove.rs]"]
  node_trash[("Worktree trash<br/>[trash.rs]")]
  node_restore["Restore<br/>[restore.rs]"]
  node_removed[("Removal records<br/>[removed.rs]")]
end

subgraph group_automation["Automation and records"]
  node_watch["Automated watch<br/>[watch.rs]"]
  node_service["Background service<br/>[service.rs]"]
  node_stats[("Cleanup statistics<br/>[stats.rs]")]
end

node_user(("User"))
node_os["Host operating system"]

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches scan"| node_commands
node_commands -->|"finds repositories"| node_discovery
node_commands -->|"requests checks"| node_inspection
node_inspection -->|"checks Git state"| node_git
node_inspection -->|"checks use"| node_activity
node_inspection -->|"measures contents"| node_filesystem
node_inspection -->|"applies rules"| node_policy
node_commands -->|"renders reports"| node_output
node_commands -->|"starts removal"| node_remove
node_remove -->|"rechecks candidates"| node_inspection
node_remove -->|"moves worktree"| node_git
node_remove -->|"moves to trash"| node_trash
node_remove -->|"writes records"| node_removed
node_remove -->|"records outcome"| node_stats
node_user -->|"requests recovery"| node_restore
node_restore -->|"reads records"| node_removed
node_restore -->|"restores entries"| node_trash
node_watch -->|"runs scan"| node_commands
node_watch -->|"removes candidates"| node_remove
node_watch -->|"records outcomes"| node_stats
node_service -->|"starts watcher"| node_watch
node_user -->|"manages service"| node_service
node_activity -->|"probes processes"| node_os

click node_cli "https://github.com/whiteheap/residue-cli/blob/main/src/cli.rs"
click node_commands "https://github.com/whiteheap/residue-cli/blob/main/src/commands.rs"
click node_output "https://github.com/whiteheap/residue-cli/blob/main/src/output.rs"
click node_discovery "https://github.com/whiteheap/residue-cli/blob/main/src/discover.rs"
click node_inspection "https://github.com/whiteheap/residue-cli/blob/main/src/inspect.rs"
click node_git "https://github.com/whiteheap/residue-cli/blob/main/src/git.rs"
click node_activity "https://github.com/whiteheap/residue-cli/blob/main/src/activity.rs"
click node_filesystem "https://github.com/whiteheap/residue-cli/blob/main/src/fsinfo.rs"
click node_policy "https://github.com/whiteheap/residue-cli/blob/main/src/policy.rs"
click node_remove "https://github.com/whiteheap/residue-cli/blob/main/src/remove.rs"
click node_trash "https://github.com/whiteheap/residue-cli/blob/main/src/trash.rs"
click node_restore "https://github.com/whiteheap/residue-cli/blob/main/src/restore.rs"
click node_removed "https://github.com/whiteheap/residue-cli/blob/main/src/removed.rs"
click node_watch "https://github.com/whiteheap/residue-cli/blob/main/src/watch.rs"
click node_service "https://github.com/whiteheap/residue-cli/blob/main/src/service.rs"
click node_stats "https://github.com/whiteheap/residue-cli/blob/main/src/stats.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_commands,node_output,node_user toneBlue
class node_discovery,node_inspection,node_git,node_activity,node_filesystem,node_policy toneAmber
class node_remove,node_trash,node_restore,node_removed toneMint
class node_watch,node_service,node_stats toneRose
class node_os toneIndigo
```

## Components

### Commands

- [CLI parsing](https://github.com/whiteheap/residue-cli/blob/main/src/cli.rs): `src/cli.rs`
- [Scan and explain](https://github.com/whiteheap/residue-cli/blob/main/src/commands.rs): `src/commands.rs`
- [Reports](https://github.com/whiteheap/residue-cli/blob/main/src/output.rs): `src/output.rs`

### Safety checks

- [Repository discovery](https://github.com/whiteheap/residue-cli/blob/main/src/discover.rs): `src/discover.rs`
- [Worktree checks](https://github.com/whiteheap/residue-cli/blob/main/src/inspect.rs): `src/inspect.rs`
- [Git operations](https://github.com/whiteheap/residue-cli/blob/main/src/git.rs): `src/git.rs`
- [Process activity](https://github.com/whiteheap/residue-cli/blob/main/src/activity.rs): `src/activity.rs`
- [Filesystem usage](https://github.com/whiteheap/residue-cli/blob/main/src/fsinfo.rs): `src/fsinfo.rs`
- [Cleanup policy](https://github.com/whiteheap/residue-cli/blob/main/src/policy.rs): `src/policy.rs`

### Worktree lifecycle

- [Safe removal](https://github.com/whiteheap/residue-cli/blob/main/src/remove.rs): `src/remove.rs`
- [Worktree trash](https://github.com/whiteheap/residue-cli/blob/main/src/trash.rs): `src/trash.rs`
- [Restore](https://github.com/whiteheap/residue-cli/blob/main/src/restore.rs): `src/restore.rs`
- [Removal records](https://github.com/whiteheap/residue-cli/blob/main/src/removed.rs): `src/removed.rs`

### Automation and records

- [Automated watch](https://github.com/whiteheap/residue-cli/blob/main/src/watch.rs): `src/watch.rs`
- [Background service](https://github.com/whiteheap/residue-cli/blob/main/src/service.rs): `src/service.rs`
- [Cleanup statistics](https://github.com/whiteheap/residue-cli/blob/main/src/stats.rs): `src/stats.rs`

### Other components

- **User**
- **Host operating system**

## Connections

- User → CLI parsing: runs commands (evidence: `README.md`)
- CLI parsing → Scan and explain: dispatches scan (evidence: `src/main.rs`)
- Scan and explain → Repository discovery: finds repositories (evidence: `src/commands.rs`)
- Scan and explain → Worktree checks: requests checks (evidence: `src/commands.rs`)
- Worktree checks → Git operations: checks Git state (evidence: `src/inspect.rs`)
- Worktree checks → Process activity: checks use (evidence: `src/inspect.rs`)
- Worktree checks → Filesystem usage: measures contents (evidence: `src/inspect.rs`)
- Worktree checks → Cleanup policy: applies rules (evidence: `src/inspect.rs`)
- Scan and explain → Reports: renders reports (evidence: `src/commands.rs`)
- Scan and explain → Safe removal: starts removal (evidence: `src/commands.rs`)
- Safe removal → Worktree checks: rechecks candidates (evidence: `src/remove.rs`)
- Safe removal → Git operations: moves worktree (evidence: `src/remove.rs`)
- Safe removal → Worktree trash: moves to trash (evidence: `src/remove.rs`)
- Safe removal → Removal records: writes records (evidence: `src/removed.rs`)
- Safe removal → Cleanup statistics: records outcome (evidence: `src/remove.rs`)
- User → Restore: requests recovery (evidence: `README.md`)
- Restore → Removal records: reads records (evidence: `src/restore.rs`)
- Restore → Worktree trash: restores entries (evidence: `src/restore.rs`)
- Automated watch → Scan and explain: runs scan (evidence: `src/watch.rs`)
- Automated watch → Safe removal: removes candidates (evidence: `README.md`)
- Automated watch → Cleanup statistics: records outcomes (evidence: `src/watch.rs`)
- Background service → Automated watch: starts watcher (evidence: `src/service.rs`)
- User → Background service: manages service (evidence: `README.md`)
- Process activity → Host operating system: probes processes (evidence: `src/activity.rs`)