Start Here · Operations
Operator Guide
Day-to-day operations for running Slop autonomously. Queue issues, monitor workers, configure automation, and recover when things go sideways.
Queue Management
Worker Status
Automation Modes
Incident Response
Quick Reference
The most common operator tasks at a glance. When something needs doing, start here.
| Task | How To |
|---|---|
| Queue an issue for implementation | Backlog column → click issue → click Set Ready |
| Reprioritize the queue | Drag cards up/down in the Ready column |
| Start a specific issue manually | Disable Auto Mode in Config, then click Start on the issue card |
| Check why a worker is stuck | Click the In Progress card → View Log |
| Restart a hung worker | Click the worker card → Restart |
| Retry a failed issue | Click the failed card → Retry Issue (creates a fresh worker) |
| Merge a PR manually | Disable Auto Merge in Config, then click Merge when CI passes |
| Pause all new work | Config → disable Auto Mode |
| Pause a single worker | Click worker card → Pause |
| Fix broken base CI | Fix the failing check on the base branch directly - no new claims or merges happen until it is green |
| Score all ready issues | Click Auto Plan above the Ready column |
| Switch watched repos | Use the repo selector at top of page, or append ?repo=<id> to the URL |
| Override a stuck merged PR to done | Worker card → Override to Merged destructive |
| Wipe everything and start fresh | Config → Wipe Database irreversible |
Understanding the Board
The board is your primary control surface. Four columns represent every stage an issue moves through, from raw backlog to completed merge.
Backlog
All open issuesSynced from GitHub snapshot of the watched repo.
Shows: number, title, labels, story points.
Action: click to open, then Set Ready.
Ready
Queued for implementationDaemon claims from top of this column when Auto Mode is on.
Drag cards to reorder priority.
Optionally set per-issue overrides before claiming.
In Progress
Agent is workingOne card per active worker.
Shows: status, PR link, CI status, cost so far.
Actions: Pause, Restart, View Log.
Done
Merged or closedLast 24 hours shown.
Shows final cost and merge time.
Issues auto-scroll off after 24h.
Live updates: The board refreshes in real time via Server-Sent Events. You do not need to reload the page to see a worker move from "implementing" to "waiting_ci" - status transitions appear within seconds.
Queueing Issues
Getting an issue into the implementation pipeline takes a few clicks. Auto Mode must be enabled for the daemon to automatically claim queued issues.
- Find the issue in the Backlog column (synced from GitHub).
- Click the issue card to open its detail panel.
- Click "Set Ready" - the issue moves to the Ready column.
- Drag the card in the Ready column to set its position in the priority queue. Top of the column = claimed first.
- Optionally: open the issue config to set a model override, effort level, or shipping mode for this specific issue.
- With Auto Mode on, the daemon picks it up on its next poll cycle (default: every 30 seconds). With Auto Mode off, click Start on the card to manually dispatch.
Internal issues: Issues created in Slop's built-in tracker (not GitHub) follow the same flow - they appear in the Ready column immediately after creation and are claimed by the daemon the same way.
Worker Status Flow
Every worker follows a defined path from claim to completion. Understanding this state machine tells you exactly what an agent is doing at any moment - and what it will do next.
start
→
claimed
→
implementing
→
verifying
(optional)
→
waiting_ci
→
merged
happy path
start
↓
CI fails
start
→
→
→
fixing_ci
→
waiting_ci
(retry, up to 5x)
review
→
waiting_review
→
in_review
→
waiting_address
→
in_address
(if request_changes)
merge
→
waiting_merge
(auto merge off)
→
merging
→
merged
|
failed
|
paused
conflict
→
resolving_conflict
(up to 5x, then failed)
Blue - active / in motion
Yellow - waiting on external signal
Orange - automated recovery in progress
Purple - review gate
Green - terminal success
Red - terminal failure
Grey - paused by operator
Status Reference
| Status | Color | What is happening | What comes next |
|---|---|---|---|
| claimed | Blue | Daemon created the worker row; worktree is being set up. | Transitions to implementing once worktree is ready. |
| implementing | Blue | Agent (claude/codex/copilot) is writing code in the worktree. | Agent pushes a branch and PR, moves to verifying or waiting_ci. |
| verifying | Blue | Optional verify gate running - cover + review skills checking the PR. | Passes to waiting_ci if gate clears. |
| waiting_ci | Yellow | PR pushed; waiting for GitHub CI checks to complete. | CI passes: moves to waiting_merge or review gate. CI fails: moves to fixing_ci. |
| fixing_ci | Orange | Agent is reading CI failure output and attempting to fix the code. | Pushes fix, returns to waiting_ci. Up to 5 attempts before failed. |
| resolving_conflict | Orange | Merge conflict detected; agent is rebasing the branch. | Returns to waiting_ci on success. Up to 5 attempts before failed. |
| waiting_review | Purple | Auto Review is on; waiting for the /pr-review skill to start. | Moves to in_review when review begins. |
| in_review | Purple | AI code review is actively running. | Verdict "approve" or "nitpicks" = proceed to merge. "request_changes" = address gate. |
| waiting_address | Purple | Review requested changes; waiting for the /address-comments skill. | Moves to in_address then back to waiting_ci after fix push. |
| in_address | Purple | Agent is addressing reviewer comments. | Pushes revised code, returns to waiting_ci. |
| waiting_merge | Yellow | CI passed and review gates cleared; waiting for Auto Merge or manual merge. | Auto Merge on: transitions to merging automatically. Off: operator clicks Merge. |
| merging | Green | PR merge API call in flight. | Success: merged. Conflict: resolving_conflict. |
| merged | Green | PR merged and issue closed. Worktree cleaned up. | Terminal - card moves to Done column. |
| failed | Red | Non-recoverable error: attempt budget exhausted or unexpected exception. | Terminal - use Retry Issue to start a fresh worker. |
| paused | Grey | Operator paused this worker. In-flight tool call completes first. | Click Resume to re-enter the status flow where it left off. |
Configuring Automation
Four master switches control how autonomous Slop operates. All changes take effect on the next daemon poll cycle.
Master Switch
Auto Mode
When on, the daemon automatically claims issues from the top of the Ready queue and dispatches workers. When off, nothing starts unless you click Start manually. Turn this off first when you need to take the system offline safely.
Merge Gate
Auto Merge
When on, PRs are merged automatically once CI passes (and any review gates clear). When off, workers park in
waiting_merge until you click Merge. Use this when you want human sign-off on every PR before it lands.Review Gate
Auto Review
When on, runs the /pr-review skill after CI passes. A "request_changes" verdict blocks the merge path. Costs additional API tokens. Good for catching regressions on complex or high-risk issues.
Address Gate
Auto Address
When on, automatically invokes /address-comments after a "request_changes" verdict. The agent reads reviewer comments and pushes fixes. Requires Auto Review to be on. Adds another CI cycle per review round.
Agent Model Selection
| Model | Speed | Cost | Best for |
|---|---|---|---|
| claude-haiku-4 | Fastest | Lowest | Trivial changes, typo fixes, doc updates, test additions, story points 1-2 |
| claude-sonnet-4 | Balanced | Moderate | Most features. Recommended default for story points 3-5 |
| claude-opus-4 | Slowest | Highest | Complex architectural changes, refactors, story points 8+ |
| codex | Varies | Varies | OpenAI Codex CLI harness alternative |
| copilot | Varies | Varies | GitHub Copilot SDK harness alternative |
modelEffortFromStoryPoints: When enabled, Slop automatically selects the model based on story point score - haiku for 1-2 points, sonnet for 3-5, opus for 8 and above. Enable in Config to avoid manually setting the model per issue.
Other Key Config Settings
| Setting | Default | Effect |
|---|---|---|
| Parallelism Cap | 1 | Maximum concurrent workers. Increase carefully - each worker consumes significant CPU and memory for the agent process. |
| Poll Interval | 30s | How often the daemon checks GitHub for CI status updates, new snapshots, and stuck workers. |
| agentTimeoutMs | None | Maximum wall-clock time for a single agent session. Set this to cap runaway workers that keep making tool calls. |
| stuckImplementingMs | 30 min | If a worker stays in implementing longer than this, a diagnostic notification fires. The worker is not killed automatically. |
| maxCiAttempts | 5 | How many times a worker retries CI failures before moving to failed. |
| maxConflictAttempts | 5 | How many times a worker attempts to rebase a conflicting branch before moving to failed. |
| Poll Paused toggle | Off | Pauses GitHub snapshot polling only. Workers already running continue unaffected. Use during GitHub API rate limit recovery. |
Handling Common Scenarios
A control room reference for the situations that come up most. Each scenario tells you what you will see, what to check, and what action to take.
Worker stuck in implementing
- Click the worker card → View Log. Look for the last tool call - if the timestamp is many minutes old, the process is likely hung.
- If the agent appears stuck with no recent activity: click Restart to re-dispatch a fresh agent session on the same worktree.
- If it has been over your
stuckImplementingMsthreshold, you will have received a notification - this confirms the hang rather than slow normal progress. - If Restart does not help, check system resources - the agent process may be OOM-killed silently.
CI keeps failing - worker cycling through fixing_ci
- Open the worker log and look for the CI failure output the agent is reading. Is it a flaky test, a missing env var, or a genuine bug in the generated code?
- If flaky: re-trigger CI from GitHub directly - once CI passes, the worker picks it up on the next poll.
- If the agent cannot fix it after 5 attempts, the worker moves to
failed. Fix the underlying issue in the repo manually, then use Retry Issue. - Reduce
maxCiAttemptsin Config to fail faster on unsolvable issues.
Repeated resolving_conflict loops
- Conflicts usually mean the base branch has diverged significantly since the PR was opened.
- Let the agent try up to 5 times - for simple conflicts, it typically succeeds within 1-2 attempts.
- If all attempts fail: click Restart. A fresh agent will rebase from the current base branch HEAD.
- For complex conflicts: resolve manually in the worktree path (
WORKTREES_ROOT/<repoId>/<issueNumber>), push the branch, then let the worker continue fromwaiting_ci.
Worker is in failed
- Click the card → View Log. Scroll to the bottom to find the terminal error event.
- Identify whether it is an infrastructure problem (worktree corruption, GitHub API error) or a code problem (agent could not make the tests pass).
- Fix the underlying cause (manually patch the repo, correct the issue description, upgrade the model for this issue).
- Click Retry Issue to spawn a fresh worker from scratch.
Base Branch CI is red - no new claims or merges happening
- The base CI health banner at the top of the board turns red when the main branch has failing checks.
- The daemon halts all new claims and all merges until base CI is green again. This is intentional - no point building on a broken base.
- Fix the failing check on your base branch directly (outside of Slop). Once the check goes green, the daemon resumes automatically on the next poll.
- Workers already implementing are unaffected - they are working in worktrees off the current HEAD.
Review keeps blocking merge with
request_changes
- Check the review output in the worker log to understand what the reviewer flagged.
- If Auto Address is on, the agent attempts to fix the comments automatically. Watch
in_addressstatus. - If the reviewer is flagging something the agent cannot fix (e.g. architectural disagreement), disable Auto Review temporarily and merge manually.
- Or edit the issue description to give the agent clearer implementation constraints, then Retry.
Memory alert - diagnostic issue filed on GitHub
- When an agent process exceeds the memory threshold (default: 2 GB), Slop automatically files a diagnostic issue on the watched repo with the "diagnostic" label.
- The affected worker may have been killed by the OS. Check its status - if it moved to
failed, Retry Issue with a lower-cost model (haiku uses less memory). - If the issue is consistently OOM-killing workers, consider reducing
agentTimeoutMsor breaking the issue into smaller sub-issues.
Worker stuck in waiting_merge but PR was merged manually on GitHub
- The daemon polls for merge status; it should detect the merge within the next poll cycle and transition the worker automatically.
- If it does not transition after 2-3 poll cycles, use Override to Merged on the worker card.
- This stamps the worker as
mergedand cleans up the worktree. It does not perform any GitHub operations.
Need to pause everything urgently
Fastest path: Config → disable Auto Mode. No new issues will be claimed. Workers already In Progress continue running until they reach a wait state or completion.
To also stop in-flight workers: Click Pause on each In Progress card individually. The agent completes its current tool call before pausing.
To drain completely: Disable Auto Mode, wait for all In Progress cards to reach a terminal or wait status, then you have a fully quiesced system. Safe for database maintenance, host reboots, or major config changes.
To also stop in-flight workers: Click Pause on each In Progress card individually. The agent completes its current tool call before pausing.
To drain completely: Disable Auto Mode, wait for all In Progress cards to reach a terminal or wait status, then you have a fully quiesced system. Safe for database maintenance, host reboots, or major config changes.
Destructive Operations
Two admin operations have irreversible consequences. Read carefully before using either.
⚠ Override to Merged admin
Forces a worker to the
merged terminal state and cleans up its worktree, regardless of actual PR status.
Use only when you have merged the PR manually on GitHub and Slop has not detected it automatically.
What it does
- Sets worker status to
merged - Deletes the git worktree from disk
- Fires a final "merged" event to the UI
- No GitHub API calls are made
What it does NOT do
- Does not merge the PR on GitHub
- Does not close the GitHub issue
- Does not verify the PR was actually merged
When to use: PR is merged on GitHub but worker is stuck in
waiting_merge or merging after 2-3 poll cycles. Not for PRs that were closed without merging - use Retry Issue instead.
🚫 Wipe Database irreversible
Deletes all operational data from the SQLite database and resets config to defaults.
There is no undo. The daily backup is your only recovery option.
Preserved
- Repo registrations (slug + path)
- GitHub token
- Daily backup file
Deleted
- All workers and events
- All ready queue entries
- All issue snapshots
- All config settings (reset to defaults)
- Internal issues and story points
Note: Existing git worktrees on disk are NOT deleted by Wipe Database. Clean them up manually from
WORKTREES_ROOT/ after wiping if you want a fully fresh start. Use this only as a last resort after a bad experiment or unrecoverable corruption.
Monitoring Health
Several indicators surface system health at a glance. Check these when things feel slow or wrong before diving into individual worker logs.
| Indicator | Where | What it means when red/bad | Fix |
|---|---|---|---|
| Base Branch CI | Top of board | Main branch has failing checks. No new claims, no auto-merges. | Fix the CI failure on the base branch directly. |
| Guard Status | Config page | Branch protection rules are not correctly configured on the watched repo. | Enable branch protection with at least one required CI context on GitHub. |
| Daemon Status | Config page / top bar | Daemon process is not running or crashed. | Run make dev or restart the server process. |
| Poll Paused | Config page | Snapshot polling disabled. Board will not refresh with new GitHub issues. | Toggle off Poll Paused in Config once rate limits recover. |
| Memory diagnostic issues | GitHub repo (diagnostic label) | One or more agent processes exceeded the memory threshold. | Use a smaller model for the affected issue type. Check system RAM availability. |
| Worker stuck in implementing > threshold | Notification / worker log | Agent process may be hung or OOM-killed silently. | View log, then Restart the worker. |
Multiple Repos
Slop supports multiple watched repos simultaneously. Workers, queues, and snapshots are repo-scoped; configuration is global.
| What | Scope | Details |
|---|---|---|
| Workers, ready queue, snapshots | Per-repo | Each Repo row has independent workers, ReadyIssue queue, and RepoSnapshot. |
| Config settings | Global | Auto Mode, Auto Merge, Auto Review, model, parallelism cap, poll interval - all apply to every repo. |
| Per-issue overrides | Per-repo + issue | IssueConfig rows are scoped to a specific repo and issue number. |
| GitHub token | Global | One GITHUB_TOKEN authenticates all watched repos. |
| Worktrees | Per-repo | Nested at WORKTREES_ROOT/<repoId>/<issueNumber>. |
Switching repos: Use the repo selector at the top of the page, or append
?repo=<id> to any URL. The selection is remembered in a cookie. All board and worker views filter to the selected repo.
Story Points and Planning
Story points drive model selection and help estimate queue throughput. They are optional but unlock automatic model-to-complexity matching.
| Points | Complexity | Auto-selected model |
|---|---|---|
| 1 | Trivial - typo, one-liner | haiku |
| 2 | Simple - add a field, rename | haiku |
| 3 | Small feature or fix | sonnet |
| 5 | Medium - multi-file change | sonnet |
| 8 | Large - new subsystem component | opus |
| 13 | Architectural - crosses many boundaries | opus |
| 21 | Epic - should be broken down | opus |
- Auto Plan: Click the button above the Ready column to score all ready issues at once using AI estimation.
- Single issue: Open an issue card, click Suggest Points to score just that one.
- Enable auto model selection: Turn on
modelEffortFromStoryPointsin Config. Slop then ignores the global model setting for scored issues and picks the right tier automatically.
Cost Management
Each worker session calls the agent API and accumulates token costs. Slop surfaces this in real time so you can catch runaway sessions before they get expensive.
| Where to look | What you see |
|---|---|
| In Progress card (live) | Estimated API cost updated every event, in real time. |
| Worker log - final "result" event | Total input tokens, output tokens, and computed cost for the full session. |
| Done column cards | Final cost shown on each completed worker. |
Keeping costs down: Use
claude-haiku-4 or claude-sonnet-4 for most issues. Reserve opus for genuinely complex architectural work (8+ story points). Set agentTimeoutMs in Config to cap session length for any worker that keeps making tool calls without finishing. A worker cycling through fixing_ci repeatedly can accumulate significant cost - watch the live counter and Restart or fail it manually if it goes far above expected.