Tasks & worktrees

Everything you do in Termic happens inside a task.

The model

Three nouns, nested:

• Project: a pointer to a git repository, plus its scripts, preview URL, sandbox defaults and default agent. A project can contain more than one repo, but the common case is one.
• Task: one stream of work against a project. Most tasks are a git worktree: a separate checkout on disk, on its own branch. Some are main checkout tasks that share your live checkout.
• Tab: what’s running inside a task: an agent CLI, a plain shell, an editor, or a diff view. A task can have several.

Starting a task: Worktree for isolated, parallel work, or Main checkout to attach an agent to your live checkout. Pick the agent right from the menu.

The New Task dialog has a worktree vs main checkout toggle, so you can launch an agent in an isolated worktree (the default) or directly in the main checkout with no git worktree created. The dialog remembers your last choice: the task type (worktree or main checkout) and the sandbox mode you picked last time carry over, so you don’t re-pick them every time.

Cmd+N opens a quick project picker that fuzzy-searches any project and starts a new task, without scrolling the sidebar to find the project first.

Worktree tasks

When you create a Worktree, Termic runs git worktree add to create a fresh checkout under ~/termic/tasks/<project>/<name>/, on a new branch cut from your project’s base branch. (The directory root is configurable in settings.) The worktree shares the project’s object database but has its own working tree, index and HEAD.

Worktrees give you:

• Isolation. An agent can rewrite files, run a build, install dependencies, and break things without touching your main checkout or any other task.
• Parallelism. Several worktrees means several agents working on several branches at the same time. See Parallel agents.
• Clean teardown. Archiving a worktree task removes the on-disk checkout and stops anything it was running.

Other worktree details:

• Termic creates the branch in two steps (git branch --no-track then git worktree add) so that deleting a task’s branch later doesn’t prompt you about dropping the upstream ref it was branched from.
• git-crypt repositories work in worktrees: Termic symlinks the key directory into the per-worktree git dir and resets so the smudge filter can decrypt.
• Agent sessions auto-resume. Each worktree has its own directory, so the CLI’s directory-based --resume / resume --last reconnects you to the same session after a sleep or relaunch.
• A resume that fails opens the agent’s own session picker. A stored session id stops resolving when the transcript was deleted, or when claude is holding that session in the background. The next spawn opens the agent’s session picker instead of starting a new conversation, and the toast shows the agent’s reason for refusing. The session you pick comes back through the agent hooks, so the next relaunch resumes it. Leaving the picker starts a fresh session once. Claude does this out of the box; another agent does it once its picker has been measured and its Session picker args filled in.

Duplicate a worktree

From a task’s menu, Duplicate worktree seeds the new-task dialog with the source task’s current branch tip as its base. This is how you fork a parallel attempt: let an agent get halfway, duplicate, and try a different approach from the same starting point in a second task.

Main checkout tasks

Not every change is worth a branch. Main checkout attaches an agent directly to your project’s live checkout, with no worktree at all. Use it for a one-off question, a README edit, a quick dependency bump, the kind of thing where spinning up an isolated branch is more ceremony than the task deserves.

Main checkout tasks behave a little differently, by necessity:

• They point at your real working directory, so changes are immediately in your checkout. There’s no “send to main” step because you’re already there.
• Archiving doesn’t delete anything. It closes the task; your repo is left exactly as it is.
• You can create several main checkout tasks per project. Because they all share one directory, Termic mints a session UUID for each on first spawn and resumes that on every later spawn, so they don’t accidentally pull in a claude session you ran outside Termic. The sidebar prompts for a name (defaulting to claude-1, codex-1, and so on).

Which one should I use?

A simple rule:

• Parallel work, risky changes, anything you’ll want to test on its own port → new worktree.
• A quick edit, a question, a small fix on the branch you’re already on → main checkout.

A single main checkout task still gives you tabbed agents, the editor and diff view, the run panel, and one-click session resume.

Per-task sandbox and YOLO

Two safety settings are pinned to the task, not the app:

• The sandbox mode (Off, Monitoring, or Enforcing) is chosen when you create the task, inheriting the project’s default, and editable later.
• YOLO (skipping per-action permission prompts) is set per task from its sidebar menu, when the task isn’t already enforced. An Enforcing sandbox turns it on automatically, since the OS cage enforces the limits instead. There is no global YOLO switch.

The sidebar flags a task running YOLO without an Enforcing sandbox with a red badge.

Idle and archived

Tasks you aren’t actively using show a moon icon in the sidebar when their agent goes quiet. Archiving (and deleting) runs on a background thread, so removing a task with a 50,000-file node_modules doesn’t freeze the UI.

Right-click a task in the sidebar to open its actions menu (the same one you reach from its row), where you’ll find Duplicate worktree, YOLO, the sandbox mode, and archiving.

Related

• Multi-repo tasks: more than one repo under a task.
• Parallel agents: running many at once.
• Spotlight: run your whole stack from the main checkout against one task.