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

This interactively sets up:

• 14 slash commands in .claude/commands/workerc/
• 7 hooks in .claude/hooks/
• 4 agents in .claude/agents/ (custom agents preserved on re-init)
• Settings in .claude/settings.local.json or .claude/settings.json
• Progress directory at .claude/progress/
• Optional CLAUDE.md scaffold

Commands

| Command | Description | |---------|-------------| | /workerc:new | Start a new work session with optional spec | | /workerc:plan | Refine spec with codebase context — turns intent into blueprint | | /workerc:resume | Resume an unclaimed session | | /workerc:status | Show current session progress | | /workerc:list | List all progress files with status | | /workerc:scope | Update spec scope mid-session | | /workerc:commit | Stage and commit with auto-generated message | | /workerc:review | Review work against spec | | /workerc:handoff | Pause session with handoff notes | | /workerc:done | Mark session complete | | /workerc:abort | Abandon session | | /workerc:debug | Investigate a bug with scientific method debugging | | /workerc:checkpoint | Create a save point for safe rollback | | /workerc:update | Update workerc to latest version |

Hooks

Always installed

• post-edit-tracker.sh — Blocks edits if no progress file is active. Auto-claims pending sessions on first edit. Auto-tracks edited files. Enforces 15s freshness.
• session-start-compact.sh — Re-injects session context after conversation compaction. Restores progress file, spec, and file list.
• session-start-startup.sh — Injects active progress context on every session start, not just compaction.
• workerc-check-update.cjs — Checks npm registry for new workerc versions in background. Caches result for statusline.
• workerc-statusline.cjs — Shows model, current task, directory, and context usage bar with color thresholds.

Optional (auto-detected)

• post-edit-lint.sh — Runs linter on every file edit. Detected tools: Biome, ESLint.
• post-edit-types.sh — Runs type checker on every file edit. Detected tools: TypeScript (tsc).

Agents

| Agent | Description | |-------|-------------| | browser | Web browsing and automation via Playwright MCP | | commit | Single-line git commits (type(scope?): message) | | finder | Fast codebase search using Haiku model | | debugger | Scientific method debugging with persistent debug sessions |

How it works

1. Run /workerc:new to start a session — creates a progress file and optional spec
2. Run /workerc:plan to refine the spec with real codebase context
3. The tracker hook auto-claims the session on your first file edit
4. As you work, the tracker logs edited files and enforces regular progress updates
5. The statusline shows your current task, model, and context usage
6. Use /workerc:commit to commit, /workerc:review to check against spec
7. Use /workerc:handoff to pause or /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. Running it again updates all commands, hooks, and agents without duplicating settings entries. Custom agents you've added to .claude/agents/ are preserved.

Changelog

See CHANGELOG.md for release history.

License

MIT