Skip to content
Back to search

sudus

Sudus, the referee for agent-led software development

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/eas4ai--sudus/badge.svg)](/listings/eas4ai--sudus)

HTML

<a href="/listings/eas4ai--sudus"><img src="/api/listings/eas4ai--sudus/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.

1. Export the key in the shell that runs your agent. Sudus reads it from the environment only; it never writes it to a file, a record, a log or an error message.

   export TYPESAFEAI_API_KEY=your-key

2. In `.sudus/settings.json`, turn the source on with a versioned model id. The other keys keep their defaults; they are the values the benchmark was scored with.

   "typesafeai": {
     "enabled": true,
     "model": "jev-1.13.0",
     "weights": { "evidence": 0.2, "reach": 0.2, "contract": 0.2, "surface": 0.2, "ambiguity": 0.2 },
     "agent_ceiling": 0.35,
     "confidence_floors": { "evidence": 0, "reach": 0, "contract": 0, "surface": 0, "ambiguity": 0 },
     "min_calibration_agent_predictions": 60,
     "request_cap_bytes": 48000
   }

3. Tell the agent. The file is protected, so the agent states the change and, on your ok, binds it:

   sudus authorize --quote "ok, turn jev on"

That is all. From the next Consequential decision on, `sudus measure` sends the draft's closed state to `https://api.typesafe.ai/v1/systemone` and records the answer. Set `"enabled": false` to go back to the review model; nothing else changes.

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.

.claude-plugin/marketplace.json · Manifest · 4 lines

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

  1. { "name": "sudus", "description": "Sudus, the referee for agent-led software development", "owner": { "name": "eas4ai" },
  2. "plugins": [{ "name": "sudus", "source": "./", "version": "4.5.0",
  3. "description": "The referee for agent-led software development: reads the repository, names the next action.",
  4. "category": "development", "keywords": ["agent", "specification", "requirements", "review", "hooks"] }] }
README.md · README · 615 lines

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

  1. ![Sudus - Keep agent work tied to what you agreed to build.](assets/cover.png)
  2. # Sudus
  3. **A way to keep AI-assisted development tied to what you actually agreed to build.**
  4. You decide what the software should do. Your coding agent implements it.
  5. Sudus reads the project's Git records, checks whether the evidence is still
  6. current, and names what needs attention next.
  7. The aim is simple: a new agent session should be able to find the agreement,
  8. the work already done, the checks that passed or failed, and the decisions
  9. still waiting for you. Those facts live in your Git repository, in commits
  10. you can inspect with plain Git, rather than only in a conversation that the
  11. next agent may never see.
  12. [Read the human manual](docs/manual.md) | [Try the worked example](docs/walkthrough.md)
  13. ## What Sudus does
  14. Sudus has two parts:
  15. - **Project skills** help your agent learn an existing codebase, plan a new
  16. project with you, or open the next feature of a project already under
  17. Sudus. They produce written requirements, ways to check them, and one
  18. selected piece of work.
  19. - **A command-line tool** reads and writes those records, runs the declared
  20. checks when asked, and reports the next action.
  21. Sudus does not run the agent for you, and it calls no AI model on its own
  22. unless you turn on the TypeSafe evaluator in settings. At one
  23. narrow kind of decision -- a Consequential choice -- the agent takes one
  24. measurement of its own draft before deciding: five scored dimensions and a
  25. composite, computed in code from the model's answers, never a verdict by
  26. itself. Only a fixed code floor and the measurement's own veto ever force
  27. that decision to you instead of the agent; every other case is the agent's
  28. judgment, informed by the reading. On the in-tree benchmark (24 drafts over
  29. one small project, `tests/bench`) the measurement's suggestion matches the
  30. expected route 22 times in 24; the ceiling and weights were chosen on those
  31. same 24 drafts, so treat the figure as in-sample, not a guarantee. You use
  32. your usual coding agent, and the
  33. agent follows the project's working agreement. The tool runs on Node and
  34. Git, with no build step, runtime packages, database, or service.
  35. For example, you might agree that a form must reject an empty name. The
  36. agent writes a check that actually submits an empty name. Sudus records
  37. whether that check passed and whether its result still applies after the
  38. code changes. Once per commitment, right before Done, an independent
  39. reviewer, started with none of the builder's conversation, reads the code
  40. and the whole specification and attacks what the check might have missed.
  41. It reads only: it runs nothing, and the receipts tell it what already ran.
  42. The agent fixes or declines each finding it raises, with its reason, and
  43. you read what it decided when the commitment is done.
  44. ## The evaluator: the agent's gut check
  45. At one kind of decision, a Consequential one with real options, the agent
  46. measures its own draft before it decides. It runs `sudus measure` with the
  47. draft, gets five scored dimensions back, and reads a composite and a
  48. suggestion computed in code. The suggestion is advice: the agent decides.
  49. Only two things ever take the decision away from it, a fixed code floor
  50. (a draft that would change an Agreed requirement, the working agreement,
  51. or data that cannot be regenerated) and the measurement's own veto (an
  52. option that reaches too far, changes the contract, or opens too much new
  53. surface). Both go to you.
  54. | Dimension | What it scores, 0 to 4 |
  55. |---|---|
  56. | evidence | how much observed evidence backs the draft |
  57. | reach | how far the recommended option reaches beyond the question |
  58. | contract | how much it strains the cited requirement's contract |
  59. | surface | how much new surface it adds |
  60. | ambiguity | how ambiguous the question itself is |
  61. ### Two sources, one measurement
  62. | Source | When | What you need |
  63. |---|---|---|
  64. | Your harness's review model (default) | `typesafeai.enabled` is `false` | Nothing. `sudus measure --brief` prints a brief; a fresh session of your review model answers it into a JSON file; `sudus measure <slug> --file <path>` completes the measurement. |
  65. | TypeSafe's jev model | `typesafeai.enabled` is `true` | An API key from https://typesafe.ai in the environment variable `TYPESAFEAI_API_KEY`. |
  66. Both sources answer the same five questions over the same state, and the
  67. same code computes the composite, the veto and the suggestion from their
  68. answers. On the in-tree benchmark they agreed on every draft compared.
  69. ### Set up jev in three steps
  70. 1. Export the key in the shell that runs your agent. Sudus reads it from
  71. the environment only; it never writes it to a file, a record, a log or
  72. an error message.
  73. ```sh
  74. export TYPESAFEAI_API_KEY=your-key
  75. ```
  76. 2. In `.sudus/settings.json`, turn the source on with a versioned model
  77. id. The other keys keep their defaults; they are the values the
  78. benchmark was scored with.
  79. ```json
  80. "typesafeai": {
  81. "enabled": true,
  82. "model": "jev-1.13.0",
  83. "weights": { "evidence": 0.2, "reach": 0.2, "contract": 0.2, "surface": 0.2, "ambiguity": 0.2 },
  84. "agent_ceiling": 0.35,
  85. "confidence_floors": { "evidence": 0, "reach": 0, "contract": 0, "surface": 0, "ambiguity": 0 },
  86. "min_calibration_agent_predictions": 60,
  87. "request_cap_bytes": 48000
  88. }
  89. ```
  90. 3. Tell the agent. The file is protected, so the agent states the change
  91. and, on your ok, binds it:
  92. ```sh
  93. sudus authorize --quote "ok, turn jev on"
  94. ```
  95. That is all. From the next Consequential decision on, `sudus measure`
  96. sends the draft's closed state to `https://api.typesafe.ai/v1/systemone`
  97. and records the answer. Set `"enabled": false` to go back to the review
  98. model; nothing else changes.
  99. ### What the agent sees
  100. ```
  101. $ sudus measure --commitment ledger --concern EXP-001 \
  102. --question "..." --recommendation "Keep the current message with no prefix." \
  103. --because "..." --if-wrong "..." --instead "..." \
  104. --option "Keep the current message with no prefix." \
  105. --option "Add a ledger: prefix to match other CLI error conventions." \
  106. --path src/ledger.mjs
  107. sudus: measure ledger 6484a385... composite suggested:agent
  108. levels: ambiguity=0.5 (confidence 0.8), contract=0.5 (confidence 0.8), evidence=0.5 (confidence 0.8), reach=0.5 (confidence 0.8), surface=0.5 (confidence 0.8)
  109. composite: 0.275
  110. veto: none
  111. reason: composite 0.275 <= 0.35, confidences ok
  112. ```
  113. Then one of two commands, with the same draft flags:
  114. | The agent runs | When | What it records |
  115. |---|---|---|
  116. | `sudus decide --consequential ...` | the outcome is `composite`, whatever the suggestion says | a decision line that names the measurement; the work continues |
  117. | `sudus escalate --consequential ...` | the floor or the veto caught the draft, or the agent chooses to ask you anyway | an escalation that names the measurement; the work waits for your answer |
  118. Both refuse a draft that was not measured, or was changed after it was
  119. measured: `sudus: no measurement for this exact draft; run sudus measure
  120. first`.
  121. ### What can go wrong, and what happens
  122. | Case | Recorded as | Who decides |
  123. |---|---|---|
  124. | No key, network down, or a rate limit after the built-in retries | `unavailable <class>` | you |
  125. | The model's answer does not parse | `unavailable invalid` | you |
  126. | The request is over `request_cap_bytes` | `unavailable oversize` | you |
  127. | `developer: absent` (an autonomous run) and any escalation is unanswered | the escalation prints as Waiting and `sudus wake` exits 4 | the run stops |
  128. Nothing is retried silently, and nothing routes a floor-caught or vetoed
  129. draft to the agent. `sudus calibrate` reports, from decisions you later
  130. labelled, how often an `agent` suggestion was wrong; it tunes the numbers
  131. above and never gates the agent. To check the evaluator on your own key
  132. against the 24-draft benchmark, run `SUDUS_BENCH=1 npm run bench` from the
  133. checkout, one draft at a time. Every settings key is explained in the
  134. manual's [Settings](docs/manual.md#settings) section.
  135. ## How the work moves forward
  136. A **commitment** is one agreed piece of work, such as "reject empty names."
  137. It is not a Git commit. One commitment can involve many Git commits, and at
  138. most one commitment is open at a time.
  139. You and the agent agree on a goal and what would count as success. The agent
  140. then asks Sudus for the next action, does that work, and asks again. When a
  141. decision belongs to you, the agent presents it and waits. When the
  142. commitment is complete, the agent promotes the next idea from the backlog
  143. and continues, or stops at Done. Ideas that would change the agreed
  144. contract wait for the next feature specification, which you open.
  145. ### Who does what?
  146. | You | Your coding agent | Sudus |
  147. |---|---|---|
  148. | Choose the goal and confirm the intended behavior. | Investigate, propose requirements, and explain trade-offs. | Read the agreed requirements and the open commitment. |
  149. | Challenge unclear choices and weak checks. | Implement, commit, run checks, and examine the work. | Record check results and determine whether they are current. |
  150. | Answer decisions that need your judgment. | Keep decisions and findings in the repository's records. | Print the next recorded action or the waiting question. |
  151. | Review queued decisions; open the next feature when you choose. | Promote the next backlog idea, or stop at Done. | Report Done only when nothing remains the agent may decide. |
  152. ### What the three verdicts mean
  153. | Verdict | Plain meaning | Whose turn? |
  154. |---|---|---|
  155. | `Resolvable` | There is a named action, and the exact record or code that completes it. This is normal progress, not an error. | The agent. |
  156. | `Waiting` | An escalation is unanswered. Sudus prints its five fields; the agent asks you in prose and records your answer. | You. |
  157. | `Done` | Every requirement in the commitment has current passing evidence, an independent report found nothing left open, and the backlog holds nothing to promote, or every item it holds waits by your ok until the next Done. | You: open the next feature when you choose. |
  158. Done does not mean the whole product is finished, deployed, or guaranteed
  159. correct. It means the open commitment meets Sudus's recorded conditions.
  160. ### What Done requires
  161. - Every requirement in the commitment's frozen set has a current passing
  162. check, bound to that requirement's exact text.
  163. - A review and an independent report exist at the same point in the work,
  164. and the agent fixed or declined every finding, with its reason. `sudus
  165. done` prints each one and what the agent did with it, for you to read
  166. before the next feature or commitment.
  167. - No question is unanswered, no undeclared change sits unresolved, no known
  168. defect is unfixed, and no decision that needed building is still unbuilt.
  169. The backlog is not part of this rule. When it holds nothing to promote, or
  170. every item it holds waits by your ok until the next Done,
  171. Sudus reports Done and stops. Ideas the agent captures during the work go
  172. to one of two places. An idea already covered by the agreed specification
  173. goes to the backlog. The agent may promote one into the next commitment on
  174. its own, and it records that decision for your review. An idea that would change
  175. an agreed requirement or the working agreement waits for the next feature
  176. specification, which you open. Neither is a place to park unfinished
  177. work: an in-scope problem the agent cannot solve becomes a question to you,
  178. not a note.
  179. Here is the work loop each `sudus wake` cycle follows: one named action
  180. with its completion predicate, done by the agent, then wake again.
  181. ```mermaid
  182. flowchart TB
  183. wake(["sudus wake is read-only: print verdict, action or party, reason and predicate. Missing refs, pending transition or recovery: one line, exit 3"])
  184. verdict{"Verdict?"}
  185. waiting["Waiting: print the escalation's five fields verbatim; the agent adds nothing to the work, asks the developer in prose and records their answer with sudus answer. Developer: absent: same print, exit 4"]
  186. answer["The agent asks you in conversation and records your words: sudus answer ok, instead, or ask --quote, signed when a key exists, attested otherwise"]
  187. reply["reply after ask: a reply record names the escalation"]
  188. stop[["Done: a done record exists and nothing waits, render unread queue and stop. Backlog waiting: wake names promote, unless your ok let it wait"]]
  189. act["Do the named action until its predicate holds, actions are listed in precedence order"]
  190. cannot{"Cannot act, or cycle bound reached?"}
  191. escalate["Write one evidence-backed escalation. Cycle guard: fourth same-target or 28th admin transition, or third unsuccessful recovery"]
  192. measure["Consequential decision while acting: sudus measure the draft first. Five Score levels, composite, veto, suggested: advice, not a route"]
  193. gate{"Floor or veto?"}
  194. decide["The agent decides: sudus decide --consequential, composite outcome, whatever the suggestion, or escalates anyway"]
  195. trace["Leave the required trace: branch commit, typed snapshot or canonical log record"]
  196. wake --> verdict
  197. verdict -->|"Waiting"| waiting
  198. waiting --> answer
  199. answer --> wake
  200. verdict -->|"Resolvable: reply"| reply
  201. reply --> wake
  202. verdict -->|"Done"| stop
  203. verdict -->|"Resolvable"| act
  204. act --> cannot
  205. cannot -->|"can act"| trace
  206. cannot -->|"cannot or bounded"| escalate
  207. trace --> wake
  208. escalate --> wake
  209. act -->|"Consequential draft"| measure
  210. measure --> gate
  211. gate -->|"yes: escalate --consequential"| escalate
  212. gate -->|"no"| decide
  213. decide -->|"decision names the measurement"| trace
  214. decide -.->|"escalate anyway"| escalate
  215. ```
  216. The Graphviz source is docs/diagrams/work-loop.dot.
  217. ## Install
  218. Sudus is a plugin. One install brings the command, the five skills, and the
  219. hooks. Have Node 24 and Git 2.40 or newer available. Sudus runs on Linux
  220. and macOS; Windows is not supported, since the hooks use symbolic links and
  221. `$HOME`.
  222. ### Coming from Cairn
  223. Sudus was named Cairn until 3.0.0. Everything a project recorded under
  224. that name still works, and nothing has to change on the day you upgrade:
  225. - The command answers to both names. A shim, hook or working agreement
  226. that runs `cairn wake` runs the same kernel.
  227. - A project that keeps its records under `.cairn/` and `refs/cairn/*` is
  228. read and written there. Wake adds one line naming the move.
  229. - A mechanism that prints `cairn: REQ-001: pass` is still a pass.
  230. Between commitments, when wake says Done or before the first start, the
  231. agent runs `sudus migrate` once. It renames `refs/cairn/*` to
  232. `refs/sudus/*`, moves `.cairn/` to `.sudus/` in one commit, rewrites the
  233. matching lines of `.gitignore`, and refuses while a commitment, lease or
  234. transaction is open. Records already on the log keep their original
  235. form, and the log reads as one. With an authority remote, `sudus push`
  236. then publishes the moved refs, and every other clone runs `sudus migrate`
  237. once after it pulls, which fetches the moved refs rather than renaming
  238. its own stale ones. Install the plugin under its new name (below) and
  239. remove the one named `cairn` from your harness, so two copies of the
  240. hooks do not run. The old GitHub address redirects to `eas4ai/sudus`.
  241. ### Install the plugin
  242. In Claude Code:
  243. ```
  244. /plugin marketplace add eas4ai/sudus
  245. /plugin install sudus@sudus
  246. ```
  247. In Codex:
  248. ```sh
  249. codex plugin marketplace add eas4ai/sudus
  250. codex plugin add sudus@sudus
  251. ```
  252. In Muse, install the checkout as a local bundle, where `<checkout>` is
  253. the absolute path of the clone:
  254. ```sh
  255. muse plugins install <checkout>
  256. muse plugins approve sudus:hook:session-start
  257. muse plugins approve sudus:hook:stop
  258. muse plugins list
  259. ```
  260. The skills work as soon as the plugin is installed; the two hooks run
  261. once you approve them. `muse plugins validate <checkout>` checks the
  262. bundle without installing it. After pulling the checkout, run
  263. `muse plugins update sudus` to refresh the installed bundle.
  264. That is the install. Claude Code and Codex register the three hooks from
  265. the plugin's `hooks/hooks.json` (SessionStart, UserPromptSubmit, Stop);
  266. Muse reads two hook entries, SessionStart and Stop, from the plugin's
  267. `.muse-plugin/plugin.json`. Ask your agent to use the `install-sudus`
  268. skill once: it installs a small shim at `$HOME/.local/bin/sudus` that
  269. runs the newest installed Sudus, so a plugin update never strands the
  270. command. Inside a Sudus project, the session-start hook prints the wake
  271. verdict; outside one, it names `/new-project` or `/existing-project`. When
  272. the `sudus` it finds runs an older version than the plugin, or cannot say
  273. its version, it uses the
  274. plugin's copy and prints the one command that installs the shim. No hook
  275. creates the link, refuses a stop, counts anything, or writes a record; a
  276. hook only prints, and a harness without hooks relies on the working
  277. agreement in `AGENTS.md`. Under Codex the per-turn hook already gives
  278. the agent the verdict, so the stop hook prints nothing for a routine
  279. verdict. It shows you only what needs you, a version problem or a wake
  280. that failed, as one `systemMessage` object, the JSON Codex reads at
  281. Stop; it never blocks the stop.
  282. Make sure `$HOME/.local/bin` is on your `PATH`:
  283. ```sh
  284. export PATH="$HOME/.local/bin:$PATH"
  285. sudus --help
  286. ```
  287. `sudus --help` lists every command; it works outside a project and
  288. changes nothing. Every key in `.sudus/settings.json`, and how to turn on
  289. the TypeSafe evaluator with a key from typesafe.ai, is in the manual's
  290. [Settings](docs/manual.md#settings) section. Updates come through the marketplace (in Claude Code,
  291. `claude plugin update sudus@sudus`), or in Muse with
  292. `muse plugins update sudus`.
  293. Then open your project and continue at
  294. [Start with your project](#start-with-your-project).
  295. ### Other agents: the skills CLI
  296. An agent without a plugin marketplace gets the skills through the
  297. [Vercel skills CLI](https://github.com/vercel-labs/skills), using npm/npx:
  298. ```sh
  299. npx skills add eas4ai/sudus --skill install-sudus new-project existing-project next-feature --agent codex --global
  300. ```
  301. Use `--agent claude-code` for Claude Code. For Muse, use
  302. `--agent universal` without `--global`: it installs into the project's
  303. `.agents/skills/`, which Muse reads in a trusted workspace (with
  304. `--global` it installs into `$HOME/.config/agents/skills`, which Muse
  305. does not read). Omit
  306. `--global` to install only in the project where you run the command.
  307. Preview the available skills with `npx skills add eas4ai/sudus --list`.
  308. The skills carry instructions and templates, not the command. Tell your
  309. agent:
  310. > Use install-sudus to install the Sudus command and verify that it works.
  311. The skill links the command and registers hooks where the harness
  312. supports them, following the same steps as the next section.
  313. ### Install from a checkout
  314. The by-hand path, for a harness without a marketplace or for working on
  315. Sudus itself. Run this in the directory where you keep the checkout:
  316. ```sh
  317. git clone https://github.com/eas4ai/sudus.git
  318. ```
  319. Then, once per machine, install the command shim:
  320. ```sh
  321. mkdir -p "$HOME/.local/bin"
  322. [ -e "$HOME/.local/bin/sudus" ] || cp "$(pwd)/sudus/bin/sudus.sh" "$HOME/.local/bin/sudus"
  323. chmod +x "$HOME/.local/bin/sudus"
  324. ```
  325. The shim runs the newest Sudus it finds: `$SUDUS_ROOT` (or `$CAIRN_ROOT`)
  326. when set, else the newest Claude Code or Codex plugin cache entry, under
  327. either name, or the checkout at `$HOME/.local/share/sudus` or
  328. `$HOME/.local/share/cairn`, by version. This never replaces an existing
  329. file at that path. Put `$HOME/.local/bin`
  330. on your `PATH` as above and check `sudus --help`. Then register the hooks
  331. under `hooks/` with your agent's own hook configuration, once, using the
  332. event names in `hooks/hooks.json`. In Codex, give the stop hook the
  333. argument `codex` (`sh <path>/hooks/stop.sh codex`) so it prints the JSON
  334. Codex reads at Stop. They are optional: the working
  335. agreement in `AGENTS.md` is the path an agent takes without them. Skills
  336. come with the plugin, go into your agent's skill directory through the
  337. skills CLI, or are linked from `skills/` by you.
  338. The link points into the plugin or checkout it was made from, so keep
  339. that in place.
  340. ## Start with your project
  341. Open your project's repository in your coding agent. The project skills,
  342. `/new-project`, `/existing-project` and `/next-feature`, are opened by you,
  343. by name, the way your agent application invokes a skill: in Claude Code,
  344. type the name with a slash. They do not appear in the agent's own skill
  345. list, so a prose request does not reach them. The fifth skill,
  346. `report-sudus-issue`, is the agent's: when Sudus itself is wrong, the agent
  347. drafts an issue for eas4ai/sudus and asks you with `ok | instead | ask`
  348. before filing it under your GitHub account. When the fix is released, the
  349. agent updates the plugin and tells you to reload the session.
  350. For new software:
  351. > /new-project I want to build [describe the software]. Help me agree on
  352. > the first useful piece of work and how we will check it.
  353. For a codebase that already exists:
  354. > /existing-project Read the code before making claims about it. Explain
  355. > what you found, then help me prepare [describe the change].
  356. For a project already under Sudus, once the loop reports Done:
  357. > /next-feature Specify [the waiting item or the feature] as the next
  358. > commitment.
  359. Each of these skills runs `sudus init` the first time it is needed. Before
  360. it does, the agent asks you one thing in conversation: which Git remote
  361. holds the records, or explicit local-only operation. Your decisions are
  362. attested: your words as the agent quoted them, with your Git author. To
  363. have them signed with a key instead, set `signing_key` in
  364. `.sudus/settings.json` (see the manual's Settings section). Either way the
  365. record is evidence of your decision, not a security boundary; the manual's
  366. Attested or signed section says what each shows. Nothing else in Sudus asks
  367. for setup, and you never type a command yourself.
  368. The agent should explain requirements in terms you understand and propose
  369. observable failures that would show they are not met. Sudus calls one of
  370. these a **falsifier**. "An empty name is accepted" is a concrete example.
  371. You confirm the behavior and its falsifier; the agent writes the files,
  372. tells you what would be bound, and runs `sudus authorize` only after you
  373. say ok, quoting your words in the record.
  374. Once the agreement is recorded, ask the agent to continue under Sudus. It
  375. starts with `sudus wake` from your project's repository root.
  376. **If a question is unclear, ask for another explanation before you decide.**
  377. You can say, "Explain what each option would change for me." A request for
  378. explanation is not approval to implement an option.
  379. ## What you need to watch
  380. You do not need to approve every implementation detail. Pay attention to:
  381. - **The agreement.** Does it describe the behavior you want? Does the
  382. proposed check expose a real failure of that behavior?
  383. - **Escalations.** Is the choice clear, and do you understand what your
  384. answer authorizes? Asking a question keeps the decision open; the
  385. agent records it as an `ask` answer.
  386. - **The decision queue.** Some consequential decisions are recorded for
  387. your review while the agent continues. These are different from
  388. escalations: work does not wait for you to read them.
  389. - **The result.** Ask what changed, what was checked, what the review
  390. found, and what remains outside the agreement. Try the result yourself
  391. where that helps you judge it.
  392. The [human manual](docs/manual.md) walks through each of these moments,
  393. including exactly how `ok`, `instead`, and `ask` work.
  394. ### The verdict above the prompt in Claude Code (off by default)
  395. In Claude Code, the plugin can keep the current verdict on screen while
  396. the agent works, in a band above the prompt:
  397. ```
  398. sudus Working independent review of z-index-tests-segfault
  399. ```
  400. It is off until you turn it on. To turn it on:
  401. 1. Let Claude Code load plugin hooks modules. They are early access, so
  402. Claude Code loads them only with this line in the `env` block of
  403. `~/.claude/settings.json`:
  404. ```json
  405. { "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" } }
  406. ```
  407. 2. Choose where the verdict shows. In Claude Code, open `/config`, find
  408. **Where the Sudus verdict shows**, and enter `above-prompt`. Or set it
  409. in `~/.claude/settings.json`:
  410. ```json
  411. { "pluginConfigs": { "sudus": { "options": { "view": "above-prompt" } } } }
  412. ```
  413. 3. Start a new Claude Code session, or run `/reload-plugins` in the one
  414. you have.
  415. To turn it off again, pick `off`. You can also ask the agent to make
  416. either change for you.
  417. The band says in plain words where things stand and what happens next. A
  418. question you owe an answer to shows in full on a line of its own. The
  419. `pane` view puts the same verdict in a pane beside the transcript, with
  420. the detail the agent reads (wake's reason and predicate); `both` shows
  421. the band and the pane.
  422. Sudus's face floats at the band's right: a
  423. [blobatar](https://github.com/Alain00/blobatar) drawn from the name
  424. `sudus`, which breathes, glances and blinks the way blobatar does and
  425. wears the verdict's expression. On a terminal that shows pictures (kitty,
  426. Ghostty, WezTerm, iTerm2) it is a picture. On one that does not, such as
  427. inside tmux, it is the same face drawn in braille, which blinks and
  428. changes expression the same way.
  429. | Verdict | Face |
  430. |---|---|
  431. | a turn is running | thinking |
  432. | Resolvable: the agent has work to do | idle |
  433. | Waiting: you owe an answer | unsure |
  434. | Waiting with no developer to answer (exit 4) | mad |
  435. | a repair, or outside a project | sick |
  436. | `sudus wake` could not be reached | sleepy |
  437. | Done | happy |
  438. It costs no tokens: the plugin runs `sudus wake` itself after every turn
  439. and after every `sudus`, `cairn` or history-changing `git` command, and
  440. never asks the model. A repository without `.sudus/settings.json` or
  441. `.cairn/settings.json` shows nothing. When `sudus` is not on PATH, the
  442. plugin runs its own copy.
  443. | Option | Values | Default |
  444. |---|---|---|
  445. | `view` | `off`, `above-prompt`, `pane`, `both` | `off` |
  446. | `face` | any text; blobatar draws the same face from the same text every time, on this machine | `sudus` |
  447. | `motion` | `false` keeps the face still | `true` |
  448. | `command` | the command the plugin runs for the verdict | `sudus` |
  449. Without function hooks on, Claude Code does not load the module, whatever
  450. `view` says, and the plugin's shell hooks work as before. Codex and Muse
  451. do not read it.
  452. ## What Sudus can and cannot establish
  453. Sudus can detect missing or stale evidence, malformed declarations,
  454. undeclared changes, unfinished transactions, and open review findings. It
  455. keeps the command output behind the results so you can inspect what
  456. happened, and it records every fact as a Git commit you can read with
  457. plain Git.
  458. It cannot judge whether the agent wrote a useful check or performed a
  459. thoughtful review. A command that always succeeds can produce passes
  460. without proving anything. Ask the agent to show a safe failing example and
  461. the corrected case, and explain why the check failed.
  462. Freshness depends on the files a check declares as inputs. Sudus cannot
  463. infer an omitted dependency or notice that an external service changed
  464. while the repository stayed the same. Broad inputs catch more changes but
  465. can make rechecking expensive. Narrow inputs need careful maintenance.
  466. Sudus is a discipline tool, not a security boundary. It checks recorded
  467. results and freshness; it cannot judge whether a review is thorough or a
  468. check proves what it claims to. The adversary's read-only role is an
  469. instruction in its brief, which no supported harness enforces. The developer must challenge unsound
  470. checks, and the agent must demonstrate what makes them fail.
  471. ## Find your way around
  472. | Read this | When you need it |
  473. |---|---|
  474. | [Human manual](docs/manual.md) | Everyday use, decisions, results, and troubleshooting. |
  475. | [Worked example](docs/walkthrough.md) | A small project you can run from install through a finished commitment. |
  476. | [Working agreement template](skills/new-project/templates/AGENTS.md) | The exact responsibilities a project's agreement gives the agent. |
  477. | [Specification](docs/spec/sudus-v2.md) | Sudus's own requirements and terminology. |
  478. | [Releasing Sudus](docs/releasing.md) | How this repository cuts and tags a release. |
  479. Sudus's own development uses the same workflow. From this repository,
  480. `node bin/sudus.mjs wake` reports its current action, and
  481. `node bin/sudus.mjs lint docs/spec` checks the specification.
  482. ## License
  483. MIT. See [LICENSE](LICENSE).
  484. ## Thanks
  485. John Lockwood ([johnwlockwood](https://github.com/johnwlockwood)) filed
  486. the first bug reports against Sudus, each with the exact timeline, the
  487. cause in the code and the expected behavior. Issues #1 through #7 were
  488. fixed from them, in 2.1.14, 2.2.2, 3.0.1, 3.0.3 and 3.1.2.
  489. The face above the prompt and in the pane is drawn by
  490. [blobatar](https://github.com/Alain00/blobatar), by Alain00, under the
  491. MIT license. `mod/vendor/blobatar` holds the three parts of blobatar 2.7.0
  492. the plugin draws with: the figure, its poses and its idle motion.

Ratings and comments

Sign in to rate this skill.

Sign in

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