Introduction
What is Slop?
Slop is a local autonomous development pipeline: given a list of prioritized GitHub issues (or internal issues), it claims each one, spins up an isolated git worktree, invokes an AI agent (claude, codex, or copilot harness) to implement the fix, waits for CI to pass, optionally runs an AI PR review gate, then merges. It runs entirely on a developer's laptop -- no cloud deployment, no external orchestration service.
The operator interacts through a Next.js web UI; the backend is a single long-lived Node.js
daemon that poll-drives every phase of every issue's lifecycle. Issues flow through a 17-status state machine,
and every external collaborator is injected through a typed Deps object so the entire execution
path is independently testable.
Slop operates on separate, configured "watched repos" -- each a Repo row
(slug owner/name + local checkout path) added on the Config page. One GITHUB_TOKEN
authenticates all of them. Issues filed on this repo are ignored unless this Slop checkout itself is added
as a watched repo (dogfooding).
Issue Pipeline
Issue Ready
Label applied, enters queue
Implement
Agent runs in worktree
Verify
Optional post-impl check step
CI
Waits for checks to pass
Review
Optional AI PR review gate
Merge
PR merged, issue closed
Capabilities
Key Features
What Slop can do out of the box.
Automated Issue Implementation
Dispatches an AI agent (claude, codex, or copilot) to implement each queued issue in an isolated git worktree, then opens a pull request with the changes.
CI Gate
Waits for all required GitHub CI checks to pass before attempting to merge. Automatically retries failing CI by spawning a fix agent.
Auto-merge
Once CI clears and any review gates pass, Slop merges the pull request and closes the original issue automatically.
PR Review Gate
Optionally runs an AI-powered code review on the PR before merging. The agent addresses review comments and re-runs until the review is satisfied.
Verification Step
Runs a configurable post-implementation verification command (e.g., your test suite) directly in the worktree before pushing the PR.
Parallel Workers
Multiple issues can be implemented concurrently. A per-repo parallelism cap prevents resource exhaustion on the local machine.
Internal Issue Store
A lightweight local issue store lets you create, refine, and track issues without touching GitHub. Internal issues surface on the same Kanban board.
Batch Import
Import and process groups of issues together as a named batch, useful for coordinating related work or story-point-sized slices.
Live Console
A real-time log stream (Server-Sent Events) shows every worker event, state transition, and agent log line as it happens in the browser.
Multi-repo
Manage multiple watched repos from a single Slop instance. Workers, issues, and worktrees are scoped per repo; one GitHub token covers all.
Technology
Tech Stack
The full list of technologies Slop is built on.
| Category | Technology | Version | Role |
|---|---|---|---|
| Framework | Next.js | 16.2.6 | App Router, Server Actions, SSE |
| UI Library | React | 19.2.6 | Client Components, hooks, live updates |
| Language | TypeScript | 6.x | End-to-end strict typing (strict: true) |
| ORM | Prisma | 7.x | Schema, migrations, query builder |
| Database | SQLite | better-sqlite3 12.x | Embedded persistent store, no external DB |
| Agent SDK | Claude Agent SDK | 0.3.x | Drives Claude Code agents per issue |
| CSS | Tailwind CSS | 4.x | Utility-first via globals.css tokens |
| Linter/Formatter | Biome | latest | Lint + format in a single pass |
| Unit Tests | Vitest | 4.x | Node-side tests against real test DB |
| E2E Tests | Playwright | latest | Browser automation and integration tests |
| Package Manager | pnpm | latest | Workspace, frozen lockfile |
| Module Boundaries | dependency-cruiser | latest | Enforced import rules between layers |
Setup
Quick Start
Get Slop running locally in four steps.
1
Install dependencies
Run the install target to set up pnpm packages and generate the Prisma client.
make install2
Configure environment
Copy the example env file and fill in your
GITHUB_TOKEN and other required values.cp .env.example .env
# Edit .env: set GITHUB_TOKEN, WORKTREES_ROOT, etc.3
Start the dev server
Launches both the Next.js UI and the background worker loop concurrently on port 3100.
make dev
# Open http://localhost:31004
Add a watched repo and queue issues
Open the Config page, add a watched repo by entering the
owner/name slug and local checkout path. Then click "Set Ready" on any issue in the board UI to add it to the ReadyIssue queue.
Issues added to the
ReadyIssue queue via the board UI are picked up on the next poll cycle -- default 30 seconds. The poll interval is adjustable via the Config page.
Concepts
Key Concepts
Core ideas to understand before diving into the code.
Watched Repos vs the Slop Repo
A "watched repo" is any GitHub repository configured on the Config page as a
Repo row -- the target of automation. The Slop repo itself is not a watched repo by default. Add it as one to dogfood: Slop will then implement its own issues.
Workers and Their Lifecycle
A
Worker DB row tracks one issue's progress through a 17-status state machine: from claimed through implementing, waiting_ci, optional in_review, and finally merged or failed. Each transition is a guarded compare-and-set that prevents double-advancing.
Daemon Polling Model
Rather than a push-driven event queue, the daemon re-evaluates the world on a fixed interval (default 30 s). Each cycle executes a deterministic sequence: guard check, base CI health, auto-pilot claiming, lifecycle reconciliation, resource monitoring, agent spawning, snapshot refresh, and worktree reaping.
Server Actions + Daemon Interface
UI mutations go through Next.js Server Actions in
src/app/actions/, which validate inputs and delegate to the daemon via getRunningDaemon(). Actions return a {"{"} ok: true {"}"} | {"{"} ok: false; error: string {"}"} union and never throw to the client. New operations are added to the Daemon interface in src/server/daemon/types.ts.
Dependency injection everywhere: Worker steps and daemon polls accept every collaborator through a single typed
Deps object, not through direct module imports. Production wiring happens once at boot in src/server/daemon/index.ts. Tests inject fakes at any granularity, making the full execution path testable without mocking modules.
Navigation
Documentation Map
All available documentation files and what they cover.
| Document | Contents |
|---|---|
| Project Overview | What Slop is, key features, full tech stack table, quick start guide, key concepts, and this map. |
| Architecture | Three-subsystem overview (UI, Daemon, Workers), layered dependency rules, poll-driven CAS state machine, event bus, process-per-worker concurrency model, and boot sequence. |
| Data Models | All Prisma models (Worker, Repo, Run, Event, IssueConfig, ReadyIssue, Batch, etc.), repository function signatures, and cross-cutting TypeScript types in src/types/. |
| API Contracts | Server Actions grouped by domain (issue, worker, PR, repo, config, batch, runs), the full Daemon interface, and all HTTP REST + SSE route paths. |
| Component Inventory | Catalog of all React components: pages, layout, kanban board, worker cards, run console, config forms, and shared UI primitives. |
| Development Guide | Environment setup, all make targets and pnpm scripts, test conventions (real SQLite DB, no module mocking), coverage floors, Biome lint rules, and contribution guidelines. |
| Source Tree | Annotated directory listing: src/app/, src/server/daemon/, src/server/workers/, src/db/, src/types/, src/lib/, harness/, e2e/, and top-level config files. |
| Feature Docs | Per-feature deep dives in docs/features/: intake, implementation, shipping, console, repo view, PR review gate, verification, multi-repo, runs, run reports, internal issues, agents, doc editing, feature docs, and multi-harness. |