npm package: @scriptgun/workerc
Description: Claude Code session management CLI — commands, hooks, and progress tracking
Latest version: 0.13.0

# workerc

Claude Code session management — commands, hooks, agents, and progress tracking.

workerc adds structured session workflows to any project using [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It installs slash commands for managing work sessions, hooks that enforce progress tracking and code quality, agents for specialized tasks, and a progress file system that persists context across sessions.

## Install

```bash
npx @scriptgun/workerc init
```

Non-interactive (CI/scripts):

```bash
npx @scriptgun/workerc init --yes
```

This interactively sets up:

- **22 slash commands** in `.claude/commands/workerc/`
- **Up to 12 hooks** in `.claude/hooks/` (based on detected tools)
- **12 agents** in `.claude/agents/` (custom agents preserved on re-init)
- **Config file** at `.claude/workerc.json` (runner, lint, types, format, test commands)
- **Settings** in `.claude/settings.local.json` or `.claude/settings.json`
- **Progress directory** at `.claude/progress/`
- **Optional CLAUDE.md** scaffold

Package runner auto-detected from lockfiles (bun/pnpm/yarn/npm) with override option. Test frameworks auto-detected (vitest, jest, playwright) with manual override.

## Commands

### Session starters (one question, full pipeline)

| Command | Pipeline |
|---------|----------|
| `/workerc:feat` | researcher(sidecar) → architect → executor → reviewer → cleaner → reviewer(final) |
| `/workerc:feat-tdd` | researcher(sidecar) → architect → tester(RED) → executor(GREEN) → tester(verify) → reviewer → cleaner → reviewer(final) |
| `/workerc:refactor` | architect → cleaner → reviewer → cleaner(final pass) → reviewer(final) |
| `/workerc:refactor-tdd` | architect → tester(characterization) → cleaner → tester(verify) → reviewer → cleaner(final pass) → reviewer(final) |
| `/workerc:fix` | debugger → architect → executor → tester → reviewer → cleaner → reviewer(final) |
| `/workerc:fix-tdd` | debugger → architect → tester(RED) → executor(GREEN) → tester(verify) → reviewer → cleaner → reviewer(final) |
| `/workerc:perf` | optimizer → architect → executor → tester → reviewer → cleaner → reviewer(final) |
| `/workerc:perf-tdd` | optimizer → architect → tester(benchmark RED) → executor(GREEN) → tester(verify) → reviewer → cleaner → reviewer(final) |
| `/workerc:style` | architect → styler → reviewer → cleaner → reviewer(final) |
| `/workerc:style-tdd` | architect → tester(component RED) → styler(GREEN) → tester(verify) → reviewer → cleaner → reviewer(final) |

### Session lifecycle

| Command | Description |
|---------|-------------|
| `/workerc:resume` | Resume an unclaimed session |
| `/workerc:done` | Mark session complete |
| `/workerc:handoff` | Pause session with auto-generated handoff notes |
| `/workerc:abort` | Abandon session |
| `/workerc:commit` | Stage and commit with auto-generated message |
| `/workerc:checkpoint` | Create git save point for rollback |

### Info & config

| Command | Description |
|---------|-------------|
| `/workerc:list` | List all progress files with status |
| `/workerc:status` | Show current session progress |
| `/workerc:reinit` | Re-run init (reconfigure linter, types, test frameworks) |
| `/workerc:update` | Update workerc to latest version |

## Hooks

### Always installed

- **post-edit-tracker.sh** — Auto-claims pending sessions on first edit. Auto-tracks edited files. Tiered freshness enforcement (30s advisory, 120s block).
- **session-start-startup.sh** — Injects active progress context, agent delegation rules, and zero-tolerance quality rules on every session start.
- **session-start-compact.sh** — Re-injects session context after conversation compaction. Includes context capacity warnings.
- **workerc-check-update.cjs** — Checks npm registry for new workerc versions in background (cached 24h).
- **workerc-statusline.cjs** — Shows model, current task, directory, context usage bar, and handoff warning at 85%+.
- **workerc-find-session.sh** — Locates active progress file for a session ID (used by commands).
- **workerc-list.sh** — Deterministic progress file listing (used by `/workerc:list`).
- **workerc-status.sh** — Deterministic status display (used by `/workerc:status`).

### Optional (auto-detected)

- **post-edit-quality.sh** — Consolidated quality gate. Runs configured lint using its declared strategy (`scope: file` or `scope: project`), filters configured type-check output to the edited file, and runs configured formatters when enabled. Auto-detected from Biome, oxlint, ESLint, TypeScript (`tsc`), and Prettier (formatter skipped if Biome is active).

## Agents

### Pipeline agents

| Agent | Role |
|-------|------|
| **researcher** | Web search, fact-finding, comparisons (min 5 searches) |
| **architect** | Deep reasoning plus concrete implementation plans written into the spec |
| **executor** | Implements spec, verifies configured lint strategy and type checks after each file |
| **reviewer** | Stub detection, spec compliance, configured lint per declared strategy, configured type checks, configured tests as final regression gate, dead code |
| **tester** | Writes and runs tests — common cases, edge cases, type contracts |

### Utility agents

| Agent | Role |
|-------|------|
| **debugger** | Scientific method bug investigation |
| **cleaner** | Runs a behavior-preserving clean-code sweep on touched code and the final cleanup pass after review |
| **optimizer** | Performance analysis — fewer RTs, better batching |
| **finder** | Fast codebase search (Haiku model) |
| **commit** | Single-line conventional commits |
| **styler** | UI/CSS — layouts, spacing, responsive, accessibility |
| **browser** | Web automation via Playwright MCP |

## How it works

1. Run a session starter: `/workerc:feat`, `/workerc:fix`, or `/workerc:refactor`
2. Describe what you want in one sentence
3. workerc creates the session and runs the full agent pipeline automatically
4. Progress frontmatter tracks `pipeline_stage`, `last_completed_agent`, `review_status`, and `cleanup_status` so resume can distinguish primary review, cleanup, and final verification
5. The tracker hook logs edited files and enforces progress updates
6. The statusline shows your current task, model, and context usage
7. Use `/workerc:commit` to commit, `/workerc:done` to complete

Progress files persist across sessions — use `/workerc:resume` to pick up where you left off.

## Re-running init

`workerc init` is idempotent. Re-init updates all commands, hooks, agents, and `workerc.json` without duplicating settings. Custom agents are preserved.

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for release history.

## License

MIT