Knossos

What it does ​

Ask an agent what depends on a class and it reads the source tree again, every session, and tells you what it inferred. Knossos scans the repository once into a local graph of its components and the relationships between them, each with the file and line that proves it. What static analysis cannot prove is labelled with its confidence and origin.

In Claude Code that graph works in two places at once. /knossos opens it as a live pane beside your session, and the agent gets a short note at the moment it reads, edits or commits a file that matters: how much depends on it, which rules bind it, and which tests reach it.

What your agent is told ​

Four notes, each one line, each said once at the moment it helps. None of them blocks a tool call.

A Read of a busy file in a boundary with rules looks like this:

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

And after a commit:

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.

The agent can also ask about one file itself before it edits it. knossos_context returns that file's boundary and the rules that bind it, its dependents, the tests that reach it, its latest commits and whether this session changed it, in one tool call.

Each session starts with a short brief: whether the graph still matches the files, the project's rules and recorded notes. A routing skill tells the agent which questions to bring to the graph and which to leave to grep.

The pane ​

/knossos opens the project's architecture on eight tabs: Overview, Hubs, Boundaries, Cycles, Issues, Changes, Branch and Churn. It opens on Overview.

Hubs lists the most depended-on components. On a wide pane the marked one's neighbourhood stands beside the list, so you see what a hub pulls in without leaving the tab.

Cycles draws each dependency cycle as a row of boxes, from its first member back to the start.

After a turn that edited files, one line above the prompt says how far the change reaches:

knossos · 2 files → 37 dependents · 4 tests · as of 12s ago · reaching core, http +1

Changes holds the rest: every file changed since the session began, its dependents, the tests that reach it, and its diff.

Branch compares the checkout with its merge base, so you see what a branch added before you open a pull request.

Every component and file has a detail, with its blast radius drawn as rings. The finder takes you to any component by name.

A live watcher, one per project and shared by your sessions, rescans as files change, so the pane and the notes follow edits made by anyone. The pane never blocks an edit, never starts a turn on its own, and stays quiet when something it needs is missing.

Quick start ​

Knossos is not yet published to Packagist or any container registry, so install it from a checkout. You need PHP 8.3 or newer, Node 22 or newer, Python 3.11 or newer, Composer 2 and Git. Cargo 1.82 or newer is optional and adds Rust scanning.

Run the installer from the project you want to scan first:

git clone https://github.com/AraneaDev/knossos.git /absolute/path/to/knossos
cd /absolute/path/to/your-project
/absolute/path/to/knossos/tools/install

It creates the data directory ~/.knossos with a roots file that allows this project, scans it, and registers the MCP server with Claude Code at user scope. Then install the plugin, which carries the pane, the notes, the brief and the skill:

ln -s /absolute/path/to/knossos/bin/knossos ~/.local/bin/knossos
knossos install-agent-plugin                                        # preview
knossos install-agent-plugin --data-dir="$HOME/.knossos" --execute

Start a new session and type /knossos.

There is no public marketplace route, on purpose: a clone fetched from a marketplace would have no vendor/, so its own knossos could not run, and an install that fails silently every time helps nobody.

Other ways in ​

MCP, for any agent. The same graph answers 33 MCP tools: impact analysis, call sites, flows between components, cycles, hubs, dead-code candidates, change review, test impact, snapshots and trends. Codex and any client that takes the common mcpServers stdio entry can use them. The pane and the notes are Claude Code hooks and do not run elsewhere.

The CLI. Every tool except server_info is also a command, with --json for scripts:

knossos impact-analysis <project-id> 'App\Billing\Invoice'
knossos review-diff <project-id> --base-ref=main --policies=architecture-policies.json
knossos watch /absolute/path/to/project

CI. Boundary policies say which part of the codebase may depend on which, and quality budgets cap regressions such as new cycles or boundary violations against a reviewed baseline:

knossos quality-gate <project-id> <baseline-snapshot> --budgets=knossos-budgets.json --sarif --json

Exit code 0 means every evaluated gate passed, 1 that a gate failed, and 2 that the result could not be evaluated, and --sarif hands the findings to your CI in a format it already reads.

Languages ​

A mixed repository reconciles into one graph, so a question about impact crosses a language boundary the way the code does. Every relationship carries a confidence, certain, probable or possible, and a path is only as confident as its weakest edge.

What it does not do ​

Scanning never installs dependencies, executes project code or boots a framework. Workers run supervised and resource-capped, and their output is untrusted until it passes validation.

The server reads only the roots you allowed. Knossos never widens that list during normal operation: only the installer and knossos allow-root --execute write it.

A failed scan is never activated. The last complete scan stays the graph you query, and the database is derived from the source, so it can always be rebuilt.