Knossos documentation
Each page answers one question. Every page describes behaviour at the code it ships with, and anything a scan cannot prove is labelled as heuristic, bounded or unsupported on the page that covers it. The project README is the short version.
Get started
- Installation: how do I install Knossos from a release, a checkout or Docker, register it with Claude Code, and what goes wrong?
- First scan: how do I scan a project, check the result, and what does an answer look like?
- Project configuration: how do I tell Knossos what to skip, where the boundaries are, and which rules and budgets to check?
Claude Code
- The plugin: how do I install, point, update and remove the Claude Code plugin?
- The pane: how do I open the pane, read its header and layouts, and which keys and settings drive it?
- The band: what does the line above the prompt say after a turn?
- The tabs: what does each of the nine tabs show?
- Notes on components: how do I read, write, confirm and find the notes, yours and the model's?
- Details, routes and the finder: what opens from a row, and how do I find a component by name?
- Live updates: how do the pane and the band follow the code, and what shows before there is a graph?
- Messages for the model: what does the mod tell the model, when, and in which words?
- Session brief: what does a session see when it starts, and how is each verdict chosen?
- The routing skill: which questions does the skill send to the graph, and which does it keep away?
- The pane in a browser: how do I open the pane in a browser tab with
knossos web, and what does it leave out? - The pane in a terminal: how do I open the pane fullscreen in a terminal with
knossos, and how does it share a server?
Agents
- Codex and other MCP clients: how do I register Knossos with Codex or another MCP client, and add the routing skill to Codex?
- Agent integration: which tools orient an agent before it greps, how does it get an evidence bundle for one task, and how does it record a judgment for later sessions?
Concepts
- The graph and its evidence: what does a scan store, and how far can I trust each fact?
- From request to handler: how does a
fetchorroute()call reach the route and handler that serve it?
Guides
What to ask the graph for one kind of task, through the MCP tools or the CLI.
- Finding components: how do I find a project, a component, its relations and every place a symbol is used?
- Structure analysis: what depends on this, how does A reach B, where are the cycles and hubs, which code does no test reach, and where does new code belong?
- Dead-code candidates: what does
architecture_healthreport as unreferenced or reached only by tests, and what does it exclude first? - Reviewing a change: what does this diff put at risk, and which tests reach it?
- Declared rules and budgets: how do I make architectural intent something a build can fail on?
- Scan history: what changed between two scans, and how have the metrics moved?
Languages
- PHP: how does the PHP worker type a call, and how does it match names written in another case?
- PHP and Laravel: what do the Laravel and Livewire enrichers add to a PHP scan?
- PHP and Symfony: what does the Symfony enricher add to a PHP scan?
- TypeScript and JavaScript: what does the TypeScript worker extract, from which files and frameworks?
- Python: what does the Python worker extract, and which frameworks does it recognise?
- Rust: what does the Rust worker extract, and where does it stop?
Reference
- MCP tool reference: what does each tool take, and what are its defaults and annotations? Generated from the tool definitions.
- CLI reference: which commands and options exist? Generated from
bin/knossos help. - Response envelopes: what shape does every answer share, and what do verbosity, size budgets and staleness do to it?
- Language API reference: which PHP interfaces and worker surfaces may an extension rely on? Generated from their docblocks.
- Scanner worker protocol v1: what does a scanner worker read and write on the wire?
- Scanner and enricher SDK: how do I add a scanner for another language?
- External enrichers: how do I add project-specific facts from my own tool to a scanned graph?
Generated pages are rebuilt by php tools/generate-reference.php. Edit the help text and schemas they come from, never the Markdown.
Operate
- Watch mode: how do I keep a graph current as files change?
- Updating: how do I update an installed Knossos or roll it back, and what does the update notice send over the network?
- Container mode: how does the installer run Knossos on a host with Docker or Podman and no PHP, and what can a container reach?
- Running in Docker: what does the image guarantee, and how do I mount, compose and install the plugin for it by hand?
- Project and database maintenance: how do I remove a project, clean up failed scans, and check, compact or back up the database?
- Fault recovery matrix: what happens when a scan or a worker fails?
- Troubleshooting and migrations: what do I check first when something breaks, and how do upgrades migrate?
- Streamable HTTP and its threat model: when may I serve over HTTP, and what does it defend against?
- Supply chain and release assurance: how is the release image built and verified?
- CI and editor integration: how do I fail a build on a rule or a budget, and which exit codes and reports do I get?
- Graph bundles: how do I move a graph between databases without the source?
Contribute
- Quality gates: which checks run, in which lane, and how do I run them locally?
- Coverage policy: which coverage floors apply, and where are they measured?
- Maintainability ratchets: which budgets keep the code from growing worse?
- Adversarial testing: which property, fuzz, differential and mutation tests guard the trust boundaries?
- Performance budgets: how fast and how large may a scan and a query be?
- How the mod is built: how is the Claude Code mod put together, and how is it tested?
- Agent evals: which parts of Knossos change an agent's answers, and how do I run an eval?
Decisions and examples
- ADR 0001: PHP core with isolated language scanner workers: why the core is PHP and every language scanner runs as its own process.
- ADR 0002: Isolate a current MCP stdio adapter: why the stdio server is a small adapter of its own, kept apart from the tool logic.
- ADR 0003: Prioritize static NestJS enrichment: why NestJS got static enrichment before Next.js and Express.
- ADR 0004: Serve MCP 2026-07-28 alongside 2025-11-25: how one dispatcher serves two protocol revisions.
- ADR 0005: Exclude a mutant only when no test could ever kill it: when an Infection exclusion is allowed, and how each one is pinned to its sites.
- CI and editor examples: GitHub Actions, GitLab CI and VS Code task recipes, used by the integration guide.