Multi-Project Workflows

Sidequest organizes work in a two-level hierarchy: Workspaces contain Projects, and Projects contain Quests. Supervisors and the Active Quests timeline cut across that hierarchy, so you can run and watch work in many repositories at once.

The Hierarchy

Workspace ("Acme")
  |-- Project: api-gateway   (git repo at ~/code/api-gateway)
  |     |-- Quest: Add rate limiting to /orders        (Worktree)
  |     |-- Quest: Why is /search p99 3x higher?       (Current Branch)
  |
  |-- Project: web-dashboard (git repo at ~/code/web-dashboard)
  |     |-- Quest: Dark mode for the billing pages     (Worktree)
  |
  |-- Project: infra         (git repo at ~/code/infra)

Home                         (your home directory, Current Branch quests only)

Workspaces

A workspace is a named container for grouping related projects. It has no path on disk — it is purely organizational. Use workspaces to group projects by team, client, or initiative. Sidequest starts with one named Default.

Projects

A project points to a directory on your filesystem, usually a git repository. Add them from disk or by cloning a URL; see First Workspace.

Quests

Quests belong to a project and represent a unit of work. Each quest gets its own agent session, and Worktree quests get their own git branch and worktree.

Working with Multiple Projects

Running Quests Across Projects

Each project has its own set of quests. You can have active quests running simultaneously in different projects — for example, a backend feature and a frontend feature at the same time. Each runs in its own tmux session with its own worktree.

Switch between projects in the sidebar to view each project’s quest log. Active sessions keep running in the background when you switch away.

Seeing everything at once

• The sidebar shows a green ▶ count of active quests on every project and shimmers a project’s name when one of its quests needs attention. The filter button narrows the tree to projects with active quests.
• The Active quests button in the bottom toolbar opens a timeline of every active quest across all projects: how long each has run, when it last changed, and Aging / Stale markers for quests that have gone quiet for a day or three. Click a row to jump to it.
• The command palette (Cmd+Shift+P) searches quests in every project.
• Search all journals (the owl) searches every project’s journal entries.

Supervising across projects

A supervisor is not tied to a project. Drag quests — or whole project headers — from any number of repositories onto one supervisor, and it answers their prompts and pulls from one queue. This is the easiest way to keep a cross-cutting change (a dependency bump across six services, say) moving unattended.

Cross-project context

When a quest in one repository needs to read another, add it under Add other projects for context in the Create Quest dialog, or set Attach projects to new quests in Project Settings so every quest in that project starts with the same list. The agent is told to read those paths; no worktrees are created for them. Any directory can be added with Browse directory…, not only registered projects.

Journals carry knowledge across projects too: sidequest-journal search --all-projects finds what a quest elsewhere learned.

Multi-Repo Projects

Early versions of Sidequest had a Multi Repo project type for a parent folder containing several git repositories. Existing multi-repo projects keep working, but adding such a folder today opens a picker that adds each child repository as its own project, which is simpler to supervise and review.

If you still have a multi-repo project:

• A Worktree quest creates one worktree per child repository under ~/.sidequest/multirepo/<quest-id>/, all on the same branch name, and runs the agent in the parent directory so it can see them all.
• The Changes panel prefixes paths with the child repository name.
• Review quests and the branch selector are not available.

Monorepo Projects

If your monorepo is a single git repository (e.g., a Turborepo, Nx, or Lerna project), add it as a regular Git Repo project. Sidequest handles single-repo worktrees natively. A per-project Setup Command (for example pnpm install) keeps fresh worktrees ready to build.

Organizing Large-Scale Work

For teams or individuals managing many repositories, consider this structure:

Workspace: "Platform Team"
  Project: API Gateway
  Project: Auth Service
  Project: Web Dashboard

Workspace: "Mobile Team"
  Project: iOS App
  Project: Android App
  Project: Shared SDK

Workspace: "Infrastructure"
  Project: Terraform
  Project: Deploy Scripts

Tips for staying organized:

• One workspace per team or initiative. Keep related projects together.
• Star what you work on this week and use the star filter to hide the rest.
• Use Current Branch quests for cross-cutting questions. They run directly in the repo without creating branches.
• Name quests descriptively. The quest prompt is used to generate the branch name and to match relevant journals.
• Give each kind of work a supervisor with a ceiling that matches how much of it you want running at once.