How snowtema/drift works
1. Repository shape
- drift is a single Go binary that offers both a terminal TUI and a CLI.
- The architecture is intentionally local-first and file-based: project state lives in JSON files on disk, not in a server or database.
2. Top-level execution flow
- cmd/main.go is the entrypoint.
- It hands off to internal/commands/cli.go, which routes between:
- interactive TUI mode
- one-off CLI commands such as init, list, status, note, goal, scan, and open
3. Protocol layer as the core boundary
- internal/protocol/* is the most important architectural boundary.
- It defines the shared data model, config, and file I/O for the on-disk protocol:
- per-project .drift/project.json
- global ~/.drift/registry.json
- user config in ~/.drift/config.json
- This layer is what both the CLI and TUI consume, so the protocol is effectively the product contract.
4. Data model and persisted state
- The project record appears to hold metadata such as description, status, progress, tags, links, goals, and notes.
- The registry is the global index of tracked projects.
- The docs and schemas in docs/protocol.md and docs/schema/*.json formalize this contract for compatibility with other tools.
5. TUI subsystem
- internal/ui/* implements the interactive terminal interface.
- The package structure suggests a classic model/update/view split:
- model.go for UI state
- update.go for handling input and state transitions
- view.go for rendering
- styles.go and helpers.go for presentation and utility code
- The TUI is the user-facing orchestration layer over the protocol.
6. List/detail workspace
- The TUI centers on a dual-panel project browser:
- a list view for navigating tracked projects
- a detail view for editing goals, notes, descriptions, and status
- User actions in the TUI write back to the same .drift files used by the CLI, so the interface is just another client of the protocol.
7. Scanning and project discovery
- internal/ui/scan.go supports directory browsing and batch discovery/init from inside the TUI.
- The README also exposes drift scan in the CLI, so scanning is a shared capability across both interfaces.
- This subsystem bridges the filesystem and the registry by finding candidate project folders and optionally initializing them.
8. Configuration and personalization
- User preferences such as theme, tree/flat view, sort order, and banner state are persisted in ~/.drift/config.json.
- This is separate from project data, which keeps UI preferences distinct from the tracked-project protocol.
9. Claude Code integration boundary
- The repo includes explicit integration with Claude Code:
- launching Claude from the TUI
- writing a CLAUDE.md section during init for auto-sync behavior
- a reusable skill under skills/drift/SKILL.md
- Architecturally, this is an external-agent integration layer that sits beside the core tracker, not inside it.
10. Documentation and compatibility assets
- docs/protocol.md, the JSON schemas, and the .ajtbd notes define and analyze the data model and workflow.
- These files matter because the project is designed to be open protocol rather than just one app; other tools can interoperate by reading/writing the same JSON.
11. Release and packaging
- .goreleaser.yaml and .github/workflows/release.yaml indicate the binary is built and published as a standalone release artifact.
- This supports the “single binary, zero dependencies” distribution model described in the README.
12. Mental model for an architecture diagram
- A good diagram would show:
- User interacting with either CLI or TUI
- both calling into the protocol layer
- which reads/writes project JSON, registry JSON, and user config
- plus a side integration to Claude Code
- with scanning/discovery feeding new projects into the same persistent store
Main entry points: cli.go CLI router · io.go File I/O · types.go Data model · model.go UI state
Components 16
Runtime
Entry and command routing
- main · Binary entrypoint
cmd/main.go - CLI router · Dispatches CLI and TUI modes
internal/commands/cli.go
Protocol
Shared data model and file I/O
- Data model · Project, registry, and config types
internal/protocol/types.go - File I/O · Reads and writes JSON protocol files
internal/protocol/io.go - Config · User configuration and preferences
internal/protocol/config.go
TUI
Interactive terminal interface
- UI state · List and detail workspace state
internal/ui/model.go - Update loop · Handles input and state transitions
internal/ui/update.go - Renderer · Renders the terminal interface
internal/ui/view.go - Styles · Presentation and theming
internal/ui/styles.go - Helpers · Shared UI utilities
internal/ui/helpers.go
Integration
External agent and discovery flows
- Scanner · Project discovery and init from directories
internal/ui/scan.go - Claude Code · Launch and sync integration boundary
skills/drift/SKILL.md - Release · Build and publish workflow
.goreleaser.yaml
Docs
Compatibility and schema assets
- Project schema · Project protocol contract
docs/schema/project.schema.json - Registry schema · Global tracked-project index contract
docs/schema/registry.schema.json - Protocol doc · Human-readable protocol definition
docs/protocol.md
Connections 19
- main → CLI router: starts · Entrypoint hands off to command routing
- CLI router → Data model: uses · Commands operate on shared protocol data
- CLI router → File I/O: reads/writes · CLI mutates on-disk project state
- CLI router → Config: loads · CLI consumes user preferences
- CLI router → UI state: launches · Interactive mode enters the TUI workspace
- UI state → Data model: binds · UI state mirrors protocol entities
- Update loop → UI state: mutates · Input drives state transitions
- Renderer → UI state: renders · View reads current UI state
- Renderer → Styles: uses · Renderer applies styling
- Update loop → File I/O: persists · Edits write back to JSON files
- Scanner → File I/O: discovers · Finds and initializes tracked projects
- Scanner → Data model: indexes · Discovery feeds project records
- File I/O → Data model: serializes · Storage layer encodes protocol objects
- Config → Data model: separates · User prefs are distinct from project records
- Protocol doc → Project schema: formalizes · Documentation aligns with schema contracts
- Protocol doc → Registry schema: formalizes · Documentation aligns with registry contract
- Claude Code → File I/O: syncs · External agent integration uses the same files
- Claude Code → CLI router: extends · CLI and TUI expose Claude Code workflows
- Release → main: packages · Builds the standalone binary