Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@a5c-ai/babysitter-breakpoints) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Breakpoint Manager

Lightweight breakpoint manager with API, queue worker, and web UI.

Requirements

Node.js 18+

Setup

npm install
npm run init:db

Run (dev)

npm run dev

Run (installed CLI)

breakpoints run

Or run separately:

npm run start:api
npm run start:worker

Configuration

Environment variables:

PORT (default 3000)
DB_PATH (default data/breakpoints.db)
REPO_ROOT (default repo root)
AGENT_TOKEN (optional)
HUMAN_TOKEN (optional)
WORKER_POLL_MS (default 2000)
WORKER_BATCH_SIZE (default 10)

API Examples

Create breakpoint (agent):

curl -X POST http://localhost:3000/api/breakpoints \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{"agentId":"agent-1","title":"Need review","payload":{"summary":"check this"},"tags":["review"],"ttlSeconds":3600}'

Check status:

curl http://localhost:3000/api/breakpoints/<id>/status

Release with feedback (human):

curl -X POST http://localhost:3000/api/breakpoints/<id>/feedback \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HUMAN_TOKEN" \
  -d '{"author":"reviewer","comment":"Looks good","release":true}'

Breakpoint Context Payload

To enable context rendering in the UI, include a context.files array in the breakpoint payload:

{
  "context": {
    "runId": "run-...",
    "files": [
      { "path": "docs/plan.md", "format": "markdown" },
      { "path": "api/routes.js", "format": "code", "language": "javascript" }
    ]
  }
}

The API serves file content via:

GET /api/breakpoints/:id/context?path=path/to/file

Only allowlisted extensions are served, and the file must be listed in the breakpoint payload.

Web UI

Open http://localhost:3000 and provide the human token in the UI.

Install the babysitter-breakpoint skill

breakpoints install-skill

Defaults to global Codex install. Options:

breakpoints install-skill --target codex --scope global
breakpoints install-skill --target codex --scope local
breakpoints install-skill --target claude --scope global
breakpoints install-skill --target claude --scope local
breakpoints install-skill --target cursor --scope global
breakpoints install-skill --target cursor --scope local

Global targets use CODEX_HOME or ~/.codex for Codex, and ~/.claude or ~/.cursor for Claude/Cursor. Local installs write to .codex/skills, .claude/skills, or .cursor/skills under the repo root. Restart the app after install.

When installed from npm, the skill is bundled at .codex/skills/babysitter-breakpoint/ inside the package and copied to the target location by breakpoints install-skill.

Breakpoint CLI (agent-friendly)

Create a breakpoint:

breakpoints breakpoint create \
  --question "Approve process + inputs + main.js?" \
  --run-id run-123 \
  --title "Approval needed" \
  --file ".a5c/runs/run-123/artifacts/process.md,markdown" \
  --file ".a5c/runs/run-123/inputs.json,code,json" \
  --file ".a5c/runs/run-123/code/main.js,code,javascript"

Wait for release (prints full details when released):

breakpoints breakpoint wait <id> --interval 3

Notes

Tags are stored as JSON in SQLite; tag filtering uses a simple string match.
The queue worker processes TTL expiration jobs; notification jobs are stubbed.