Contributor guide

How taskstream is put together and how to work on it — for anyone building, extending, or reviewing the code.

Here to use the app?

This guide is about the code. Installing, using, and configuring taskstream is the User guide.

What's in this guide

Development setup
Get a working shell: Nix and direnv, the dev-shell commands, and the web packages.
Architecture
The map — crates, persistence, the desktop app, and the spec index.
Data model
The storage layer: what a task is, how it is ordered, who owns a row, and how repeats become tasks.
Workflow engine
Recipes, runs, and the coding pipeline — including branches, worktrees, and the loopback tool server.
Agent runtime
The protocol the desktop pane speaks, the agent’s tools and sub-agents, and the vendored patches.
Integrations
The area you are most likely to touch: sync, the provider layer, MCP, and the agent protocol.
Contributing
Which checks must pass, and the Rust and web conventions to follow.
License
AGPL-3.0 in practice, and what that means for a change you want to upstream.

Reading order

Nothing here is long, and the order matters more than usual: the setup page is what makes the rest actionable, and the architecture page is the map you will keep coming back to.

Development setup — Get a working shell: Nix and direnv, the dev-shell commands, and the web packages.
Architecture — The map — crates, persistence, the desktop app, and the spec index.
Data model — The storage layer: what a task is, how it is ordered, who owns a row, and how repeats become tasks.
Workflow engine — Recipes, runs, and the coding pipeline — including branches, worktrees, and the loopback tool server.
Agent runtime — The protocol the desktop pane speaks, the agent’s tools and sub-agents, and the vendored patches.
Integrations — The area you are most likely to touch: sync, the provider layer, MCP, and the agent protocol.
Contributing — Which checks must pass, and the Rust and web conventions to follow.
License — AGPL-3.0 in practice, and what that means for a change you want to upstream.

Where the rules live

Conventions are written down rather than implied, in four places:

AGENTS.md — The Rust coding guidelines: error handling, naming, file layout, GPUI timers.
docs/spec/*.md — One spec per non-trivial feature, recording the decisions behind it.
libs/web-design-system/DESIGN.md — Web tokens, layers, component conventions, and the class-parity rule.
README.md — Entry points and the quickest path to each part of the repository.

The repository is also spec-driven: behavior changes get a file in docs/spec/ first, and that file records the interview decisions behind the design. Architecture lists every spec with its status.

Two workspaces

The repository holds two unrelated build worlds, and it helps to know which one you are in:

The Cargo workspace — apps/taskstream-desktop, apps/agent-cli, and the crates under libs/. Everything the desktop app and the agent do lives here.
The pnpm workspace — libs/web-design-system, demos/design-system-showcase, and this site. Three separate Astro/Panda projects sharing one design-system preset.

The two are deliberately decoupled: the desktop palette lives in apps/taskstream-desktop/src/theme.rs and is not generated from the web tokens. What the web packages do share is class-generation settings — if they drift, the design system's components render unstyled with no error. Development setup has the detail.

The repository lives at github.com/lofi-tools/todo-lofi.