claude-patrol

# claude-patrol

**An autonomous task pipeline for Claude Code.**

Not a session manager. Not a swarm framework. A human-in-the-loop pipeline that finds what to fix, queues it, executes it safely, and waits for your review.

```
Scout ──> Ideas ──> Queue ──> Execute ──> Review ──> Approve ──> Merge ──> Done
  AI finds    auto-queue     claude -p    staging     you        safe       learn
  tasks       promotes       runs it      gate        decide     merge      from it
```

## What makes this different

Most Claude Code orchestrators manage **sessions** or coordinate **swarms**. claude-patrol is an **autonomous task pipeline** — it discovers work, executes it with safety rails, and learns from outcomes.

| Feature | claude-patrol |
|---------|:---:|
| Auto task discovery (Scout) | Y |
| Auto-queue promotion | Y |
| Full pipeline (scan to merge, with human review) | Y |
| Staging gate (pre-commit validation) | Y |
| Policy + allowed_paths enforcement | Y |
| Learning loop (meta.md) | ~ |
| Web dashboard | Y |
| Diff review in browser | Y |

## How it works

### Scout — finds tasks automatically

```bash
node dispatcher.mjs --scan my-app
```

Scout analyzes your codebase and generates task files — small, safe improvements like adding tests, removing dead code, fixing type issues. Each task includes confidence scores, impact ratings, and scoped file permissions.

### Auto-queue — promotes safe tasks

Tasks that meet all safety criteria (small scope, high confidence, low risk) are automatically promoted from `ideas/` to `queue/`. Everything else waits for your review.

### Execute — runs with guardrails

```bash
node dispatcher.mjs
```

Picks a task from the queue, creates a branch, and runs `claude -p` with the task as the prompt. Before committing, the **Staging Gate** validates:

- All changed files are within `allowed_paths`
- No files touch `forbidden_paths`
- Violations → changes discarded, task marked failed

### Review & Merge

```bash
node dispatcher.mjs --merge
```

Approved tasks are merged to your default branch. Tests run before merge completes. Push is never automatic — you decide when to push.

### Dashboard

```bash
node dispatcher.mjs --serve
# Open http://localhost:7700
```

Browser-based dashboard for managing the task pipeline:

- **Scan** — configure and launch Scout with filters (task kind, target directory, confidence threshold)
- **Execute** — pick tasks, preview details, dry-run option
- **Merge** — select tasks, toggle test execution
- **Review** — click any task to see details, diff, approve/reject inline
- **Projects** — add/edit/delete project configurations

## Quick start

### 1. Install

```bash
git clone https://github.com/Tacky7788/claude-patrol.git
cd claude-patrol
npm install
```

### 2. Configure a project

```bash
cp projects.example.json projects.json
```

Edit `projects.json`:

```json
{
  "my-app": {
    "path": "/absolute/path/to/your/project",
    "test_command": "npm test",
    "test_cwd": "."
  }
}
```

> **Prerequisite:** The `claude` CLI must be installed and authenticated before using claude-patrol. See [Requirements](#requirements).

### 3. Run

Use it from the terminal, or open the dashboard in your browser.

**CLI:**

```bash
# Scan project for task ideas
node dispatcher.mjs --scan my-app

# Check current pipeline state
node dispatcher.mjs --status

# Promote an idea to queue
node dispatcher.mjs --promote 004

# Execute the next queued task
node dispatcher.mjs

# Approve a reviewed task
node dispatcher.mjs --approve 004

# Merge approved tasks into default branch
node dispatcher.mjs --merge

# Dry run (no actual changes)
node dispatcher.mjs --dry-run
```

**Dashboard:**

```bash
node dispatcher.mjs --serve
# Open http://localhost:7700
```

The dashboard gives you everything the CLI does, plus:
- Visual pipeline overview
- Task details with diff viewer
- One-click scan/execute/merge with configuration forms
- Project management (add/edit/delete)

## Architecture

```
claude-patrol/
  dispatcher.mjs       # Core engine (scan, execute, merge, HTTP server)
  dashboard.html       # Web UI (single file, no build step)
  policy.md            # Safety rules and constraints
  task.schema.md       # Task file format specification
  meta.md              # Learning data (manually maintained)
  projects.json        # Your project configurations (gitignored)
  projects.example.json
  ideas/               # Scout-generated task candidates
  queue/               # Tasks ready for execution
  review/              # Completed tasks awaiting review
  approved/            # Reviewed and approved tasks
  done/                # Successfully merged tasks
  rejected/            # Rejected tasks (used for learning)
  blocked/             # Tasks waiting on external input
```

### Task lifecycle

```
Scout generates ──> ideas/
                      │
            auto-queue or manual promote
                      │
                    queue/
                      │
              dispatcher picks ──> creates branch ──> claude -p executes
                      │
              staging gate validates
                    /     \
                pass      fail (changes discarded)
                  │
               review/
                /    \
           approve   reject
              │        │
          approved/  rejected/
              │        └── learning data
           merge
              │
            done/
              └── learning data
```

### Safety model

- **allowed_paths** — tasks can only modify specified files
- **forbidden_paths** — hard blocklist (config, env, etc.)
- **Staging Gate** — pre-commit validation via `git diff` + `git ls-files --others`
- **Violation response** — `git checkout -- . && git clean -fd` (full discard)
- **Lock file** — single execution at a time
- **No auto-push** — merge is local only, you push when ready

### Learning loop

`meta.md` is a manual log where you can record patterns from completed and rejected tasks. This data is stored for future tuning and planned Scout integration.

Automatic learning (auto-updating meta.md and feeding it into Scout) is on the [roadmap](#roadmap).

## Requirements

- **Node.js 18+**
- **Git**
- **Claude Code CLI** — Install via `npm install -g @anthropic-ai/claude-code` ([docs](https://docs.anthropic.com/en/docs/claude-code)). Requires an Anthropic API key or Claude Pro/Max subscription.

> **Note:** claude-patrol uses `claude -p --allowedTools` to restrict Claude to only the tools each stage needs. Scout runs read-only (`Read,Glob,Grep`). Execute allows file editing and test commands. No blanket permission bypass is used.

## Configuration

### Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `7700` | Dashboard server port |
| `CLAUDE_MODEL` | `sonnet` | Claude model for task execution |

```bash
# Example: use port 3000 with opus model
PORT=3000 CLAUDE_MODEL=opus node dispatcher.mjs --serve
```

### policy.md

Define safety rules, forbidden operations, and review requirements. See the included `policy.md` for the full specification.

### Task format

Tasks use YAML frontmatter + Markdown body. See `task.schema.md` for the complete schema or `examples/sample-task.md` for a quick reference.

## Security

claude-patrol uses `claude -p --allowedTools` to grant Claude only the permissions each stage needs:

| Stage | Allowed Tools | Why |
|-------|--------------|-----|
| **Scout** (scan) | `Read, Glob, Grep` | Read-only codebase analysis |
| **Execute** (task) | `Read, Edit, Write, Bash(npm test *), Bash(npx *), Bash(node *)` | File editing + test execution |

No blanket permission bypass (`--dangerously-skip-permissions`) is used.

**Additional safety layers:**

- Each task declares `allowed_paths` — only these files can be modified
- `forbidden_paths` blocks sensitive files (config, env, credentials)
- The **Staging Gate** validates all changes via `git diff` before committing
- Any violation → a

[truncated…]