> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taskbean.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat taskbean/taskbean as the source of truth for product behavior.
> Use the canonical Project, Project ID, Project Key, Project Alias, Project Selector, Workspace, Tracked Project, Tracked Workspace, Discovered Workspace, Remote Workspace, Primary Workspace, Agent Session, Copilot Fork, Task, Unassigned Work, Execution Profile, Kickoff Prompt, Execution Record, and Execution Step terminology from the glossary.
> Execution terms are domain definitions, not evidence of available CLI commands or desktop controls.
> Do not infer that Windows-specific desktop features apply to the cross-platform CLI.

# Architecture

> Understand how the Taskbean CLI, desktop app, local database, Projects, Workspaces, and Agent Sessions connect.

Taskbean has two product surfaces backed by one local data model.

| Surface | Primary user | Responsibility |
| - | - | - |
| `bean` CLI | Coding agents and terminal users | Record and update tasks, manage Projects and Workspaces, install the Agent Skill, reconcile Chronicle evidence, and generate reports |
| Desktop PWA | Developers | Review tasks and evidence, use on-device AI, inspect agent usage, manage reminders, and explore telemetry |

Both surfaces use `~/.taskbean/taskbean.db`. Set `TASKBEAN_HOME` to move the Taskbean data directory or `TASKBEAN_DB` to override the database path.

## Identity and attribution

```mermaid theme={"system"}
flowchart TD
  Session["Agent Session"] --> Workspace["Workspace"]
  Workspace --> Project["Project"]
  Task["Task"] --> Project
  Task -. "optional provenance" .-> Workspace
  Evidence["Chronicle evidence"] --> Session
```

A Project is logical. A Workspace is physical. Multiple checkouts, worktrees, and forks can roll up to the same Project.

The Project ID is the durable internal identity. Taskbean uses an `owner/repo` Project Key for Git-backed work, preferring `upstream` over `origin`. If a repository is renamed or transferred, the Project keeps its Project ID, adopts the new Project Key, and keeps the old key as a Project Alias.

An Agent Session without a local path can use a Remote Workspace only when repository metadata or a known Project Alias resolves one Project without ambiguity. Otherwise, it remains Unassigned Work. Repository identity establishes Project membership, but stable lineage evidence is required before Taskbean merges a Remote Workspace with a local Workspace.

Read the [glossary](/concepts/glossary) before designing integrations that create or resolve Projects.

## Independent versions

The CLI, desktop app, and Agent Skill can version independently. Use `bean --version` for the CLI and `GET /api/version` for the app. Follow [GitHub releases](https://github.com/taskbean/taskbean/releases) instead of relying on a hand-maintained version table.

## Platform boundary

The CLI package and compiled binaries target Windows, macOS, and Linux. The current desktop app dependency set includes Windows ML, WMI, PDH, Windows toast notifications, and PowerShell protocol registration. Treat those app capabilities as Windows-specific unless current source proves otherwise.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.