{"id":48146873,"url":"https://github.com/turqoisehex/cc-sentinel","last_synced_at":"2026-04-04T17:01:18.664Z","repository":{"id":346086169,"uuid":"1188466923","full_name":"turqoisehex/cc-sentinel","owner":"turqoisehex","description":"Governance infrastructure for Claude Code — hooks, agents, and workflows that prevent the failure modes autonomous coding sessions actually hit","archived":false,"fork":false,"pushed_at":"2026-03-29T18:36:28.000Z","size":488,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-29T20:42:47.534Z","etag":null,"topics":["ai-agents","ai-coding","automation","bash","claude-code","cli","code-quality","developer-tools","governance","hooks","testing","verification","workflow"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/turqoisehex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T05:36:52.000Z","updated_at":"2026-03-29T18:36:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/turqoisehex/cc-sentinel","commit_stats":null,"previous_names":["turqoisehex/cc-sentinel"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/turqoisehex/cc-sentinel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turqoisehex%2Fcc-sentinel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turqoisehex%2Fcc-sentinel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turqoisehex%2Fcc-sentinel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turqoisehex%2Fcc-sentinel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/turqoisehex","download_url":"https://codeload.github.com/turqoisehex/cc-sentinel/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turqoisehex%2Fcc-sentinel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31407381,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-coding","automation","bash","claude-code","cli","code-quality","developer-tools","governance","hooks","testing","verification","workflow"],"created_at":"2026-04-04T17:01:04.397Z","updated_at":"2026-04-04T17:01:18.623Z","avatar_url":"https://github.com/turqoisehex.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cc-sentinel\n\n[![CI](https://github.com/turqoisehex/cc-sentinel/actions/workflows/ci.yml/badge.svg)](https://github.com/turqoisehex/cc-sentinel/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/github/license/turqoisehex/cc-sentinel)](LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/turqoisehex/cc-sentinel?style=social)](https://github.com/turqoisehex/cc-sentinel)\n\n**Governance infrastructure for Claude Code.** Hooks, agents, and workflows that prevent the failure modes autonomous coding sessions actually hit.\n\n## The Problem\n\nClaude Code is powerful out of the box. But long, autonomous sessions surface real failure modes that no amount of prompting fixes:\n\n| Failure Mode | What Happens | Without cc-sentinel | With cc-sentinel |\n|---|---|---|---|\n| **Context loss** | After compaction, Claude forgets what it was doing, repeats work, or contradicts earlier decisions | Hours of wasted compute, inconsistent output | Pre-compact hook saves state; post-compact hook restores it. Sessions survive compaction. |\n| **Work deferral** | Claude writes \"TODO: implement later\" or \"will add in next step\" and never returns | Incomplete features shipped as \"done\" | Anti-deferral hook detects deferral language in every file write and warns immediately. |\n| **False completion** | Claude claims a task is done without verifying | Bugs discovered in production, not development | Stop hook blocks completion claims without verification squad evidence on disk. |\n| **Governance drift** | Claude edits its own rules, CLAUDE.md, or config files mid-session | Guardrails silently disabled | File-protection hook blocks writes to protected files. Override requires explicit authorization marker. |\n| **Silent compaction** | Context window fills with no warning; state is lost before it can be saved | Unrecoverable mid-task failure | Visual status bar + 5 graduated warnings at 50/65/75/85/92%. |\n| **Commit quality** | Large diffs committed without review; tests skipped; formatting inconsistent | Technical debt accumulates per-session | Code commits gated: two adversarial agents review the diff, tests auto-run, formatter auto-runs. Doc-only and config changes pass through lightweight checks. |\n| **Agent amnesia** | Subagents start with no knowledge of project conventions or current task state | Agents produce work that contradicts the session | Agent-file-reminder hook injects context. Channel system coordinates parallel agents via file signals. |\n\ncc-sentinel solves these with **hooks that enforce automatically** -- not rules that rely on Claude choosing to follow them.\n\n## How It Works\n\ncc-sentinel is a modular set of Claude Code hooks, skills, reference docs, agents, and templates. You install the modules you need. The installer is a conversation -- Claude Code reads your project and recommends what to install.\n\n```\nClaude Code: I see this is a Python/Django project with pytest. Here's what I recommend:\n\n  [x] Core (required) -- context loss prevention, anti-deferral, state management\n  [x] Context Awareness -- visual context meter in your status bar\n  [ ] Verification -- up to 5-agent verification squad before completion claims\n  [x] Commit Enforcement -- test gating, auto-format, diff review\n  [ ] Sprint Pipeline -- structured /1 through /5 workflow\n  [x] Governance Protection -- protect CLAUDE.md and config from mid-session edits\n  [x] Notification -- desktop alert when Claude finishes or needs input\n\nInstall these 5 modules? (Y/n)\n```\n\n### Beyond Code\n\ncc-sentinel's governance works for any Claude Code workflow, not just software engineering:\n\n- **Translation projects** -- Anti-deferral catches \"will revisit phrasing later.\" Verification squad audits consistency across documents. Context awareness prevents mid-chapter compaction.\n- **Research workflows** -- State files preserve literature review progress across sessions. Commit enforcement gates research notes through adversarial review. Sprint pipeline structures the research-to-synthesis arc.\n- **Data analysis** -- Channel system coordinates parallel analysis streams. Pre-compact hooks save intermediate results. Stop hook prevents premature \"analysis complete\" claims.\n\nIf Claude Code can do it, cc-sentinel can govern it.\n\n## Installation\n\n**Prerequisites:** Node.js, Git, jq, and Python 3. See [Platform Setup](#platform-setup) for one-command install per platform.\n\n**In any Claude Code session:**\n\n```\nInstall https://github.com/turqoisehex/cc-sentinel\n```\n\nClaude Code clones the repo and runs an interactive installer. The expected flow:\n\n1. **Detect** your OS, shell, terminal, and project type. Report findings.\n2. **Ask your use case** -- what you use Claude Code for (development, research, writing, etc.).\n3. **Present a problem→solution table** showing each failure mode and the module that solves it.\n4. **Present a module table** with recommendations. Always offer \"All modules\" as the first option.\n5. **Ask about global vs project install.** Recommend global for most users.\n6. **Run the installer** with the selected modules. Do not ask for confirmation after module selection -- just run it.\n7. **Offer deny rules** for binary/media file exclusions (conservative: block media/archives/binaries, keep images and PDFs readable).\n8. **Suggest plugins** that complement cc-sentinel (superpowers, context7, feature-dev).\n9. **Print a summary** of what was installed: modules, hooks, skills, status line, spawn config.\n10. **Tell the user to run `/self-test`** in their next session to validate.\n\n**Manual installation:**\n\n```bash\n# Clone\ngit clone https://github.com/turqoisehex/cc-sentinel.git ~/.claude/cc-sentinel\n\n# Install to current project\nbash ~/.claude/cc-sentinel/install.sh --modules \"core,context-awareness,verification\" --target project\n\n# Or install globally\nbash ~/.claude/cc-sentinel/install.sh --modules \"core,context-awareness\" --target global\n\n# Windows (PowerShell)\npowershell -File ~/.claude/cc-sentinel/install.ps1 -Modules \"core,context-awareness\" -Target project\n```\n\n## Modules\n\n### Core (required)\n\nPrevents the three most common failure modes: context loss, work deferral, and agent amnesia.\n\n| Hook | Event | What It Does |\n|---|---|---|\n| `anti-deferral.sh` | PreToolUse | Scans every file write for deferral language (\"TODO later\", \"will implement\", \"future sprint\"). Injects a warning into Claude's context requiring explicit developer approval before deferral. |\n| `session-orient.sh` | SessionStart | Injects CURRENT_TASK.md contents at session start so Claude has full context from turn one. |\n| `pre-compact-state-save.sh` | PreCompact | Last-chance hook before context compaction. Reminds Claude to write all in-progress state to CURRENT_TASK.md. |\n| `post-compact-reorient.sh` | SessionStart (compact) | After compaction, re-injects task state so Claude can resume without re-reading files. |\n| `agent-file-reminder.sh` | PreToolUse | Reminds agents to write results to files, not just return them in memory (which is lost after the agent exits). |\n| `auto-checkpoint.sh` | Stop, PreCompact | Auto-commits work-in-progress when a session ends or context compacts, preventing silent work loss. |\n\nAlso includes:\n- **CURRENT_TASK.md template** -- structured state file that survives compaction\n- **Channel template** -- for multi-agent parallel work\n- **Operator cheat sheet** -- quick reference for all skills\n- **`/self-test`** -- diagnostic command that validates your installation\n\n### Context Awareness\n\nVisual context window meter displayed in your Claude Code status bar. Graduated warnings fire as context fills, prompting Claude to save state before compaction hits.\n\n```\ncontext [████████████░░░░░░░░] 62%\n```\n\nThresholds trigger automatic reminders:\n- **50%** -- \"Documenting as you go?\"\n- **65%** -- \"Could a fresh session resume from your state files?\"\n- **75%** -- \"Document comprehensively and get cold-start ready. Continue working methodically until compaction at ~84%.\"\n- **85%** -- \"Commit all changes. State files must be current. Keep working.\"\n- **92%** -- \"Auto-compaction imminent. State files must be complete.\"\n\nThis benefits **Claude Code itself** as much as the user. Without context awareness, Claude has no way to know how full its context window is — it cannot sense compaction approaching. The graduated warnings give Claude actionable signals to save state, wrap up work units, and prepare for compaction before it happens. The user gets visibility too, but the primary consumer is Claude's own decision-making.\n\nAuto-detects terminal Unicode support. Falls back to ASCII (`#`/`-`) when the locale does not indicate UTF-8.\n\n**Windows support:** cc-sentinel includes the only known Windows-compatible version of cc-context-awareness. On macOS/Linux, you can choose between the bundled version or the [canonical repository](https://github.com/sdi2200262/cc-context-awareness).\n\n### Verification\n\nUp to 5-agent verification squad that independently audits work before any completion claim. Each agent has a different adversarial perspective:\n\n| Agent | What It Catches |\n|---|---|\n| **Mechanical Auditor** | Wrong file paths, constants, enum values, counts, performance issues -- anything greppable |\n| **Adversarial Reader** | Spec contradictions, hallucinated content, rule violations, regressions |\n| **Completeness Scanner** | Missing requirements, unassigned items, spec gaps |\n| **Dependency Tracer** | Missing migrations, untraced call sites, silent default changes |\n| **Cold Reader** | Semantic errors invisible to the author -- reads with zero context |\n\nThe `stop-task-check.sh` hook fires when Claude tries to stop, requiring verification evidence before allowing completion claims through. Self-attestation (\"I verified this\") is explicitly rejected -- the hook checks for actual squad output files on disk. The `comment-replacement.sh` hook silently strips stale inline comments (TODO, FIXME, HACK) from edited files.\n\nCommands: `/verify`, `/grill` (iterative self-challenge)\n\n### Commit Enforcement\n\nCode commits are gated: tests must pass, formatting must be clean, and two verification agents review the diff before it lands. Documentation-only and config changes pass through lightweight checks without full agent review.\n\n| Component | What It Does |\n|---|---|\n| `safe-commit.sh` | Runs tests (auto-detects: npm, pytest, cargo, go, flutter, make), blocks on failure |\n| `auto-format.sh` | Runs formatter (prettier, black, cargo fmt, dart format, gofmt) on every file write |\n| `channel_commit.sh` | Orchestrates: stage, verify, test, format, commit. The single public API for commits. |\n| `commit-adversarial.md` | Agent that reviews staged diff for logic errors, spec violations, regressions |\n| `commit-cold-reader.md` | Agent that reads staged diff with zero context -- flags anything broken or nonsensical |\n\nMulti-framework auto-detection: the commit hooks detect your project type from manifest files (`package.json`, `Cargo.toml`, `go.mod`, `pubspec.yaml`, `pyproject.toml`, `Makefile`) and run the appropriate test suite and formatter.\n\n**Single-terminal mode:** Works without a Sonnet listener. When no Sonnet heartbeat is detected, the system automatically falls back to local verification — no 5-minute hang, no manual flags needed.\n\nAlso supports **multi-channel coordination** for parallel Opus/Sonnet workflows via `SENTINEL_CHANNEL` environment variable.\n\n### Sprint Pipeline\n\nStructured workflow phases for complex features. Each phase has a skill:\n\n| Command | Phase | Purpose |\n|---|---|---|\n| `/1` or `/audit` | Audit | Assess current state, identify gaps |\n| `/2` or `/design` | Design | Brainstorm, spec, plan, classify tasks |\n| `/3` or `/build` | Build | Automated execution of classified plan |\n| `/4` or `/perfect` | Perfect | Quality pass, edge cases, polish |\n| `/5` or `/finalize` | Finalize | Verification squad, cleanup, completion |\n\n**Example workflow:**\n\n```\nYou: /2\nClaude: [Brainstorms with you, writes spec, creates implementation plan,\n         classifies tasks as Opus/Sonnet/Agent, adversarial plan review,\n         presents for your approval]\n\nYou: /3\nClaude: [Executes plan task by task. Commits at phase boundaries.\n         Two agents verify every commit. No manual intervention needed.]\n\nYou: /4\nClaude: [Reads everything fresh. Finds edge cases, inconsistencies,\n         quality issues. Fixes them. \"Scrap and rewrite\" pass.]\n\nYou: /5\nClaude: [Runs verification squad. Produces final report.\n         Cleans up session artifacts. Ready to ship.]\n```\n\nAdditional Sprint Pipeline commands: `/opus` (channel management), `/sonnet` (Sonnet dispatch), `/rewrite` (content rewrite pipeline), `/spawn` (multi-session launcher).\n\nCore utility commands (available without Sprint Pipeline): `/cold` (cold-start resume), `/cleanup` (session cleanup), `/status` (progress overview).\n\nRecommends complementary Claude Code plugins: superpowers, context7, feature-dev, pr-review-toolkit, claude-md-management, ralph-loop, claude-code-setup. The installer lists each plugin's purpose and install command -- it does not auto-install them.\n\n### Governance Protection\n\nPrevents Claude from editing its own rules mid-session.\n\n- **`file-protection.sh`** -- PreToolUse hook that blocks writes to protected files (CLAUDE.md, settings.json, etc.)\n- **Override mechanism** -- Add `GOVERNANCE-EDIT-AUTHORIZED` to CURRENT_TASK.md to temporarily allow edits (creates an audit trail)\n- **`/mistake`** -- Structured correction capture that adds to CLAUDE.md's accumulated corrections\n- **`/prune-rules`** -- Maintains correction list under soft cap (prevents rule bloat)\n\n### Notification\n\nDesktop alerts when Claude Code completes a task or needs your input. Platform-native:\n\n- **macOS** -- osascript notification + terminal bell\n- **Linux** -- notify-send (libnotify) + terminal bell\n- **Windows** -- FlashWindowEx taskbar flash + console beeps (uses .NET, pre-installed on Windows 10+; targets Windows Terminal)\n\n## Self-Test\n\nAfter installation, run `/self-test` to validate your setup. It checks:\n\n- Hooks are registered in settings.json AND their files exist on disk\n- Reference files are present for each installed module\n- Templates exist (CURRENT_TASK.md or current-task-template.md)\n- CLAUDE.md contains cc-sentinel behavioral rules\n- Working directory (`verification_findings/`) exists and is gitignored\n- Skills are installed for each installed module\n- Auto-invoke rules are present (`.claude/rules/plugin-auto-invoke.md`)\n\nIf anything fails, `/self-test` reports exactly what's wrong and how to fix it.\n\n## Project vs Global Install\n\n| | Project (`--target project`) | Global (`--target global`) |\n|---|---|---|\n| **Location** | `.claude/` in project root | `~/.claude/` |\n| **Scope** | This project only | All Claude Code sessions |\n| **Recommended for** | Teams, project-specific config | Solo developers, personal defaults |\n| **Hook paths** | Relative (`.claude/hooks/...`) | Absolute (`~/.claude/hooks/...`) |\n\nMost users should start with **global install**. Global install is useful for personal defaults you want everywhere.\n\n## Configuration\n\n### Module Selection\n\nInstall only what you need. Dependencies are resolved automatically:\n\n```\ncore (required)\n  +-- context-awareness\n  +-- verification\n  |     +-- commit-enforcement (requires verification)\n  |           +-- sprint-pipeline (requires all above)\n  +-- governance-protection\n  +-- notification\n```\n\n### .claudeignore\n\nThe installer generates a `.claudeignore` file tuned to your project type (Flutter, Node, Python, Rust, Go) to keep large build artifacts out of Claude's context window.\n\n### Protected Files\n\nBy default, `CLAUDE.md` and `settings.json` are protected. Edit `protected-files.txt` to customize:\n\n```\nCLAUDE.md\nsettings.json\n```\n\n## Architecture\n\n```\ncc-sentinel/\n  CLAUDE.md              # Interactive installer (conversation script)\n  install.sh             # Unix installer\n  install.ps1            # Windows installer\n  modules.json           # Module manifest (metadata, dependencies, hook registration)\n  modules/\n    core/                # Required -- hooks, templates, /cold, /cleanup, /status\n    context-awareness/   # Status bar meter, graduated warnings\n    verification/        # up to 5-agent squad, /verify, /grill\n    commit-enforcement/  # safe-commit, auto-format, channel routing\n    sprint-pipeline/     # /1-/5 workflow, /spawn multi-session\n    governance-protection/ # file-protection, /mistake, /prune-rules\n    notification/        # Platform-native desktop alerts\n  templates/\n    claudeignore/        # Per-framework .claudeignore templates\n```\n\nEach module contains some combination of:\n- `hooks/` -- Shell scripts registered in settings.json\n- `skills/` -- Skills serving as both slash commands and programmatic invocations (`.claude/skills/`)\n- `reference/` -- Documentation injected into context\n- `agents/` -- Agent definitions (`.claude/agents/`)\n- `scripts/` -- Utility scripts copied to project root\n- `templates/` -- Project root templates\n\n## Methodology\n\ncc-sentinel implements the workflow principles documented by Boris Cherny -- creator of Claude Code at Anthropic, previously Principal Engineer (IC8) at Meta, author of *Programming TypeScript*. Cherny ships exclusively through Claude Code, routinely producing 10-30 PRs per day. His publicly documented workflow tips have tens of millions of views. cc-sentinel takes what he describes as discipline and makes it infrastructure.\n\n### Verification is non-negotiable\n\n\u003e \"Probably the most important thing to get great results out of Claude Code.\" -- Cherny\n\nClaude's self-assessment of its own work is structurally unreliable. Cherny's workflow embeds adversarial two-layer code review, tests-first development, and stop hooks that block exit on test failure. His `/code-review` command spawns multiple parallel subagents checking style, history, and bugs -- then several more specifically tasked with *challenging* those findings.\n\n\u003e \"Say 'Grill me on these changes and don't make a PR until I pass your test.'\" -- Cherny\n\n**cc-sentinel enforcement:** `stop-task-check.sh` blocks completion claims without verification evidence on disk. Up to five independent verification agents (mechanical, adversarial, completeness, dependency, cold-reader) audit in parallel. Per-commit adversarial and cold reader agents check every commit. `/grill` provides iterative adversarial self-challenge. Self-attestation is explicitly rejected -- the stop hook checks for actual output files, not Claude's claim that it verified.\n\n### Context is infrastructure, not conversation\n\nContext window degradation is the most consistent failure mode in agentic AI work. Cherny's entire session architecture is designed around this reality: parallel sessions, subagent offloading, lean CLAUDE.md, glob/grep over RAG.\n\n\u003e \"Offload individual tasks to subagents to keep your main agent's context window clean and focused.\" -- Cherny\n\nHis team tried vector databases, recursive model-based indexing, and other approaches. Plain filesystem search (glob/grep) driven by the model beat everything.\n\n**cc-sentinel enforcement:** `cc-context-awareness` provides a visual status bar with graduated warnings at 50/65/75/85/92%. Pre-compact hooks force state documentation. Post-compact hooks restore it. The CURRENT_TASK protocol creates complete cold-start survival documents. The channel system enables multi-session parallel execution with file-signal coordination. Cherny accepts ~10-20% session abandonment as the cost of doing business. cc-sentinel's compaction hooks make sessions recoverable instead of disposable.\n\n### Every mistake becomes a rule\n\n\u003e \"Claude writes its own correction rules when asked and is eerily good at doing so.\" -- Cherny\n\nCombined with team-wide PR reviews that update shared CLAUDE.md files in real time, this creates what Dan Shipper calls \"Compounding Engineering\" -- a system that improves through accumulating project-specific knowledge.\n\n**cc-sentinel enforcement:** `/mistake` provides structured capture: describe the error, search existing rules, strengthen or add, check soft cap, commit. `/prune-rules` provides periodic review with git blame dates, trigger counts, and keep/update/remove recommendations. `anti-deferral.sh` catches when Claude tries to punt known issues. `file-protection.sh` prevents accidental corruption of accumulated rules.\n\n### Build for the model six months from now\n\n\u003e \"At Anthropic, we don't build for the model of today, we build for the model of six months from now.\" -- Cherny\n\nCurrent-generation models can run autonomously for hours to days, and each generation extends this further. Rules should be revisable. CLAUDE.md should be pruned with each model release.\n\n**cc-sentinel enforcement:** Modular architecture -- install only what the current model needs, remove modules as models improve. `/prune-rules` structures the pruning process with git blame dates and trigger analysis, providing evidence for each rule: when was it last triggered? Has the model improved past it? `/self-test` verifies installation integrity after changes.\n\n### Pour energy into the plan\n\n\u003e \"Pour your energy into the plan so Claude can one-shot the implementation.\" -- Cherny\n\n\u003e \"Knowing everything you know now, scrap this and implement the elegant solution.\" -- Cherny\n\nEvery session starts in Plan mode. For complex features, Cherny uses `/feature-dev` -- Claude asks what he wants, builds a specification, creates a detailed plan, then proceeds step by step. For high-stakes plans, he spawns a second Claude instance to review the plan \"as a staff engineer.\"\n\n**cc-sentinel enforcement:** `/design` (alias `/2`) structures the path: brainstorm, spec, plan, adversarial plan review, user approval gate. `/build` (alias `/3`) executes approved plans with verification at each step. `/perfect` (alias `/4`) provides the systematic \"scrap and rewrite\" pass. Plan-first is not optional -- the sprint pipeline makes plan, build, verify the only path.\n\n### Where cc-sentinel extends beyond\n\n| Capability | Cherny's approach | cc-sentinel |\n|---|---|---|\n| Context monitoring | Not mentioned | Visual meter + 5 graduated warning tiers |\n| Compaction survival | \"Abandon degraded sessions\" | Pre/post-compact hooks preserve and restore state |\n| Anti-deferral | Not mentioned | Hook detects deferral language, requires developer approval |\n| Governance protection | Not mentioned | Protected files list + authorization marker protocol |\n| Cold-start protocol | CLAUDE.md as ground truth | CURRENT_TASK as complete cold-start survival document |\n| Multi-channel coordination | Parallel sessions (independent) | File-signal coordination between orchestrator + executor |\n| Verification depth | 2-layer review (check + challenge) | Up to 5 independent agents + per-commit agents + stop hook gate |\n| Plan enforcement | Plan mode discipline (manual) | /design forces brainstorm, spec, adversarial review, user gate |\n| Completion loops | ralph-loop plugin (re-feed until done) | Stop hook + verification evidence gate + anti-deferral hook (three independent mechanisms) |\n| Permission model | Pre-approved allow list (manual) | Same + file-protection hook for governance files + authorization marker protocol |\n\n## Platform Setup\n\ncc-sentinel needs Claude Code, Git, bash, jq, and Python 3. Most platforms have some of these already. The commands below install everything missing.\n\n### Windows\n\nFresh Windows 10/11 machine -- two commands install everything:\n\n```powershell\nwinget install --source winget Microsoft.WindowsTerminal Git.Git jqlang.jq Python.Python.3.12 OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements\n```\n\n**Close and reopen your terminal after this** (PATH updates require a new session), then:\n\n```powershell\nnpm install -g @anthropic-ai/claude-code\n```\n\nThis gives you: Windows Terminal, Git Bash (provides bash), jq, Python 3, Node.js (provides npm), and Claude Code.\n\nWindows 11 ships with Windows Terminal pre-installed. winget skips packages that are already installed, so including it is harmless.\n\n### macOS\n\nFresh Mac -- install Homebrew first, then everything else:\n\n```bash\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\nbrew install node jq \u0026\u0026 npm install -g @anthropic-ai/claude-code\n```\n\nmacOS includes Git and bash; Python 3 is available via Xcode Command Line Tools or Homebrew. Only Node.js and jq need to be installed via Homebrew.\n\nIf you already have Homebrew, skip the first line. Check what you have: `brew --version \u0026\u0026 node -v \u0026\u0026 jq --version`.\n\n### Linux (Debian/Ubuntu)\n\n```bash\nsudo apt update \u0026\u0026 sudo apt install -y nodejs npm jq python3 git \u0026\u0026 npm install -g @anthropic-ai/claude-code\n```\n\nFor Node.js 18+ (required by Claude Code), you may need the [NodeSource repository](https://github.com/nodesource/distributions#installation-instructions) if your distro ships an older version:\n\n```bash\ncurl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - \u0026\u0026 sudo apt install -y nodejs\n```\n\n### Linux (Fedora/RHEL)\n\n```bash\nsudo dnf install -y nodejs npm jq python3 git \u0026\u0026 npm install -g @anthropic-ai/claude-code\n```\n\n### Linux (Arch)\n\n```bash\nsudo pacman -S nodejs npm jq python git \u0026\u0026 npm install -g @anthropic-ai/claude-code\n```\n\n### Verify Prerequisites\n\nThe cc-sentinel installer checks for `jq`, `python3`, and `bash` before proceeding and exits with specific install instructions if anything is missing. After installing cc-sentinel, run `/self-test` to validate everything is wired up.\n\n### Tested On\n\n| Platform | Version | Architecture |\n|---|---|---|\n| macOS | 15.2 Sequoia | x86_64 |\n| Linux | Mint 22.3 | x86_64 |\n| Windows | 10 Pro 10.0.19045 | x86_64 |\n\nBoth installers (`install.sh` for Unix, `install.ps1` for Windows) handle platform differences automatically. Windows hooks normalize CRLF via `tr -d '\\r'` on jq output. The bundled context-awareness module is the only known Windows-compatible version.\n\n## Uninstalling\n\nThe uninstaller removes all cc-sentinel files, cleans hook and permission entries from settings.json, strips the rules block from CLAUDE.md, and removes empty directories. Your non-sentinel hooks, settings, and CLAUDE.md content are preserved.\n\n**From a Claude Code session:**\n\n```\nUninstall cc-sentinel\n```\n\nClaude reads the CLAUDE.md uninstall instructions and runs the appropriate command.\n\n**Manual (macOS/Linux):**\n\n```bash\n# If you still have the repo cloned:\nbash ~/.claude/cc-sentinel/uninstall.sh --target global\n\n# If the repo was deleted, clone it first:\ngit clone https://github.com/turqoisehex/cc-sentinel /tmp/cc-sentinel\nbash /tmp/cc-sentinel/uninstall.sh --target global\n\n# Preview what would be removed without removing it:\nbash ~/.claude/cc-sentinel/uninstall.sh --target global --dry-run\n```\n\n**Manual (Windows PowerShell):**\n\n```powershell\npowershell -File \"$env:USERPROFILE\\.claude\\cc-sentinel\\uninstall.ps1\" -Target global\n\n# Or with dry run:\npowershell -File \"$env:USERPROFILE\\.claude\\cc-sentinel\\uninstall.ps1\" -Target global -DryRun\n```\n\nReplace `global` with `project` if you installed to `.claude/` in a specific project directory.\n\nRestart Claude Code after uninstalling for changes to take effect.\n\n## FAQ\n\n**Does this replace CLAUDE.md?**\nNo. cc-sentinel adds rules to your existing CLAUDE.md (with clear delimiters) and registers hooks in settings.json. Your existing configuration is preserved.\n\n**Can I uninstall cc-sentinel?**\nYes. See [Uninstalling](#uninstalling). The uninstaller removes all sentinel files, cleans hooks and allow rules from settings.json, and strips the rules block from CLAUDE.md.\n\n**Does this work with Claude Code plugins?**\nYes. cc-sentinel hooks and plugins coexist. The sprint-pipeline module recommends complementary plugins but does not require them.\n\n**What about performance?**\nMost hooks add 5-15ms per tool call on macOS/Linux (shell startup + jq parse). Windows (Git Bash) overhead is higher but still sub-second. The auto-format hook runs only on file writes and formats only the changed file. Context awareness adds a status line update. None are perceptible during normal use.\n\n**Can I use this with a team?**\nYes. Project install (`.claude/`) commits to your repo, so the whole team gets the same governance. Add `.claude/` to version control.\n\n## Contributing\n\nContributions are welcome. This is a side project maintained in spare time — please be patient with response times. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and submission guidelines.\n\nLook for issues labeled [`good first issue`](https://github.com/turqoisehex/cc-sentinel/labels/good%20first%20issue) if you're looking for a place to start.\n\n## Credits\n\n- **Boris Cherny** -- Creator of Claude Code at Anthropic. His publicly documented workflow principles form the philosophical foundation. cc-sentinel implements his methodology as enforceable infrastructure. Community index: [howborisusesclaudecode.com](https://howborisusesclaudecode.com). Config reconstruction: [github.com/0xquinto/bcherny-claude](https://github.com/0xquinto/bcherny-claude).\n- **cc-context-awareness** by [sdi2200262](https://github.com/sdi2200262/cc-context-awareness) -- Canonical context window monitoring tool for macOS/Linux. cc-sentinel includes a Windows-compatible rewrite (the only known working Windows version) and recommends the canonical version for non-Windows users.\n- **Production-refined** through hundreds of hours of iterative development on a production Flutter project, translating Cherny's principles into hooks, agents, and skills that enforce behavior rather than suggest it.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturqoisehex%2Fcc-sentinel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fturqoisehex%2Fcc-sentinel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturqoisehex%2Fcc-sentinel/lists"}