Knossos

What it does ​

Dependency analysis from source alone must be repeated in each session and can produce incomplete results. Knossos scans the repository into a local graph of components and their relationships, with file and line references for each. Relationships that static analysis cannot establish conclusively include confidence and origin labels.

In Claude Code, /knossos opens the graph in a live pane beside your session. Hooks also add short context notes after relevant file reads, edits and commits: dependent files, applicable rules and related tests.

Context notes for Claude Code ​

Four types of single-line note are added at specific points in a session. Each note appears once for the relevant event and does not block tool calls.

A Read note for a file with many dependents and an applicable boundary policy:

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.

Before an edit, knossos_context can retrieve a file's boundary, applicable rules, dependents, related tests, latest commits and session change status 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 specifies when to use the graph and when to search source text with 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 can inspect its dependencies 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 reports the change impact:

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 view with dependency impact displayed as rings. Use the finder to locate a 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 does not block edits or initiate turns. If a prerequisite is missing, pane output is omitted.

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.

Marketplace installation is not supported. A marketplace clone lacks vendor/, which is required to run the bundled knossos command.

MCP, CLI and CI integration ​

MCP clients. The graph is available through 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 outputs findings in SARIF format for CI integration.

Languages ​

Multi-language repositories produce one graph for impact analysis across language boundaries. Each relationship has a confidence level: certain, probable or possible. A path's confidence is limited by the lowest-confidence relationship along that path.

Scan isolation and access limits ​

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.