SpareCrow - Make It Count

sparecrow is a CLI tool and background daemon that monitors your Claude Code subscription usage and automatically dispatches queued tasks against your repositories when spare capacity is detected. Stop leaving your Claude Pro/Team quota on the table — put it to work.

How It Works

1. sparecrow authenticates using your existing Claude Code OAuth token (no extra credentials needed).
2. A background daemon polls Claude's usage metrics on a configurable interval.
3. When usage is below your threshold, it picks the next task from your queue and runs claude against a target repository with a specified prompt template.
4. Results are logged to a daily-rotated audit log and available via sparecrow report.

Requirements

• Node.js >= 22 — nodejs.org
• Claude Code — must be installed and authenticated (claude login should have been run at least once)
• Docker or Podman (optional) — required only for container-isolated task execution

Installation

npm install -g sparecrow

Verify:

sparecrow --version

Then run the interactive setup wizard:

sparecrow onboard

Getting Started

Run the interactive setup wizard:

sparecrow onboard

This will:

1. Detect your claude binary and validate your auth token
2. Let you configure a usage trigger threshold
3. Pick a prompt template (or write your own)
4. Register a target repository
5. Optionally install and start the background daemon as a system service

Quick Start

# Install
npm install -g sparecrow

# Run the interactive setup wizard
sparecrow onboard

# Add a task to the queue
sparecrow queue add --template code-review --target /path/to/repo

# Start the daemon
sparecrow daemon start

# Check status
sparecrow status

# View execution history
sparecrow logs

Commands

Global flags

These flags work with all commands:

| Flag | Description | |------|-------------| | --json | Machine-readable JSON output | | --quiet | Suppress non-essential output | | --config <path> | Override the default config file location | | --version | Show version number | | --help | Show command help |

Onboarding

| Command | Description | |---------|-------------| | sparecrow onboard | Interactive setup wizard (alias: sparecrow init) |

The wizard walks you through Claude Code detection, authentication, trigger thresholds, template selection, container detection, repository targeting, and optional daemon installation. Automatically rolls back on failure.

Status & Monitoring

| Command | Description | |---------|-------------| | sparecrow status | Show daemon health, usage level, queue depth, and recent activity | | sparecrow doctor | Run diagnostic health checks | | sparecrow report | Show the most recent execution summary (utilization, ROI, tasks completed) |

sparecrow status --all expands all cards to full detail. sparecrow doctor --verbose shows per-check timing and failure details.

Daemon Management

| Command | Description | |---------|-------------| | sparecrow daemon start | Start the background daemon | | sparecrow daemon stop | Stop the daemon (graceful SIGTERM, forced SIGKILL after timeout) | | sparecrow daemon restart | Restart the daemon (or start if not running) | | sparecrow daemon reload | Reload config without restarting | | sparecrow daemon status | Show daemon process state and active task | | sparecrow daemon install | Install as a system service (systemd on Linux, launchd on macOS) | | sparecrow daemon uninstall | Uninstall the system service |

sparecrow daemon start --dry-run previews the effective config without starting. sparecrow daemon install --yes skips overwrite confirmation.

Task Queue

| Command | Description | |---------|-------------| | sparecrow queue list | List queued tasks (alias: sparecrow queue ls) | | sparecrow queue add | Add a task to the queue | | sparecrow queue remove <position> | Remove a task by position (--yes required in non-interactive mode) | | sparecrow queue clear | Clear all tasks (--yes required in non-interactive mode) | | sparecrow queue reorder move <from> <to> | Move a task from one position to another | | sparecrow queue pause | Pause task dispatch without stopping the daemon | | sparecrow queue resume | Resume task dispatch |

Adding tasks

# Using a built-in template
sparecrow queue add --template security-review --target /path/to/repo

# Using a custom prompt
sparecrow queue add --prompt "Review error handling" --target /path/to/repo

# With a custom timeout (minutes, 0 = no timeout)
sparecrow queue add --template code-review --target /path/to/repo --timeout 60

# Preview without modifying the queue
sparecrow queue add --template bug-hunter --target /path/to/repo --dry-run

Exactly one of --template or --prompt is required. --target must point to a valid git repository.

Timeout precedence: CLI --timeout flag > template timeout_minutes > config task_timeout_minutes > default (60 min).

Logs & History

| Command | Description | |---------|-------------| | sparecrow logs | View execution history from daily-rotated audit logs |

sparecrow logs                          # last 20 entries
sparecrow logs --count 50               # last 50 entries
sparecrow logs --since 7d               # entries from last 7 days
sparecrow logs --since 2026-02-23       # entries since a specific date
sparecrow logs --task my-task           # filter by task name
sparecrow logs --outcome failed         # filter by outcome (failed, success, retrying, quota)
sparecrow logs --failures               # shorthand for --outcome failed,retrying
sparecrow logs --verbose                # expanded detail per entry
sparecrow logs --task my-task --full    # full transcript without truncation
sparecrow logs --output <taskId>        # print full output for a specific task

Configuration

| Command | Description | |---------|-------------| | sparecrow config show | Print resolved config as a table (or JSON with --json) | | sparecrow config get <key> | Get a single config value (supports snake_case and camelCase keys) | | sparecrow config set <key> <value> | Set a config value (validates before persisting) | | sparecrow config validate | Validate config file against schema | | sparecrow config path | Show config and state directory paths | | sparecrow config edit | Open config in $EDITOR | | sparecrow config --reconnect | Re-authenticate with Claude Code |

Templates

| Command | Description | |---------|-------------| | sparecrow templates | List available built-in and custom prompt templates |

Four built-in templates are included:

| Template | Description | |----------|-------------| | security-review | Scan repo for vulnerabilities and hardcoded secrets | | code-review | Review for bugs, error-handling gaps, and code quality | | bug-hunter | Search for edge cases, logic flaws, and likely defects | | test-generation | Identify untested paths and generate candidate tests |

Custom templates can be defined in your config file under the tasks key.

Container Execution

| Command | Description | |---------|-------------| | sparecrow container test | Validate container runtime end-to-end (Docker/Podman) | | sparecrow container cleanup | Remove orphaned sparecrow-managed containers |

sparecrow container test --verbose shows container logs and detailed timing. sparecrow container cleanup --yes skips confirmation.

To enable container-isolated execution, set execution_backend: container in your config. Sparecrow auto-detects Docker or Podman, or you can specify container.runtime: docker or container.runtime: podman.

Other

| Command | Description | |---------|-------------| | sparecrow completions | Print shell completion script (bash/zsh) |

Configuration

Config is stored in the platform-appropriate location — never hardcoded:

| Platform | Config file | State / logs | |----------|-------------|--------------| | Linux | ~/.config/sparecrow/config.yaml | ~/.local/state/sparecrow/ | | macOS | ~/Library/Application Support/sparecrow/config.yaml | ~/Library/Application Support/sparecrow/ |

Run sparecrow config path to see the exact paths on your system.

Config file reference

polling_interval: 300                    # seconds between usage checks (60–3600, default: 300)
log_retention_days: 30                   # audit log retention (1–365, default: 30)
task_timeout_minutes: 60                 # per-task timeout (0 = no limit, default: 60)
last_summary_enabled: false              # persist summary after each dispatch

provider:
  name: claude-code
  claude_path: /path/to/claude           # optional: explicit path to claude binary
  allow_dangerously_skip_permissions: false
  execution_backend: direct              # 'direct' or 'container'
  container:                             # only used when execution_backend: container
    runtime: auto                        # 'auto', 'docker', or 'podman'
    image: node:lts-slim                 # container image
    memory_limit_mb: 512                 # memory limit (64–65536)
    cpu_limit: 1.0                       # CPU limit (0.1–128.0)
    network_mode: bridge                 # 'bridge', 'none', or 'host'
    mount_claude_config: true            # mount .claude dir for OAuth credentials
    mount_claude_binary: false           # mount claude binary from host
    claude_binary_path: /path/to/claude  # explicit path if mount_claude_binary: true
    fallback: none                       # fallback strategy on container failure

trigger:
  threshold_percentage: 80               # dispatch when usage < this % (1–100)
  time_before_reset_minutes: 60          # minutes before reset window (1–1440)
  require_reset_window: true             # enforce reset window check

tasks:                                   # custom task templates
  - name: my-custom-task
    prompt: "Review this repo for..."
    target_path: /path/to/repo
    timeout_minutes: 60                  # optional per-task timeout

All keys use snake_case in YAML and are transformed to camelCase internally.

State directory contents

daemon.pid              — daemon PID (while running)
daemon-status.json      — last known daemon state
queue.json              — persisted task queue
last-summary.json       — most recent execution summary
task-outputs/           — task output files (by task ID)
logs/audit-YYYY-MM-DD.jsonl  — daily-rotated append-only audit log

Development

git clone https://github.com/WobbitCode/sparecrow.git
cd sparecrow
npm install

Run in development mode (no build step)

npm run dev -- status          # equivalent to: sparecrow status
npm run dev -- onboard

Build

npm run build          # tsup → dist/

Tests

npm test               # unit tests + coverage report (>= 70% required)
npm run test:watch     # watch mode
npm run test:integration  # integration tests
npm run test:e2e       # end-to-end tests (requires Docker)

Lint & format

npm run lint           # oxlint (fast Rust-based linter)
npm run format         # prettier --write src/
npm run format:check   # prettier --check (CI-safe)
npm run typecheck      # tsc --noEmit

JSON Output

All commands support --json for machine-readable output. The envelope is consistent:

{
  "ok": true,
  "data": { },
  "error": null
}

On error:

{
  "ok": false,
  "data": null,
  "error": { "code": "ERROR_CODE", "message": "User-facing message" }
}

Contributing

Contributions are welcome! Here's how to get involved:

Reporting bugs

Open an issue at github.com/WobbitCode/sparecrow/issues. Include:

• Your OS and Node.js version (node --version)
• Steps to reproduce
• Actual vs. expected behaviour
• Any relevant output from sparecrow doctor --json

Submitting a pull request

1. Fork the repository and create a branch from main.
2. Follow the module dependency DAG — lower modules never import from higher ones.
3. Match the existing conventions:
   • Files: kebab-case.ts
   • Functions/variables: camelCase; types: PascalCase; constants: UPPER_SNAKE_CASE
   • Every .ts file starts with a single-line JSDoc comment describing its purpose
   • ESM imports use the .js extension: import { X } from './module.js'
4. Write tests for your change. Each test must be fully isolated (beforeEach/afterEach, no shared mutable state). Coverage must remain >= 70%.
5. Run the full check suite before opening a PR:

   npm run typecheck && npm run lint && npm run format:check && npm test

6. Open a pull request against main with a clear description of what and why.

Module structure

Import direction is strictly enforced (lower → higher only):

types → errors → utils → config → templates → platform → providers → trigger → queue → daemon → cli/ui

If a type is needed by a lower module, move it to src/types/.

Error handling

• Always throw ScrowError with a typed ErrorCode — never throw new Error(...) or throw strings.
• Catch only at CLI command boundaries and the daemon top-level loop.
• Never log tokens, credentials, or secrets at any log level.

License

MIT