Projects, tasks & worktrees

Projects & repositories

A project is a workspace, not a folder: one or more git repositories, plus the SSH hosts, database connections and issue trackers attached to it, plus its tasks. One project can span several repos — a front end and an API — and a task can work in any of them.

Attaching a resource to a project is also what makes it reachable by agents working in that project, which is where the permission model starts.

Tasks & their states

A task is a unit of work with its own terminal panes, agent, worktree and lifecycle state.

State comes from the agent's own output and, where the CLI supports it, from a status hook Muster wires in. The sidebar shows it as a dot with the reason underneath when the agent gave one, so "waiting for input" is never silently swallowed.

The hook works on all three platforms — a local socket on macOS and Linux, a named pipe on Windows — and needs a python interpreter to forward the event. Muster finds one the way you would: your PATH first, then your login shell on macOS/Linux (so a conda, pyenv, asdf or homebrew python counts) or the py launcher on Windows, and it bakes the resolved path in so the lookup does not depend on the agent's own environment. If there is no python at all the hooks are still installed — a later install makes them work — and the log says why live status is not reporting, instead of leaving you with a task that never changes state.

A worktree per task

Creating a task can open a dedicated git worktree — a real, separate checkout on disk — on its own branch.

• New — a fresh branch off a base you choose.
• Existing — reuse a worktree another task already opened.
• Off — work directly in the repository root.

Two agents in two worktrees cannot overwrite each other's files, and neither can touch your main checkout. Git itself is the backstop: it refuses to check the same branch out twice.

Post-create hooks

Per project, commands can run automatically once the worktree exists — installing dependencies, copying an .env, warming a build cache. Configured under post_create_hooks, keyed by project.

Reviewing & shipping

The diff reviewer is a real one, not a status badge:

• Stage, unstage or discard by hunk or line range, unified or split.
• Inline review notes. They are always kept locally; pushing one as a PR comment needs the gh CLI installed and signed in, a GitHub host, and a PR already linked to the task — otherwise the note stays local and says so.
• Ignore-whitespace, expandable context, and gates on very large diffs.
• Update-from-base with a conflict resolver; blame and full file history.
• Open a pull request from the app. Muster pushes the branch, then creates the PR in place with gh pr create when the gh CLI is installed and signed in; without gh it opens your host's own create-PR page in the browser instead (GitHub, GitLab, Bitbucket and Azure DevOps compare URLs are all handled). Force-push only ever uses --force-with-lease, so a blind overwrite is not possible.

Closing a task asks whether to keep its worktree. The archive of closed tasks stays browsable and reopenable, and marks which ones lost their worktree at close.