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 37 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 terminal pane: knossos opens the same workspace fullscreen in your terminal, in a
  tmux split or a terminal of its own
• 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
• 37 MCP tools: impact analysis, call sites, flows between components, cycles, hubs,
  dead-code candidates, untested code, 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

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, start Knossos in it: type /knossos in a
Claude Code session there, or run knossos in its folder. Starting it is the consent to scan,
so the folder is allowed and scanned for you. A session that only begins never allows or scans
anything. If you prefer to do it by hand, with the 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.

Outside a session, run knossos in the project for the same pane in your terminal, or
knossos web for it in your browser.

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.

Terminal pane

Keep the architecture next to your work in a terminal, such as a tmux split:

cd /path/to/your-project
knossos

It is the same nine tabs, drawn in the terminal, with the mouse and the keys of the pane.
Ctrl-C quits, and so does q unless the pane gives q to a press: on a project that
was never scanned, q starts the scan. It shares the project's server with knossos web, so a browser open
on the same project shows the same pane. See the terminal guide
for the options, the keys and what differs from the browser.

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 37 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?
• Which files and functions does no test reach?
• 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.