Skip to content
Back to search

claude-ctrl

SkillWorks with Claude CodeGitHub

DEPRECATED / UNMAINTAINED — historical reference only. Do not install or rely on this project.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/juanandresgs--claude-ctrl/badge.svg)](/listings/juanandresgs--claude-ctrl)

HTML

<a href="/listings/juanandresgs--claude-ctrl"><img src="/api/listings/juanandresgs--claude-ctrl/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The commands below are preserved only to document how the retired project used to be installed. Do not run them on an active Claude Code configuration.

ClauDEX is intended to live at `~/.claude`:

git clone https://github.com/juanandresgs/claude-ctrl.git ~/.claude
bash ~/.claude/install.sh

For replacement installs, run `install.sh` from another copy of the repo with `TARGET="$HOME/.claude"`. The installer backs up the existing tree, replaces it, carries forward only `~/.claude/.env`, and wires `cc-policy` onto your shell path when possible.

Dependencies are intentionally ordinary: `git`, `python3`, `node`, `jq`, and, of course, Claude Code.

Optional provider keys for Codex review and deep research live in `~/.claude/.env`; start from `.env.example`.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 249 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. > [!CAUTION]
  2. > ## Deprecated and unmaintained
  3. >
  4. > This repository has been retired and is retained only as a historical
  5. > reference. **Do not install it or rely on it for active workflows.**
  6. >
  7. > It receives no maintenance, security updates, compatibility fixes, or
  8. > support. There is currently no supported public successor.
  9. <p align="center">
  10. <img src="assets/banner.jpeg" alt="The Systems Thinker's Deterministic Claude Code Control Plane" width="100%">
  11. </p>
  12. # claude-ctrl: Version 5.0 ClauDEX
  13. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  14. [![GitHub stars](https://img.shields.io/github/stars/juanandresgs/claude-ctrl)](https://github.com/juanandresgs/claude-ctrl/stargazers)
  15. [![Last commit](https://img.shields.io/github/last-commit/juanandresgs/claude-ctrl)](https://github.com/juanandresgs/claude-ctrl/commits/main)
  16. [![Shell](https://img.shields.io/badge/language-bash-green.svg)](hooks/)
  17. **Instructions guide. Hooks enforce. Runtime decides.**
  18. `ClauDEX` is version 5.0 of `claude-ctrl`: a deterministic control plane for
  19. Claude Code. It turns prompt-level operating principles into runtime-checked
  20. workflow, policy, dispatch, review, and landing behavior.
  21. The thesis is unchanged: an instruction that lives only in model context is not
  22. a constraint. ClauDEX keeps prompts as intent, uses hooks as the enforcement
  23. surface, and moves operational truth into a typed runtime.
  24. This repository is a Claude Code config, a policy runtime, and a self-hosting
  25. agent-governance experiment. Its purpose is simple: make the correct path
  26. automatic, make unsafe paths mechanically difficult, and make ambiguous state
  27. impossible to ignore.
  28. ---
  29. ## Design Philosophy
  30. Telling a model to 'never commit on main' works... until context pressure
  31. erases the rule. After compaction, under heavy cognitive load, after 40 minutes
  32. of deep implementation, the constraints that live in the model's context aren't
  33. constraints. At best, they're suggestions. Most of the time, they're prayers.
  34. LLMs are not deterministic systems with probabilistic quirks. They are
  35. **probabilistic systems** — and the only way to harness them into producing
  36. reliably good outcomes is through deterministic, event-based enforcement.
  37. Wiring a hook that fires before every bash command and mechanically denies
  38. commits on main works regardless of what the model remembers or forgets or
  39. decides to prioritize. Cybernetics gave us a framework to harness these systems
  40. decades ago. The hook system enforces standards deterministically. The
  41. observatory jots down traces to analyze for each run. That feedback improves
  42. performance and guides how the gates adapt.
  43. Every version teaches me something about how to govern probabilistic systems,
  44. and those lessons feed into the next iteration. The end-state goal is an
  45. instantiation of what I call **Self-Evaluating Self-Adaptive Programs
  46. (SESAPs)**: probabilistic systems constrained to deterministically produce a
  47. range of desired outcomes.
  48. Most AI coding harnesses today rely entirely on prompt-level guidance for
  49. constraints. So far, Claude Code has the more comprehensive event-based hooks
  50. support that serves as the mechanical layer that makes deterministic governance
  51. possible. Without it, every session is a bet against context pressure. This
  52. project is meant to address the disturbing gap between developers at the
  53. frontier and the majority of token junkies vibing at the roulette wheel hoping
  54. for a payday.
  55. I've never been much of a gambler myself.
  56. *— [JAGS](https://x.com/juanandres_gs)*
  57. ---
  58. ## Historical installation instructions (do not use)
  59. The commands below are preserved only to document how the retired project used
  60. to be installed. Do not run them on an active Claude Code configuration.
  61. ClauDEX is intended to live at `~/.claude`:
  62. ```bash
  63. git clone https://github.com/juanandresgs/claude-ctrl.git ~/.claude
  64. bash ~/.claude/install.sh
  65. ```
  66. For replacement installs, run `install.sh` from another copy of the repo with
  67. `TARGET="$HOME/.claude"`. The installer backs up the existing tree, replaces it,
  68. carries forward only `~/.claude/.env`, and wires `cc-policy` onto your shell path
  69. when possible.
  70. Dependencies are intentionally ordinary: `git`, `python3`, `node`, `jq`, and,
  71. of course, Claude Code.
  72. Optional provider keys for Codex review and deep research live in
  73. `~/.claude/.env`; start from `.env.example`.
  74. ---
  75. ## What Changed From `claude-ctrl` v4.0 Metanoia --> v5.0 ClauDEX?
  76. v5.0 `ClauDEX` moves those policies into a typed Python runtime backed by
  77. SQLite. Hooks normalize Claude Code events and ask the runtime for a decision.
  78. The runtime resolves current state, evaluates policy, records transitions, and
  79. returns the hook-shaped response Claude Code expects.
  80. Deterministic enforcement remains the point, but the system now has a single
  81. place where operational truth lives. No more outdated flatfiles. Code reviews
  82. are now enforced to convergence using a separate read-only Codex/Gemini CLI
  83. critic with execution proof, to avoid model bias. Policies are now abstracted
  84. away from the hooks themselves,
  85. paving the way for support on other coding harnesses in future versions.
  86. Additional architectural changes:
  87. - shell hooks are no longer the policy model; they are adapters into
  88. `cc-policy`
  89. - SQLite runtime state replaces scattered operational breadcrumbs as the
  90. workflow authority
  91. - role permissions are capability-based instead of repeated role-name folklore
  92. - Guardian is split into provisioning and landing authority
  93. - Implementer runs are supplemented by a second read-only CLI critique, Codex
  94. - Reviewer replaces Tester as the readiness authority
  95. - Agent worktree isolation is denied; Guardian provisions controlled worktrees
  96. - dispatch is driven by structured completion records and the stage registry
  97. - routine landing is automatic after reviewer, test, scope, and lease gates
  98. pass
  99. - explicit user approval is reserved for real boundaries such as destructive
  100. recovery, history rewrite, ambiguous publish targets, or non-straightforward
  101. git operations
  102. The result should feel stricter and more autonomous at the same time: fewer
  103. unsafe shortcuts, fewer unnecessary user bounces.
  104. ---
  105. ## The Operating Loop
  106. ClauDEX runs the current workflow as:
  107. ```text
  108. planner -> guardian(provision) -> (implementer <-> codex critique) -> reviewer -> guardian(land)
  109. ^ |_< loop to convergence >_| |
  110. | v
  111. +------------------------- post-landing continuation -------------------------+
  112. ```
  113. ```mermaid
  114. flowchart TD
  115. U["User intent"] --> O["Orchestrator"]
  116. O --> P["Planner<br/>plan, scope, evaluation contract"]
  117. P --> GP["Guardian: provision<br/>worktree and lease"]
  118. GP --> I["Implementer<br/>source changes inside scope"]
  119. I --> C["Codex CLI critic<br/>read-only convergence review"]
  120. C -->|"TRY_AGAIN"| I
  121. C -->|"BLOCKED_BY_PLAN"| P
  122. C -->|"READY_FOR_REVIEWER"| R["Reviewer<br/>read-only technical evaluation"]
  123. R -->|"needs_changes"| I
  124. R -->|"blocked_by_plan"| P
  125. R -->|"ready_for_guardian"| GL["Guardian: land<br/>commit, merge, push"]
  126. GL --> PC["Planner continuation<br/>next work item or stop condition"]
  127. PC --> GP
  128. PC --> T["Goal complete, external block, or user decision"]
  129. ```
  130. The role split is intentional. ClauDEX insists on single authorities with
  131. shared requirements:
  132. - Planner owns requirements, scope, contracts, and continuation.
  133. - Guardian provisions worktrees before implementation and lands git changes
  134. after review.
  135. - Implementer writes source inside the leased scope.
  136. - Codex CLI critiques the work and kicks it back for fixes until it converges.
  137. - Reviewer is the technical readiness authority and is mechanically read-only.
  138. - The orchestrator coordinates the chain; it does not bypass role ownership.
  139. ---
  140. ## Enforcement Model
  141. ClauDEX enforces behavior at the event boundary, then stores durable facts in
  142. the runtime.
  143. ```mermaid
  144. flowchart LR
  145. C["Claude Code event"] --> H["Hook adapter"]
  146. H --> CLI["cc-policy"]
  147. CLI --> PE["Policy engine"]
  148. CLI --> DB[("SQLite runtime state")]
  149. CLI --> DE["Dispatch engine"]
  150. CLI --> PP["Prompt-pack compiler"]
  151. H --> CR["Codex review sidecar"]
  152. PE --> D{"allow / deny / warn"}
  153. D --> H
  154. DE --> N["next role directive"]
  155. PP --> A["subagent context"]
  156. CR --> RV{"try again / blocked / ready"}
  157. ```
  158. The policy engine uses first-deny-wins evaluation. The important property is
  159. not the current count of policies; that will change. The important property is
  160. where the decision is made:
  161. - write and edit decisions pass through the runtime before source changes land
  162. - bash commands pass through command-intent classification and policy
  163. evaluation before execution
  164. - Agent launches must carry the canonical ClauDEX contract
  165. - canonical subagent seats are backed by runtime carrier rows, leases, and
  166. prompt packs
  167. - Codex/Gemini critic review is hook-wired through `settings.json`,
  168. `hooks/implementer-critic.sh`, and `sidecars/codex-review/`
  169. - completion records drive dispatch rather than pane text or local memory
  170. - routine Guardian landing requires reviewer readiness, test evidence, scope
  171. compliance, and lease authority
  172. - destructive or ambiguous operations still require explicit user approval
  173. For the live policy list, run:
  174. ```bash
  175. bin/cc-policy policy list
  176. ```
  177. For hook wiring drift, run:
  178. ```bash
  179. bin/cc-policy hook validate-settings
  180. bin/cc-policy hook doc-check
  181. ```
  182. ---
  183. ## Runtime Truth
  184. The runtime is the system of record for workflow facts that prompts and shell
  185. scripts are too fragile to own.
  186. Today, that includes:
  187. - workflow bindings and work-item state
  188. - scope manifests and evaluation contracts
  189. - active leases for role and git authority
  190. - test state and reviewer readiness
  191. - completion records and reviewer findings
  192. - one-shot approvals for high-risk operations
  193. - pending agent requests and dispatch attempts
  194. - stage transitions and role capability contracts
  195. - prompt-pack layers delivered to canonical subagents
  196. - hook wiring validation against the runtime manifest

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.