Knossos

The labyrinth mapped once: on screen beside Claude Code, and in the notes your agent reads while it works.

Knossos (Κνωσός) is the Bronze Age palace at the heart of Minoan Crete, a complex so sprawling that Greek myth remembered it as the Labyrinth: the maze Daedalus built for the Minotaur, which no one could navigate without a thread to follow back out. Ariadne handed Theseus that thread.

TL;DR: Knossos scans a repository into a local graph of its components and the relationships between them, each with the file and line that proves it. In Claude Code, /knossos opens that graph 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. The same graph answers 36 MCP tools and a CLI, for Claude Code, Codex or any MCP client.

Facts that static analysis cannot prove are labelled with their confidence and origin. Nothing in the scan installs dependencies, imports a module or boots a framework.

Status: pre-release. Knossos is not yet published to Packagist or any container registry. The source is public on GitHub, so install from a checkout (see Installation). Image names such as knossos:dev are built locally by you; there is no docker pull to fetch them yet.

A Claude Code session: /knossos opening the pane, a walk through its tabs and a search, then an edit, the band summing up the change, and its diff in Changes.

Features

• The pane: /knossos opens the project's architecture beside your session on nine tabs (Overview, Hubs, Boundaries, Cycles, Issues, Changes, Branch, Churn and Notes), with a detail for every component and file, its blast radius as rings, and the route between any two components

• The web client: knossos web opens the same architecture workspace in your browser, with keyboard navigation, search, diffs and notes, without a Claude Code session

• The band: after a turn that edited files, one line above the prompt says how far the change reaches: the files, their dependents, the tests that reach them, the boundaries hit

• Notes on components: facts worth keeping, yours and the agent's, kept across rescans. The Notes tab shows them as a tree of where they live, says which went stale, and finds the one whose component you forgot. Your note wins over the agent's

• Messages for the agent: when the agent reads a heavily depended-on or policed file, edits one, ends a turn or makes a commit, it gets one short line about what that file or change carries. Each is said once and never blocks a tool call

• 36 MCP tools: impact analysis, call sites, flows between components, cycles, hubs, dead-code candidates, change review, test impact, one file's context, snapshots and trends. Every tool except server_info has an equivalent CLI command

• Evidence on every fact: each relationship points back to a file and a line, and a path is only as confident as its weakest edge

• 4 languages: PHP (with Laravel, Livewire and Symfony), TypeScript and JavaScript, Python and Rust, reconciled into one graph for a mixed repository

• Architecture rules and budgets: boundary policies that say which part may depend on which, and quality budgets checked against a reviewed baseline, with SARIF for CI

• A live watcher: one per project, shared by your sessions, rescans as files change, so the pane and the messages follow edits made by anyone

• Session brief and routing skill: each session starts knowing whether the graph is fresh, the project's rules and recorded notes, and which questions to bring to the graph

• Safety model: scanning never runs project code, the server reads only allowed roots, and a failed scan never replaces the last good graph

Related MCP server: LAIN-mcp

Installation

You need PHP 8.3 or newer with JSON, PDO and PDO SQLite, Node 24 or newer, Python 3.11 or newer, Composer 2 and Git. Cargo 1.82 or newer is optional and adds Rust scanning.

Clone the repository, then 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 installs the worker dependencies, 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. Re-run it from another project to add that one.

Then install the plugin, which carries the pane, the messages, the session brief and the routing skill. Its hooks run the knossos of the checkout that installed the plugin (falling back to the one on your path), and must read the data directory your server uses:

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. The brief appears at its start, and /knossos opens the pane.

• Codex or another MCP client: Codex and other MCP clients. The native pane and the messages are Claude Code hooks; every other client gets the MCP tools and can use the web client to browse the graph.

• No PHP on the host: Running Knossos in Docker.

• When it does not start: installation pitfalls, such as an unpinned data directory that gives the server and the plugin two different graphs.

• Updating, removing, or trying the plugin for one session: the plugin guide.

Quick start

The installer scanned your project. To scan another, allow it and scan it with the same data directory the server uses:

export KNOSSOS_DATA_DIR="$HOME/.knossos"
knossos allow-root /absolute/path/to/project --execute
knossos scan /absolute/path/to/project

In a Claude Code session in that project, type /knossos to open the pane, then ask the agent a structural question, such as "what breaks if I change UserRepository, and which tests would tell me?". The routing skill sends it to the graph. A first scan with real output is in first scan.

The pane

Overview: what moved since the last scan, what this session touched, and how dependencies concentrate.

Hubs: the most depended-on components, with the marked one's neighbourhood beside the list.

Cycles: each dependency cycle drawn as boxes, from its first member back to the start.

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

Branch: whether this branch broke anything against main, then what it changed by boundary.

Notes: every note on the project, yours and the agent's, by where it lives.

The finder: f, a few letters of a name, and Enter opens that component.

The band: after a turn that edited files, how far the change reaches, with the pane shut.

Every tab, key and setting is in the pane guide.

Web client

Browse your project's architecture in a browser while working in Codex, another editor, or outside an agent session:

cd /path/to/your-project
knossos web

The local server opens your browser with the same nine tabs, finder, component and file details, blast radius, diffs and notes as the native pane. Click a tab or use its number; press f to find a component. The Changes tab follows uncommitted work against the last commit, without needing a Claude Code session.

Keep the command running while you use the client; Ctrl-C stops it. To name another project or choose a port without opening a browser automatically:

knossos web /path/to/your-project --port=8123 --no-open

Use the printed address, including its token. See the web client guide for editor integration, keyboard controls, bookmarks, installing it as an app, and the differences from the Claude Code pane.

What your agent gets

Four messages, each one line, each said once at the moment it helps: after a Read of a heavily depended-on or policed file, after an edit of one the Read missed, at the end of a turn that edited files (the boundary violations it introduced and the tests that reach its changes), and after a commit, on what the session's changes leave behind:

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, file_context gives one file's boundary and the rules that bind it, its dependents, the tests that reach it and its latest commits, in one call instead of a grep for its callers. Every message and its limits are in messages for the model.

Over MCP, in any client, the 36 tools answer questions such as:

• What depends, directly or transitively, on UserRepository?

• What are the exact call sites of ScannerClient::scan?

• How can a checkout request reach invoice generation?

• Which relationships cross a declared boundary policy?

• Which test files exercise the blast radius of this diff?

• Where would a refunds feature fit the existing structure?

Each group of tools has its own guide, linked from the docs index, and every schema is in the MCP tool reference.

CLI and CI

Every query is also a CLI command, with --json for scripts. A project is named by a path inside it or by its ID, and the CLI reads the same graph as the server (~/.knossos after tools/install):

knossos impact-analysis . 'App\Billing\Invoice'
knossos review-diff . --base-ref=main --policies=architecture-policies.json
knossos quality-gate . <baseline-snapshot> --budgets=knossos-budgets.json --sarif --json
knossos dead-code .
knossos diagnostics . --severity=error
knossos check-architecture .
knossos watch /absolute/path/to/project

Exit code 0 means every evaluated gate passed, 1 that a gate failed, and 2 that the result could not be evaluated. See CI and editor integration, rules and budgets, watch mode and the CLI reference.

Supported languages

Mixed repositories reconcile into one graph. Other scanners plug in as isolated worker processes through the scanner SDK.

Safety model

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

• The allow-list is a security boundary. serve refuses to start without a root, and Knossos never writes the roots file during normal operation: only tools/install and knossos allow-root --execute do, so widening it stays a deliberate act on disk.

• The database is derived and rebuildable, and source mounts stay read-only.

• The Git-backed tools run git with repository-controlled hooks, pagers and drivers forced off.

• MCP stdio is the recommended transport. The loopback-only HTTP profile has its own threat model.

• A failed scan is never activated: the last complete scan stays the graph you query. See the fault recovery matrix.

Development

One versioned quality profile runs locally, in Git hooks and in CI:

tools/quality-container fast
tools/quality-container full

fast covers linting, static analysis, formatting and the whole test suite. full adds security audits, coverage floors, performance budgets, mutation score and supply-chain checks. See quality gates, how the mod is built and CONTRIBUTING.md for the workflow, the Conventional Commit prefixes that drive releases, and how to add a language scanner.

Further reading

• The documentation index: which page answers which question

• What a dependency graph finds that your coding agent misses

License

MIT.

Links

• Tool page

• Model Context Protocol

• Claude Code plugins

• Changelog

Built by Tim Schipper and released as open source under Aranea Development.