Projects and Tasks

A Project defines where Kairo Code may work. A Task keeps one durable thread of intent, actions, approvals, results, and recovery state inside that Project.

Create a Project

From the launcher, choose Open Folder for a single repository. Choose New Project when one outcome needs several related folders, then add each authorized root. Kairo Code treats the complete ordered root set as the workspace identity; opening one shared folder does not silently join another Project or Task.

Start or resume a Task

Create a new Task for a distinct outcome. Resume an existing Task when the new request depends on its prior decisions, context, or workspace changes. Task history survives client disconnects and Host restarts.

Pinning changes navigation only. Archiving removes a Task from the active list without deleting its history. Stopping an active turn cancels execution; it does not erase the Task.

Archive, stop, or permanently delete

These actions have deliberately different effects:

Action	Result
Stop	Cancels the active run. The Task, history, workspace, attachments, and recovery state remain resumable.
Archive	Removes the Task from the active list. It preserves history and can be restored.
Permanently delete	Irreversibly removes the durable Task aggregate, releases its Browser binding, and then cleans up Task-owned local resources. It cannot be undone.

Permanent deletion removes the Task's conversation/execution/approval/recovery record, discovery metadata, review snapshots, managed Worktree, deliverable manifest, upload claims, and Task-local storage. It does not delete the original Project roots or ordinary files in a user's local checkout. It also does not delete entries already contributed to the owner's separate Memory collection. Review or export any changes and deliverables that exist only in a managed Worktree before confirming deletion.

Permanent deletion is available only in releases whose UI displays that action or through an administrator API that explicitly supports it. Do not infer a hidden menu or delete files from the Kairo Code data directory by hand.

When permanent deletion is accepted, Kairo Code uses this order:

1. It first stops new Task activity, cancels pending interactions, stops background processes, and waits for child/model work to stop publishing results.
2. It commits deletion of the durable Task aggregate: the authoritative conversation, execution, approval, and recovery record.
3. After that commit, it durably releases the Task's saved Browser provider binding.
4. Only then does it remove discovery metadata and the Task index, followed by review snapshots, managed worktrees, deliverable manifests, upload claims, and Task-local storage.

If Kairo cannot read the durable evidence before deletion, it leaves a live Task registered and returns a failure. If the durable aggregate delete fails, the runtime has been stopped, but metadata, the index, Browser binding, worktree, attachments, and other local evidence remain so the Task can be recovered and the request retried. If the aggregate commit succeeds but Browser-binding release fails, Kairo also returns a failure and preserves metadata and index entries as a visible retry record; retrying completes the remaining authority release instead of recreating the deleted Task.

Cleanup after the aggregate and Browser-binding commits is best-effort. A later metadata, worktree, deliverable, upload, snapshot, or local-file cleanup failure does not make the deleted Task live again; an administrator may need to remove that residual local data. Memories are stored in the owner's separate Memory collection, not inside one Task aggregate, so permanently deleting a Task does not delete memories previously contributed from it. Review or delete those entries separately under Settings → Advanced → Memory & learning.

Steer active work

The composer remains available while a turn runs. A normal message is accepted durably and applied at the next safe model or tool boundary. Use interrupt when the current direction must change, and stop when no further work should execute.

Kairo Code also surfaces pending approvals and user-input requests in the active Task. Answer them there so the decision is attached to the exact operation that requested it.

Plan and review

Use Plan mode when implementation depends on unresolved choices or when you want to approve the approach before workspace mutation. A plan is explicit Task state—not any list of steps the Agent happens to write.

After implementation, use the workspace panels to inspect changed files, diffs, inline review comments, verification evidence, and unresolved approvals. Review feedback returns to the same Task, preserving the link between the comment and the code state it described.

Worktrees and multiple roots

When a Project uses an isolated worktree, Kairo Code records that execution environment with the Task. Multi-root Projects keep a stable root key for each repository so diffs, file links, review comments, and verification evidence cannot be attributed to the wrong root.