Send an agent on a sidequest, without messing up your working branch. This is basically a more ergonomic way to use worktrees with Claude than the documented --worktree flag on the Claude CLI tool.
A background agent spins up in an isolated worktree, does the work, pushes the branch, and opens a PR, and (if all goes well) deletes the worktree. You get periodic status updates as the worker progresses through its phases (install, edit, test, push, PR).
- Dispatcher (the
/sidequestskill): gathers repo context, creates a branch and worktree under/tmp/sidequest-worktrees/, launches the worker as a background agent, and hands off to/loopto tail a status file. - Worker (the
sidequest-workersub-agent): verifies it's in its worktree, installs dependencies, completes the task, runs type-check and tests, commits, pushes, and opens a PR against the parent branch. - Progress loop: while the worker runs, the main session self-paces check-ins on the status file and surfaces phase transitions to you inline.
On a passing PR, the worktree is auto-removed. On a draft PR (failing checks) or a blocked worker, the worktree stays so you can inspect or iterate locally.
- Claude Code — the harness this runs in.
git2.5 or newer (needsgit worktree).ghCLI, authenticated (gh auth login)./tmpwritable — that's where worktrees and status files live.
git clone https://github.com/samanpwbb/sidequest-claude-skill.git
cd sidequest-claude-skill
./install.sh
Then add the patterns from permissions.json to the permissions.allow array in ~/.claude/settings.json. The installer prints them at the end as a reminder. Restart Claude Code so the new settings take effect.
Background sub-agents can't prompt for bash permission — any command that isn't pre-approved in settings.json silently fails. The patterns in permissions.json authorize the specific tools the worker needs: git worktree, git -C, yarn --cwd / npm --prefix / pnpm --dir, gh -R.
From a repo where you want to kick off a task:
/sidequest fix the broken invite URL in apps/workshop/src/components/PendingInvites.tsx
You'll get a launch message with the branch name, worktree path, and status file. From there, progress updates appear inline (e.g. installing deps → editing PendingInvites.tsx → tests-ok → pushed → pr-opened: <url>). You can keep chatting with Claude in the main session while the worker runs; check-ins are paced 2–4 minutes apart.
- Settings changes require a Claude Code restart to take effect. If the worker reports
STATUS: isolation-failedright after installing, the running session probably hasn't picked up the new permission patterns yet. - No
cdin the worker. The permission layer denies compound commands (cd X && Y) even when both halves would individually pass. The worker uses tool-native cwd flags instead — this is documented inside the sub-agent for anyone reading the source. - Draft PRs keep the worktree. If type-check or tests fail after three repair attempts, the worker creates a draft PR and leaves the worktree in place. Clean up manually with
git worktree remove --force /tmp/sidequest-worktrees/<slug>when you're done. - Concurrent sidequests with the same slug collide. The status file path is derived from the auto-generated branch name. If two tasks produce the same slug, the second will clobber the first's status file (the branch creation will also fail, surfacing the collision).
git checkout:*in your deny list is fine. The worker never runsgit checkout— the dispatcher creates the branch withgit worktree add -bin one step.
For maintainers who want to iterate on the skill with the live version in ~/.claude:
./install.sh --link
This symlinks ~/.claude/skills/sidequest → ./skill (directory symlink) and ~/.claude/agents/sidequest-worker.md → ./agents/sidequest-worker.md (file symlink). Edits to files in this repo take effect on the next Claude Code session.
MIT. See LICENSE.