Skip to content

Messages for the model ​

The Claude Code mod tells the model a few facts at the moment they help, so it keeps to the architecture while it works. There are four messages, each one short and said once. For one file's context on demand, the model calls the MCP server's file_context tool.

messagefiresarrives
Readafter a Read of a heavily depended-on or policed fileafter the file's contents
editafter an edit of a file at the fan-in threshold that the Read message missedafter the edit's result, and as a toast
turn endafter a turn that edited files, once it is scannedas a message before the next step
commitafter a Bash call that made a commitafter the command's output

No message costs a process of its own: the figures come from the last dashboard load and the turn's brief. agentNotes turns every message off, and enforcePolicies turns off the policy part of the turn-end message and the one after a commit (see settings).

The Read message ​

When the model Reads a file with at least fanInThreshold dependent files (20 by default), or a file in a boundary a declared policy binds, it reads one line after the file:

text
knossos: src/Result/ResultEnvelope.php (core) has 47 dependent files. Policy: core may not depend on php-worker, tests.

The rules of a boundary are stated once per loop: the main loop and each subagent get them once each. The next busy file read in core gets its count alone:

text
knossos: src/Store/StableId.php (core) has 59 dependent files.

A quiet file in a policed boundary the model has not read from yet gets the boundary and its rules, and a quiet file there after that gets nothing:

text
knossos: src/Cli/Quiet.php is in core. Policy: core may not depend on php-worker, tests.

What the message names:

  • Only a declared boundary, or one a rule binds. A file in an inferred boundary only, or in none, gets its count alone.
  • A rule with an allow list reads edge may depend only on itself, core, unassigned code. A rule limited to some dependency kinds names them in brackets: (calls).
  • The rules come with the dashboard. A boundary declared by path prefix binds every file under that prefix. A boundary placed by namespace lists its files, at most 2,000. When that list stops before it reaches the file, the message says so rather than imply there are no rules:
text
knossos: lib/Late.php: rules may bind this file; run check_architecture.

The edit message ​

An Edit, Write or NotebookEdit of a file with at least fanInThreshold dependent files that the model was not told about on Read adds one line. Claude Code reads a file before it edits it, so this is rare. You see the same line as a toast, even with agentNotes off:

text
knossos: src/Router.php has 41 dependent files across 3 boundaries; run test_impact before finishing.

The message counts the dependents' boundaries, and says across N boundaries only when there is more than one. Only the fan-in threshold triggers it: a quiet file in a policed boundary gets no edit message.

The turn-end message ​

After a turn that edited hooks/lib/paths.ts, with the pane closed: the band above the prompt reads knossos, 1 file, 16 dependents, 20 tests, as of 22s ago, with details and hide

The person sees the same turn as the band above the prompt.

After a turn that edited files, the mod scans the project (see what it writes) and the turn's brief says what the turn did. The model then reads one message before its next step, with up to two parts.

Policy violations the turn introduced, when the project declares boundary policies in knossos.json and enforcePolicies is on:

text
knossos: this turn introduced 1 boundary-policy violation. Fix it before finishing:
- domain-isolation: App\Domain\Order → App\Infra\Db

Tests that reach the turn's changes, and the command that runs them:

text
knossos: 2 tests reach this turn's changes. Run: vendor/bin/phpunit --filter '(DashboardServiceTest|TurnBriefServiceTest)'

When both have something to say they arrive as one message, the violations first.

How the policy part is worked out ​

The brief evaluates the policies for violations whose source component lives in a file the turn edited, once before the scan and once after. A violation in the second set and not the first is the turn's. One that was already there, in an edited file or in a file that merely depends on one, is not reported. Each violation is reported once a session.

  • The count is per violating dependency, so one call can count twice: once for the class, once for the method.
  • The message lists at most ten violations, then - …and 2 more (run review_diff).
  • Only files the turn changed count: with Edit, Write or NotebookEdit, or with a Bash command while the live watcher ran (the files its scans took in while the command ran, as the scan ledger lists them). A command that moved HEAD by more than a commit (a checkout, a reset, a pull) never adds to the verdict, so switching branches does not hand the model a branch's worth of violations. Without the watcher, a shell command's changes do not count. A change the watcher notices only after the turn ended counts toward the next turn.
  • When the scan ledger cannot account for every scan since the turn began (a scan that was not recorded, or one older than the ledger keeps), or an entry was cut because it changed more than 2,000 files (a branch switch), the brief still names the turn's files but leaves the policy unevaluated, and the message has no policy part. See the scan ledger.
  • The check walks only the dependencies of the components declared in the edited files, so its cost follows the edit. It stops at 100 violations, at its edge budget, or after five seconds. When it stops early, the count is a bound and the message says so:
text
knossos: this turn introduced 3 boundary-policy violations (check was truncated; run check_architecture). Fix them before finishing:
- domain-isolation: App\Domain\Order → App\Infra\Db
- …and 2 more (run review_diff)

A truncated check that found nothing still sends a message, once a session, because the turn's violations may be past the cap:

text
knossos: the boundary-policy check was truncated; run check_architecture to see violations in the files this turn edited.

The full mechanics of policies are in declared rules and budgets.

How the tests part is worked out ​

The brief names at most twenty tests that reach the turn's changes, nearest first. The message leaves out:

  • a test the turn already ran after its last edit: a Bash command that runs its runner and names the test, a directory holding it, or no test at all (the whole suite, such as vendor/bin/phpunit or npm run test:mod);
  • a test an earlier message already named;
  • a file no runner runs, such as a helper or a fixture.

The command is chosen as on the Changes tab. Tests the command names itself (PHPUnit, pytest, and Vitest or Jest scripts) are not listed again. Tests run by package (go test, cargo test) are listed, at most five, then and N more. A JavaScript test whose runner the nearest package.json does not make plain is listed with no command, since a guessed runner may not be the project's. When the session sits below the project's root, the command starts with cd <project root> &&.

The message after a commit ​

When a Bash call in any loop made a commit in the project's repository, the call's result carries one message. It says what this session's changes leave behind, as far as the graph knows:

text
knossos: this session's changes carry 1 changed file no test reaches (src/Kernel.php); 1 dependency cycle new since the session began (Router → Kernel). Check them before you push.

Up to three parts, each naming at most five items:

  • Boundary-policy violations the session's turns introduced that the policy check still reports. A violation is dropped only by a check at least as new as the turn that found it, so a pane whose reload failed or has not landed keeps it.
  • Files the session changed that no test reaches. Files changed outside the session since it began are not counted.
  • Cycles new since the session began, each as its first four members. A cycle is named only when the graph listed every cycle it held when the session began; otherwise only the count that grew is said.

The message speaks of the session's changes, since a commit need not hold them all. Nothing to say, no message. The same message is said once per loop.

A commit is told by the project's HEAD. The mod reads it (git rev-parse) before and after the command, and when it moved, reads HEAD's reflog for an entry since then that made a commit: commit, an amend, cherry-pick, revert, or a merge that made a merge commit.

seen as a commitnot seen as a commit
a merge commitgit commit inside a string, or a dry run
git commit --quietnothing to commit
a commit piped through taila reprinted commit line, such as a git log
a commit through an alias or a scripta commit in another repository
a checkout, a reset or a fast-forward

Without a reflog, git's own line for a commit ([main abc1234] subject) in what the command printed decides.

Limits ​

  • Each file is named once per session and per agent. A subagent gets its own messages, since what the main loop read was never in its context.
  • At most three messages follow tool results in one turn of a loop, the one after a commit included. A Read or edit message held back by that cap is said at the next Read or edit of the file.
  • A turn ends with at most one message.
  • A message that fails leaves the tool result as it was, and one line in the debug log. A turn-end message the session refuses is written to the debug log, so a lost message is never silent.
  • A new session in the same process (after /clear) starts the messages over: its model never read the old ones.

One file's context ​

The model asks for one file's context with the MCP server's file_context tool (mcp__knossos__file_context): the file's boundary and the declared rules whose source is that boundary, how many files depend on it and the closest five, the tests that reach it, and its three latest commits. A project file Knossos does not scan, such as a CI script or a workflow, answers with status not_scanned and its latest commits; a note on such a file makes it a file component on the next scan. A note on a file Knossos does scan stays on the file, and the Notes tab files it under that file and its boundary. The MCP tool reference has its input and output.

The mod registers no tool of its own. Claude Code serves a tool a plugin registers under the plugin's name, knossos, and keeps one server per name, so such a tool would hide the Knossos MCP server and every tool it has.