BlockSpool CLI - Continuous codebase improvement tool
npm install @blockspool/cliZero-config continuous improvement tool. Works locally with any git repository.
``bashInstall globally
npm install -g @blockspool/cli
Prerequisites
Run
blockspool solo doctor to check all prerequisites:| Requirement | Purpose | Install |
|-------------|---------|---------|
| Node.js 18+ | Runtime | nodejs.org |
| Git | Version control | git-scm.com |
| Claude CLI | Execute tickets | claude.ai/code |
| GitHub CLI | Create PRs (optional) | cli.github.com |
Commands
$3
Initialize BlockSpool in your repository. Creates .blockspool/ directory with:
- config.json - Configuration (auto-detects QA commands)
- state.sqlite - Local database$3
Scan codebase for improvement opportunities:
- Code quality issues
- Security vulnerabilities
- Performance optimizations
- Test coverage gaps$3
Convert proposals to tickets. Examples:
- blockspool solo approve 1 - Approve proposal #1
- blockspool solo approve 1-3 - Approve proposals 1, 2, and 3
- blockspool solo approve all - Approve all proposals$3
Execute a ticket using Claude Code CLI:
- Creates a branch for changes
- Runs QA commands (if configured)
- Commits changes
- --pr flag creates a GitHub PR$3
Show current state:
- Active tickets
- Recent runs
- QA results$3
Check prerequisites and environment health:
- Git installation
- Claude CLI installation and auth
- GitHub CLI installation and auth
- Node.js version
- SQLite native module
- Directory permissions$3
Steer a running auto session with live hints:
- blockspool solo nudge "focus on auth" — Add a hint
- blockspool solo nudge --list — Show pending hints
- blockspool solo nudge --clear — Clear all hintsHints are consumed in the next scout cycle. In continuous mode, you can also type hints directly into stdin.
$3
Run QA commands manually:
- Uses commands from .blockspool/config.json
- Records results in databaseConfiguration
Configuration lives in
.blockspool/config.json:`json
{
"version": 1,
"qa": {
"commands": [
{ "name": "typecheck", "cmd": "npm run typecheck" },
{ "name": "lint", "cmd": "npm run lint" },
{ "name": "test", "cmd": "npm test" }
],
"retry": {
"enabled": true,
"maxAttempts": 3
}
},
"spindle": {
"enabled": true,
"maxStallIterations": 5,
"tokenBudgetAbort": 140000
}
}
`$3
Auto-detected from package.json during solo init:
- typecheck / type-check - TypeScript checking
- lint - Linting
- test - Testing
- build - Build verification$3
BlockSpool automatically loads your project guidelines and injects them into every scout and execution prompt so agents respect your conventions.
File selection by backend:
| Backend | Primary | Fallback |
|---------|---------|----------|
| Claude |
CLAUDE.md | AGENTS.md |
| Codex | AGENTS.md | CLAUDE.md |Behavior:
- Auto-create: If no guidelines file exists, a baseline is generated from your
package.json (project name, TypeScript detection, test/lint/build commands, monorepo detection)
- Truncation: Content longer than 4000 characters is truncated with a [truncated] marker
- Refresh: During long runs, re-reads every N cycles (default 10, configurable)
- Format: Wrapped in XML tags in the promptConfigure in
.blockspool/config.json:`json
{
"auto": {
"guidelinesRefreshCycles": 10,
"autoCreateGuidelines": true,
"guidelinesPath": null
}
}
`| Setting | Default | Description |
|---------|---------|-------------|
|
guidelinesRefreshCycles | 10 | Re-read every N cycles (0 = disabled, still loaded once at start) |
| autoCreateGuidelines | true | Auto-create baseline file from package.json if none exists |
| guidelinesPath | null | Custom path relative to repo root (e.g. "docs/CONVENTIONS.md"). Set to false to disable guidelines entirely. null = default search. |$3
Prevents runaway agent execution:
- Oscillation: Detects add→remove→add patterns
- Stalling: Stops after N iterations without changes
- Repetition: Catches repeated output patterns
- Token Budget: Enforces context limitsPush Safety
BlockSpool records your
origin remote URL when you run solo init.
Every push and PR creation validates the current origin still matches.
SSH and HTTPS URLs for the same repo are treated as equivalent.If your origin changes (e.g., you switch from HTTPS to SSH), re-initialize:
blockspool solo init --force
Or edit
.blockspool/config.json directly: { "allowedRemote": "git@github.com:you/your-repo.git" }
Exit Codes
| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General failure |
| 2 | Spindle abort (agent loop detected) |
| 130 | Cancelled (Ctrl+C) |
Artifacts
Run artifacts are stored in
.blockspool/artifacts/:
- runs/ - Run summaries
- executions/ - Agent output logs
- diffs/ - Git diff snapshots
- violations/ - Scope violation details
- spindle/ - Spindle abort diagnosticsView artifacts with:
`bash
blockspool solo artifacts
blockspool solo artifacts --type runs
``Apache-2.0