Duration: 10-15 minutes Mode: Manual Orchestration Mode (MOM) Goal: Learn the complete Loom workflow from issue to merged PR
MOM is where you manually run Claude Code terminals with specialized role assignments (Builder, Judge, Curator, etc.) to coordinate development work through GitHub labels. Unlike Daemon Mode (continuous autonomous orchestration), MOM gives you direct control over each agent's actions through slash commands.
Before starting this tutorial, ensure you have:
- ✅ Loom installed in your repository (
./install.sh /path/to/your/repocompleted) - ✅ Workflow labels created on the forge (
.loom/scripts/sync-labels.sh) - ✅ GitHub CLI (
gh) installed and authenticated - ✅ Claude Code installed and available via
claudecommand - ✅ Git configured with your identity
Verify your setup:
# Check GitHub CLI authentication
gh auth status
# Check Claude Code is available
which claude
# Verify Loom files exist
ls .loom/We'll walk through a complete workflow: creating an issue for adding a new color theme, curating it, implementing it, reviewing it, and merging it.
First, create a GitHub issue for the feature we want to implement.
gh issue create \
--title "Add sunset color theme" \
--body "Add a new warm sunset color theme option to complement existing themes" \
--label "enhancement"Expected output:
✓ Created issue #42
Make note of the issue number (we'll use 42 in this example).
The Curator role enhances issues with implementation details, acceptance criteria, and test plans.
Open a new terminal and start Claude Code with the Curator role:
claudeThen, inside the Claude Code session, invoke the role:
/loom:curator
What this does: Loads the Curator role definition from .loom/roles/curator.md and provides context about issue curation workflow.
The Curator will automatically look for issues needing enhancement. When prompted, tell it to work on issue #42:
Please curate issue #42
What the Curator does:
- Reads the issue description
- Adds implementation guidance (which files to modify, approach options)
- Creates acceptance criteria checklist
- Adds a test plan
- Marks the issue as
loom:curated
Expected label transition:
No labels → loom:curated
Check the updated issue:
gh issue view 42You should see the Curator's enhancement comment with implementation details.
Once you review the Curator's enhancement, approve it for implementation:
gh issue edit 42 --add-label "loom:issue"Label transition:
loom:curated + loom:issue (ready for Builder to claim, curated label preserved)
Now we'll implement the feature as a Builder.
In a new terminal (or the same one after exiting Curator):
claudeThen, inside the session:
/loom:builder
Tell the Builder to work on issue #42:
Let's implement issue #42
The Builder will:
- Claim the issue by updating labels
- Create a worktree for isolated development
- Implement the feature
- Run tests
- Commit changes
- Create a pull request
1. Claim the issue:
gh issue edit 42 --remove-label "loom:issue" --add-label "loom:building"Label transition:
loom:issue → loom:building
2. Create worktree:
./.loom/scripts/worktree.sh 42
cd .loom/worktrees/issue-42This creates an isolated workspace at .loom/worktrees/issue-42 with a new branch feature/issue-42.
3. Implement the feature:
The Builder will make code changes, following the implementation guidance from the Curator.
4. Run tests:
# whatever your project's test command is — Loom does not impose one
pnpm check:ci5. Commit:
git add -A
git commit -m "Add sunset color theme
Implements warm sunset colors for theme switching.
Includes light and dark variants.
Closes #42"6. Push and create PR:
git push -u origin feature/issue-42
gh pr create --label "loom:review-requested" \
--title "Add sunset color theme" \
--body "Implements issue #42..."Expected output:
✓ Created pull request #43
Label transition (on PR):
No labels → loom:review-requested
The Judge role performs thorough code reviews.
claudeThen, inside the session:
/loom:judge
Tell the Judge to review the PR:
Please review PR #43
What the Judge does:
- Checks out the PR branch
- Reviews code changes
- Runs tests
- Checks for issues (formatting, logic errors, missing tests)
- Either approves or requests changes
If everything looks good, the Judge will:
gh pr comment 43 --body "LGTM!
✅ Code follows project conventions
✅ Tests pass
✅ Implementation matches issue requirements"
gh pr edit 43 --remove-label "loom:review-requested" --add-label "loom:pr"Note: Loom uses
gh pr commentinstead ofgh pr review --approvebecause GitHub's API prevents self-review when the same account creates and reviews PRs. Theloom:prlabel is the coordination mechanism for approval.
Label transition:
loom:review-requested → loom:pr (approved, ready to merge)
If the Judge finds issues, it will request changes:
gh pr comment 43 --body "Changes requested:
- [ ] Add dark mode variant
- [ ] Fix color contrast"
gh pr edit 43 --remove-label "loom:review-requested" --add-label "loom:changes-requested"Note: this is
gh pr comment, notgh pr review --request-changes, for the same self-review reason given above — and the PR moves toloom:changes-requested, a PR-lane label.loom:buildingis an issue-lane label and does not belong on a PR.
Doctor, not Builder, owns a PR in this state: it finds PRs labeled
loom:changes-requested, fixes them on the PR branch, and signals completion by
relabeling back to loom:review-requested — which hands the PR to a Judge for a
fresh review. Doctor never applies loom:pr itself, so an approval always
comes from a second Judge pass over the fixed tree:
# Doctor, after pushing the fix
gh pr edit 43 --remove-label "loom:changes-requested" --add-label "loom:review-requested"The loop is Judge → Doctor → Judge → merge, and it repeats until a Judge
approves. Verdicts are scoped to the commit they were rendered against, so once
the PR's head SHA moves, a leftover loom:changes-requested (or loom:pr) is
cleared and the PR returns to loom:review-requested automatically — a verdict
from an older commit is never trusted.
Doctor runs only when a Judge requests changes. If Step 4 had approved the PR, you would skip straight to Step 5; that is why the lifecycle is written Curator → Builder → Judge → Doctor (if needed) → Merge.
Once the PR is approved (loom:pr label), you can merge it:
./.loom/scripts/merge-pr.sh 43Expected output:
Merging PR #43: Fix widget alignment
Branch: feature/issue-42
PR #43 merged successfully
Branch 'feature/issue-42' deleted
Done
The issue (#42) will automatically close because the PR had "Closes #42" in the description.
Here's how labels flow through the entire process:
Issue Created (no labels)
↓
Curator enhances → loom:curated
↓
Human approves → loom:issue
↓
Builder claims → loom:building
↓
Builder creates PR → loom:review-requested (on PR)
↓
Judge reviews → loom:pr (approved)
↓
Human merges → Issue closed
Congratulations! You've completed your first Loom workflow. You now know:
✅ Slash Commands: How to launch role-specific Claude Code sessions ✅ Label Workflow: How GitHub labels coordinate agent work ✅ Worktrees: How isolated development environments work ✅ Role Coordination: How Curator, Builder, and Judge roles interact ✅ Complete Cycle: From issue creation to merged PR
Try these other roles:
/loom:architect- Create architectural proposals and design documents/loom:hermit- Identify code bloat and suggest simplifications/loom:doctor- Fix bugs and maintain existing PRs/loom:guide- Prioritize and organize the issue backlog
Create custom roles for your team's workflow:
# Create a custom role
mkdir -p .loom/roles
cp defaults/roles/builder.md .loom/roles/my-custom-role.md
# Edit my-custom-role.md to customizeSee defaults/roles/README.md for details.
Heads up — the Python daemon brain is gone in v0.10.0; the Rust
loom-daemonis the autonomous surface. The Pythonloom-daemonbrain and the/loom//loom --mergeslash commands were removed as part of the shepherd/daemon deprecation epic (#3372). The historical./.loom/scripts/daemon.shwrapper was removed in #3432; start/stop the autonomous Rust daemon with./.loom/scripts/cli/loom-daemon-start.sh/loom-daemon-stop.sh, and drive the tmux agent pool with./.loom/bin/loom start|status|stop— both with multi-account token rotation at the process-spawn boundary. The migration narrative — including what each entry point maps to — lives atdocs/migration/v0.10.0-shepherd-deprecation.md.
Once comfortable with the manual MOM workflow above, you can move toward autonomous orchestration. There are two complementary execution surfaces, each suited to different runtime expectations.
1. Multi-issue dispatch via loom-daemon (Tier 2 — single-host batching)
The Rust loom-daemon binary dispatches sweeps on demand. Operators
enqueue work with mcp__loom__dispatch_sweep, which detaches one
claude -p "/loom:sweep N" process per issue. Each child runs the full
Curator → Builder → Judge → Doctor → Merge lifecycle on its own. There
is no shepherd pool to size and no daemon-state.json to tune — by
default the daemon does not poll the forge; dispatch is operator-driven.
(An opt-in, default-off autonomous work finder (#3810) can poll open
loom:issue items and auto-dispatch sweeps when explicitly enabled.)
# Enqueue a sweep for a ready issue
mcp__loom__dispatch_sweep --issue 123
# Check what's running
mcp__loom__list_sweeps
mcp__loom__get_sweep_status --sweep_id <id>
# Cancel a sweep (SIGTERM → grace → SIGKILL)
mcp__loom__cancel_sweep --sweep_id <id>Dispatch requires a multi-account Claude token pool bootstrapped under
.loom/tokens/; each spawn picks its own OAuth token via
spawn-claude.sh. See the Multi-Account Token Pool section of
.loom/CLAUDE.md for the rotation setup. (The v0.9.x spawn-loop.sh
launcher was removed in v0.11.0 — use mcp__loom__dispatch_sweep
instead.)
2. Scheduled support roles (Tier 2 — cron-driven, daemon-free)
The periodic support roles that the old daemon ran in-process —
Champion, Curator, Judge, Auditor, Guide — are now GitHub Actions cron
workflows under .github/workflows/loom-*.yml. Each workflow checks out
the repo, installs the Claude CLI, and runs
claude -p "/<role>" --dangerously-skip-permissions for one tick of
work — no Loom-side state file, no long-running process.
Workflows ship with schedule: blocks commented out so forks don't
burn Actions minutes accidentally. To opt in:
- Add a
CLAUDE_API_KEYrepository secret (Settings → Secrets and variables → Actions). - Uncomment the
schedule:/- cron:lines in each.github/workflows/loom-*.ymlyou want to enable. - Optionally smoke-test via the Actions UI's Run workflow button
(
workflow_dispatch) before the next scheduled tick.
The two tiers compose: loom-daemon dispatch on your machine launches
sweeps for ready issues; GitHub Actions cron drives the support roles
that move issues and PRs between labels. Either can run on its own.
For the full reference (MCP tool surface, env tunables, opt-in
checklist, troubleshooting), see the
Daemon Mode
and
Scheduled Support Roles
sections of .loom/CLAUDE.md, and the full daemon surface at
.loom/docs/daemon-reference.md.
Solution:
# Install Claude Code
brew install anthropics/claude/claude-code
# Or download from https://claude.com/codeSolution:
# Install GitHub CLI
brew install gh
# Authenticate
gh auth loginSolution:
# IMPORTANT: First navigate OUT of any worktree directory
cd /path/to/main/repo
# Remove old worktree (only from main repo, not from inside a worktree!)
git worktree remove .loom/worktrees/issue-42 --force
git worktree prune
# Try again
./.loom/scripts/worktree.sh 42Note: Running git worktree remove while your shell is in the worktree will corrupt your shell state. Always navigate out first!
Solution:
# Re-authenticate with GitHub CLI
gh auth refresh
# Verify permissions
gh auth status- Getting Started Guide - Installation and setup
- Workflows Documentation - Complete label workflow reference
- Role Definitions - Learn about each role
- Git Workflow Guide - Worktree management and branching strategy
- Development Workflow - Daemon dev workflow
Questions or feedback? Open an issue at https://github.com/rjwalters/loom/issues