workerc

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

workerc adds structured session workflows to any project using 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

npx @scriptgun/workerc init

Non-interactive (CI/scripts):

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.

Writer pipeline

/workerc:write produces grounded, style-consistent documents by forcing sources before prose. Every factual claim is traceable to a source span; fabrication is caught by deterministic checks before any LLM review runs.

Start a session

/workerc:write blog "the complete guide to AI document extraction" sources/blog-119/

The three positionals are optional — omit any and the command asks interactively. Supported types: blog, legal, review, social, reddit, email, docs, review-reply, post-reply, freeform.

Pipeline

sourcer → outliner → writer → fact-checker (deterministic + LLM sample) → stylist → reviewer → cleaner

One approval gate after sourcing (before outline). Writer iterations are capped at 2. Reviewer failures route back to the right agent. Progress tracks in .claude/progress/{slug}.md — /workerc:resume works unchanged.

Profile directories

Global (seeded by workerc init, user-editable):
  .claude/writer/profiles/{type}/

Per-project override (wins when active project matches):
  {projectRoot}/.project/writer/profiles/{type}/

Resolution: per-project override wins by exact {type} match; falls back to global.

Profile shape (six files per type)

profile.toml        name, description, wordCountTarget, writerModel, requiresResearcher, agents
template.md         structural skeleton with {{placeholder}} sections the writer fills
style.md            voice, tone, banned phrases, sentence-length guidance
validators.md       deterministic checks: ban-phrase, require-section, max-em-dashes, etc.
reviewer.md         checklist the writer-reviewer walks before approving (- [ ] items)
sources-schema.md   source kinds required before the pipeline runs (path, cardinality, description)

Scaffold a new profile

/workerc:write:profile-new my-type           # global
/workerc:write:profile-new my-type --project # per-project override

Copies _skeleton/ into the target directory, sets name = "my-type" in profile.toml, and exits. Edit the six files, then run /workerc:write my-type.

Session output layout

.claude/writer/sessions/{slug}/
  sources/            user-populated source files (mirrors sources-schema.md structure)
  profile.lock.json   which profile resolved and from where
  sources.manifest.md sourcer output — one line per file: path | kind | sha256 | summary
  outline.md          outliner output
  draft.md            writer output with inline [src:path#L1-L10] citation markers
  citations.json      sidecar: every marker mapped to source span + claim text
  fact-check.report.md
  style.report.md
  final.md            style-corrected, reviewer-approved, cleaner-polished

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 for release history.

License

MIT