Documentation

Projects and tasks

How work is scoped, filed and tracked.

On this page

Projects are the unit of automation

A project is not a folder bookmark. It is the record that tells TDE which git remote to clone, which checkout supplies your local environment, which branch new work starts from, which pipeline runs, which third-party integrations apply, and what to execute after a worktree is created. Register one and every task you file against it inherits all of that.

Projects live in ~/.tde/projects.db. A project record carries:

Field	Meaning
`name`	Unique. Also the directory name under the canonical clone root.
`repo_url`	The git remote, used for clones and pull-request metadata.
`local_path`	Your development checkout — deliberately independent of TDE's own clone.
`default_branch`	The base for new worktrees and PRs. Defaults to `main`.
`worktree_setup_script`	A shell script run after each new worktree is created.
`dev_command`	The command behind Dev ▶. Stored in TDE only, never written into the repo.
`pipeline_id`	Which pipeline this project's tasks run. Defaults to `default`.

Three directories matter:

Path	Role
`~/.tde/repos/<name>`	TDE's canonical clone. This — and only this — is what the code index scans.
`~/.tde/worktrees/<name>/`	One git worktree per running task.
`~/.tde/projects/<name>/`	Per-project config such as `preview.toml`, kept outside any checkout so agents never have to edit the repo to change TDE's behavior.

Register a project by pointing TDE at an existing checkout, or import one by clone URL — the directory name is derived from the last URL segment with .git stripped. Removing a project deletes its record and its integration rows; the directory on disk is left untouched.

Integrations and environment

A project can bind connector instances for four integration kinds: linear, slack_triage, stripe and sentry. The binding stores only the connector's instance name — credentials stay in the encrypted vault. These bindings are what turn the matching bots on.

Because a git worktree does not carry gitignored files, TDE resolves the project environment from your registered checkout — its .env* files — and injects it into the processes it runs. Nothing is copied into the worktree. The setup script additionally receives TDE_PROJECT_PATH, TDE_WORKTREE_PATH and TDE_TASK_REF, and its output is redacted for known secret values. If the setup script fails, the worktree is removed and pruned rather than left half-provisioned.

Projects can also declare tags — project-scoped labels with helper descriptions that agents may apply to tasks.

Tasks

A task is a card on the board, stored in ~/.tde/board.db. It is shared: the desktop and the headless Runtime open the same database, so a card filed by tde task create is the same record you see on screen.

The fields you will actually work with:

Field	Notes
`tracker_id`	The external identity — `LIG-42`, `GH-118`, `jira:ENG-9`, `slack:…`, `telegram:…`. See Trackers and intake.
`title`, `description`	Free text.
`stage_id`	The authoritative pipeline stage — a free-form id from the task's own pipeline.
`pipeline_id`	Which pipeline this task runs.
`priority`	`Low`, `Medium`, `High`, `Urgent`.
`project`	The project name the agent works in.
`assignee` / `author`	Agent or human.
`labels`	Comma-separated tags, normalized to lowercase `#slug` form.
`budget_cents` / `spent_cents`	Per-task budget and accumulated spend. `0` means unlimited.
`logs`	Stage logs, each with a message and its cost.
`stage_deliverables`	Validated deliverable payloads, keyed by stage id.
`blocked`	A flag that draws `⚠` on the card.
`closed`	Set when the work is approved at the human gate. Does not change the stage.
`pending_question`	A parked `ASK:` question. See Human gates.
`scheduled_at`	A "not before" timestamp — automation will not pick the task up earlier.
`internal_notes`	Private. Never included in the context handed to an agent.
`owner_machine_id`	Under Sync, only the owner machine executes the task.

The card and the detail view

A card is four lines: tracker id, title, assignee, then either a sub-task rollup or up to three tags. Overlays mark state — ⚠ for the blocked flag, ⛓ for an open dependency.

Opening a task gives you an editable title; an action row (Run, Git Changes, Change Map, Mermaid, Chat, Shell, Env, plus Run on…, Council, Sandbox, PR #… and Dev Run when they apply); select fields for Project, Pipeline, Status, Priority, Schedule, Agent and Sprint; Tags; Blocked; the description; private Notes; and Attachments.

The right pane carries the Sub-tasks list — [✓] done, [→] running, [!] failed, [-] cancelled, [ ] pending — and tabs for Activity, Runtime, Sandbox and, once a pull request exists, CI.

Git Changes opens the worktree diff. Change Map opens the persisted map captured after a successful Build, including its files and relationships. Mermaid prefers that same persisted artifact so the diagram and review refer to one delivery record; an older task with no map falls back to generating a view from its current diff.

The activity feed

Activity is the task's comment stream. Comments come from humans, from agents, from task widgets (marked 🧩) and from the Council (⚖). Three kinds exist: a plain note, a blocker that flags the task as blocked on something, and an issue_ref that points at an external tracker item.

Comments are how a human's feedback reaches an agent: everything in the feed becomes part of the context for the next stage run.

Attachments

Attachments are file paths recorded against the task; the files themselves are copied into ~/.tde/attachments/<task_id>/. The picker accepts any file — what differs is how it opens: spreadsheets in TDE Sheets, .docx/.md/.txt in TDE Docs, PDFs and common raster images in the native viewer, everything else through a file association or the host opener.

Pasting a video URL is also an attachment action: TDE downloads the media, transcribes it and attaches transcript.txt.

When an agent runs on the task, attachments are not just paths on disk:

Kind	What the agent receives
Images (`png`, `jpg`/`jpeg`, `webp`, `gif`)	Resolved through TDE Pass as multimodal content before the tool loop starts.
Documents (`pdf`, `docx`, `xlsx`, `xls`, `ods`)	Extracted to text. Small files are inlined into the stage prompt; large ones are truncated there and indexed into the task's Recall overlay as soon as you attach them (or reopen the task detail).
Small text	Folded into the prompt directly.
Other binaries	Listed as file paths for the agent's normal tools.

Re-attaching or replacing a document re-indexes that path for the task — you do not need to leave the detail pane. See Agents and personas for the Pass path and Brain, decisions and recall for how excerpts come back.

Dependencies

Dependencies are a single relation: blocked by. Declare one and the dependent task will not run until every blocker is closed.

bash

tde task block 41 --by 38
tde task unblock 41 --by 38

The board refuses self-dependencies and cycles outright. Three places enforce the gate:

Manual dispatch — pressing Run on a gated task returns Blocked by #38 '…' — waiting completion. instead of starting.
Autonomous dispatch — bots and triage log waiting on blocker #38 … — will auto-start when done and skip the task.
Wave release — closing a task auto-starts every dependent whose last open blocker just disappeared, writing wave: unblocked by #38 — auto-started into its activity.

That last behavior is the point of dependencies: three independent tasks run in parallel and the fourth starts by itself the moment the last one closes.

Everything on this page is also reachable from the shell; see tde task.