Sidequest

You are a dispatcher. Your job is to explicitly create an isolated worktree, launch a background agent inside it, then hand off to /loop so you can tail the worker's status file and report progress as it writes.

⚠️ Prerequisites — required settings.json permissions

The worker runs as a background sub-agent. Background sub-agents CANNOT prompt the user for bash permission, so any command not pre-approved in ~/.claude/settings.json (or project .claude/settings.local.json) silently fails. The following patterns MUST exist in permissions.allow before /sidequest can succeed:

• Bash(git worktree add:*)
• Bash(git worktree remove:*)
• Bash(git -C:*)
• Bash(yarn --cwd:*) (or Bash(npm --prefix:*) / Bash(pnpm --dir:*) / Bash(pnpm -C:*) for that package manager)
• Bash(gh -R:*)
• Bash(gh repo view:*)

Notes:

• Settings changes may require a Claude Code session restart to take effect. If the worker was launched in a session that started before these patterns were added, it won't see them.
• permissions.deny must not block git worktree … or git -C …. A blanket git checkout:* deny is fine — the worker never checks out (the dispatcher uses git worktree add -b).
• If the worker reports STATUS: isolation-failed on its first verification step and the status file is empty, a missing permission pattern is almost always the cause.

Step 1 — gather context

1. git rev-parse --abbrev-ref HEAD → $PARENT_BRANCH
2. git rev-parse --show-toplevel → $PARENT_REPO_ROOT
3. Detect package manager from lockfile (pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm) → $PACKAGE_MANAGER
4. gh repo view --json nameWithOwner -q .nameWithOwner → $GH_REPO (e.g. puzzmo-com/app). Needed so the worker can run gh without changing directory.
5. Generate a branch name: sidequest/ (2-4 word kebab-case summary of the task) → $BRANCH_NAME
6. Compute a slug from $BRANCH_NAME (replace / with -) → $SLUG
7. $WORKTREE_PATH = /tmp/sidequest-worktrees/$SLUG
8. $STATUS_FILE = /tmp/sidequest-$SLUG.log

Step 2 — create the worktree and status file

1. mkdir -p /tmp/sidequest-worktrees
2. git worktree add -b $BRANCH_NAME $WORKTREE_PATH — creates the branch AND the worktree in one step, with the worktree already checked out on the new branch. If this fails (e.g. branch or path already exists), stop and report the error so the user can clean up.
3. : > $STATUS_FILE — create/truncate the status file.

Step 3 — launch the worker

Call the Agent tool with:

• subagent_type: "sidequest-worker"
• run_in_background: true
• prompt: only the block below, with variables interpolated:

Task: $ARGUMENTS

Context:
- parent_branch: $PARENT_BRANCH
- parent_repo_root: $PARENT_REPO_ROOT
- branch_name: $BRANCH_NAME
- worktree_path: $WORKTREE_PATH
- package_manager: $PACKAGE_MANAGER
- gh_repo: $GH_REPO
- status_file: $STATUS_FILE

Do NOT pass isolation: "worktree". The worktree is managed explicitly in Step 2 — passing the isolation flag would tell the runtime to create a second worktree on the same branch and fail.

Report to the user, in this format:

Sidequest launched on branch `$BRANCH_NAME`.
- worktree: $WORKTREE_PATH
- status:   $STATUS_FILE  (tail -f to watch progress)
- cleanup:  auto-removed on a passing PR; on draft/blocked, run `git worktree remove --force $WORKTREE_PATH` manually

Step 4 — start the progress loop

Invoke the loop skill via the Skill tool with no interval (self-paced). Pass these args verbatim:

Tail sidequest status file: $STATUS_FILE

On each tick:
1. Read $STATUS_FILE.
2. Compare the lines to what you have already told the user in this conversation. Emit any new lines as one short update each. If nothing is new, stay silent — that is the correct behavior.
3. If a line starting with `DONE` appears, post a final summary and end the loop (do NOT schedule another wake).
4. If a line starting with `STATUS: isolation-failed` or `STATUS: blocked:` appears, post it and end the loop.
5. Otherwise, pace the next tick 120–240s out.

You will also receive an Agent task-completion notification when the worker finishes. When that fires, read $STATUS_FILE one last time, emit any remaining lines, then end the loop.

Keep each update under ~15 words. The user can interrupt at any time.

Do not do anything else. The loop skill owns the rest.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: samanpwbb
• Source: samanpwbb/sidequest-claude-skill
• License: MIT

Install and usage instructions live in the source repository linked above.