Architecture

A Cargo workspace for the app and its libraries, plus a pnpm workspace for the web surfaces. Here is how the pieces relate.

Workspace layout

taskstream

taskstream/
├── apps/
│   ├── taskstream-desktop/                # GPUI desktop application
│   └── agent-cli/             # terminal agent + ACP server
├── libs/
│   ├── storage/               # SQLite persistence, migrations, sync tables
│   ├── acp-client/            # Agent Client Protocol client
│   ├── ai_providers/          # LLM provider abstraction
│   ├── gpui-tokio/            # GPUI <-> Tokio bridge
│   ├── report_proc/           # proc-macro crate
│   ├── web-design-system/     # Panda/Solid design system (not a crate)
│   └── ...                    # CRDT experiments (dson, op_crdt)
├── demos/
│   └── design-system-showcase # component gallery + page replicas
├── apps/docs-web/             # this documentation site
├── patched/                   # vendored upstream forks
├── docs/                      # specs, agent skills, images
└── flake.nix                  # devShell: Rust, cargo-watch, Node, pnpm

Cargo.toml declares members as apps/*, libs/*, anddemos/*, and explicitly excludes the three JavaScript packages so cargo check --workspace never walks their trees.

The desktop app

apps/taskstream-desktop is GPUI all the way down: one window, a handful of panes, and entities that hold state. Async work (sync, agent sessions, file reads) is pushed onto Tokio through libs/gpui-tokio and applied back on the UI thread.

Module	Responsibility
`main.rs`	Application entry point and window setup.
`store.rs`	The app-level store that entities read and write.
`projects.rs`	Project and area tree state.
`theme.rs`	The desktop palette. Deliberately independent of the web design system.
`ui_parts/`	The panes: task list and row, task details, agent pane, mini-apps, integrations, automations, pickers, settings, notifications, navbar.
`coding_git.rs, coding_mcp.rs`	Git and MCP support for coding workflow runs.
`components/`	Reusable widgets: calendar, checkbox, date/time picker, mini task list, tag chip.

Two themes, on purpose

apps/taskstream-desktop/src/theme.rs is the desktop palette. It is intentionally not generated from the web design system's tokens — the two surfaces share no code, and the design system spec lists that as a non-goal.

The agent side

There is one agent implementation and two front ends. apps/agent-cli is a terminal TUI that also speaks the Agent Client Protocol over stdio; libs/acp-client is the client that the desktop app's agent pane uses to talk to that same protocol. Provider selection, model fallback combos, MCP servers, hooks, and sub-agents all live on the CLI side and are shared.

Crate	Role	What it contains
`apps/taskstream-desktop`	The desktop application	GPUI views and app state: task lists and details, the agent pane, mini-apps, sync panes, and settings.
`apps/agent-cli`	The terminal agent	A full-screen TUI, a provider/model registry with fallback combos, sub-agents, and an ACP server over stdio.
`libs/storage`	Persistence	The SQLite data model and migrations: tasks, tags and tag settings, repeats, trips, workflows, Todoist, GitHub, and managed apps.
`libs/acp-client`	Agent plumbing	Launches agent processes, owns sessions and the transcript model, and provides the file-system and terminal capabilities an agent session needs.
`libs/ai_providers`	Model access	OpenAI-compatible provider implementations on top of the cersei agent library, including an OAuth-backed provider.
`libs/gpui-tokio`	Runtime bridge	Runs Tokio futures from GPUI entities so async work never blocks the UI thread.

Persistence

libs/storage owns the database. It is SQLite, accessed through the toasty ORM, and it carries its own migration binary:

task.rs, tag.rs, tag_settings.rs — the core task model.
repeat.rs — recurring rules.
workflow.rs — workflow definitions and run state.
todoist.rs, github.rs, external.rs — sync mappings for outside systems.
managed.rs, link.rs, trip.rs — the models behind mini-apps, links, and trips.
migrations.rs and src/bin/ — schema migrations, driven by the mig command.

The remaining libs/* crates are narrower: ai_providers andgpui-tokio are infrastructure, report_proc andderive_entity_id are macros, and dson_freeform_task,dson_typed_task, and op_crdt are CRDT experiments for conflict-free task data.

Web surfaces

Two web apps share one design system, and none of them touch the Rust workspace:

libs/web-design-system — tokens, a Panda preset, Ark UI headless primitives, and styled Solid components with .astro wrappers.
demos/design-system-showcase — the component gallery and the page shapes the design system is built from.
apps/docs-web — this site. It consumes the design system's preset and the marketing docs components rather than restyling them.

See the design system's DESIGN.md for the token and layering rules, andContributing for the checks that keep them honest.

Tech stack

What the app and this site are built with, and what each piece is there for. The landing page deliberately says none of this: it is here for the people who are going to work on the code.

Piece	What it is	Why it is here
GPUI	The GPU-accelerated UI framework, from the ecosystem around the Zed editor.	One native window, drawn on the GPU, with no web runtime inside the app.
Rust	The language every crate in the workspace is written in.	A single binary per platform, and nothing to install first.
SQLite	The local database, reached through the toasty ORM in libs/storage.	The task list is a file on disk the app can read with no network.
MCP and ACP	Model Context Protocol for tools, Agent Client Protocol for the agent session.	The agent is a separate process the app talks to over a protocol, rather than a model client embedded in the UI.
Astro	The static-site framework behind this documentation site and the design-system showcase.	The docs are static HTML built from the same components the marketing pages use.
Panda CSS and Ark UI	The styling engine and the headless primitives behind the web design system.	One token set and one preset, shared by the docs site and the showcase.

Specs

Non-trivial features are specified before they are built. Each spec records the decisions taken during the interview that produced it, so the file is the rationale as well as the design.

Spec	Status	Covers
`workflow-engine-spec.md`	Draft v1	Workflow engine data model in libs/storage, minimal UI contract.
`workflow-simplification-spec.md`	Draft v1	The v2 workflow model; supersedes the v1 data model.
`coding-workflow-runs-spec.md`	Implemented	AI-assisted feature development runs: phases, state, and review.
`coding-workflow-subtasks-spec.md`	Proposed	Subtasks inside a run and coverage of the spec they implement.
`todoist-sync-spec.md`	Draft v1	Todoist import plus immediate push of title/description/done deltas.
`github-integration-spec.md`	Draft v1	GitHub issues/projects sync and a git-backed coding workflow.
`acp-client-and-agent-panel-spec.md`	Draft v1	The ACP client crate and the taskstream-desktop agent panel that drives it.
`todo2-agent-pane-ui-spec.md`	Draft v1	The agent pane UI: layout, states, and interactions.
`agent-cli-interview-feature-spec.md`	Draft v1	The /interview command that turns a request into a spec.
`todo2-managed-apps-spec.md`	Draft v2	Managed tags, sections, and tasks — the model behind mini-apps.
`todo2-nested-projects-spec.md`	Draft v1	Nesting project directories under tags.
`symphony.md`	Draft v1	A language-agnostic service specification.
`web-design-system-spec.md`	Implemented v1	The web design system and its showcase.
`homepage-refresh-spec.md`	Draft v1	The landing-page rewrite, the /roadmap page, and the terminology pass.

All specs live in docs/spec/ at the repository root.