This project uses Loom - A multi-terminal desktop application that orchestrates AI-powered development agents using git worktrees and GitHub as the coordination layer.
This directory contains workspace-specific Loom configuration that should be committed to version control for team sharing.
Commit this file! Contains:
- Agent terminal configurations
- Next agent number (monotonic counter)
- Role assignments
- Autonomous mode settings
Commit these files! Team-specific roles:
*.md- Role definition markdown (required)*.json- Role metadata (optional)
Custom roles override system defaults when they have the same filename.
.loom/
├── config.json # Agent configurations
├── roles/ # Custom roles
│ ├── my-role.md
│ └── my-role.json
└── README.md # This file
These are automatically gitignored:
.loom/
├── .daemon.pid # Dev script PID file
├── .daemon.log # Dev script logs
├── daemon.sock # IPC socket
├── state.json # Runtime terminal state
├── activity.db # Activity tracking database
└── worktrees/ # Git worktrees (one per issue)
Note: Production daemon logs are written to ~/.loom/daemon.log (home directory).
Create .loom/roles/my-role.md:
# My Custom Role
You are a specialist in the {{workspace}} repository.
## Your Role
Describe what this role does...
## Guidelines
- Guideline 1
- Guideline 2Template variables:
{{workspace}}- Replaced with workspace path
Create .loom/roles/my-role.json:
{
"name": "My Custom Role",
"description": "Brief description",
"defaultInterval": 0,
"defaultIntervalPrompt": "Continue working",
"autonomousRecommended": false,
"suggestedWorkerType": "claude"
}- Right-click terminal → Settings
- Select "my-role.md" from role dropdown
- Configure autonomous mode if desired
- Save
See the Loom roles documentation for detailed role creation guide.
Edit config.json to customize:
{
"nextAgentNumber": 3,
"agents": [
{
"id": "1",
"name": "Worker 1",
"status": "idle",
"isPrimary": true,
"role": "claude-code-worker",
"roleConfig": {
"workerType": "claude",
"roleFile": "worker.md",
"targetInterval": 300000,
"intervalPrompt": "Continue working on tasks"
}
}
]
}Important: The nextAgentNumber is monotonic - it only increases, never decreases. Deleted agents' numbers are never reused.
To restore default configuration:
- File → Factory Reset Workspace...
- Confirm the operation
- All
.loom/contents will be deleted - Default configuration will be restored from Loom's bundled defaults
Warning: This deletes all custom roles and configurations!
When working in a team:
- Do commit: Custom roles, agent configurations
- Team members get: Your custom roles and suggested agent setup
- Each developer has: Their own runtime state (daemon, worktrees)
This allows teams to share agent roles and configurations while keeping runtime state local.
- Check filename ends with
.md - Check file is in
.loom/roles/directory - Restart Loom to reload roles
- Check
.loom/config.jsonexists - Check file permissions (should be writable)
- Check logs:
.loom/.daemon.log
- Worktrees are automatically cleaned up when terminals are destroyed
- Manual cleanup: File → Factory Reset Workspace
- Or delete
.loom/worktrees/directory manually
- System roles:
.loom/roles/(local copies) or Loom defaults - Role creation guide: Loom roles documentation
- Workflow guide: CLAUDE.md (in your repository root)
- Loom documentation: https://github.com/rjwalters/loom