Structure analysis
Six tools walk the graph instead of listing it: what depends on a symbol, how one component reaches another, which modules are tangled, where the structural hotspots are, which code no test reaches, and where new code belongs. What the graph holds, and how far to trust each fact, is on the graph and its evidence. Full input schemas are in the MCP tool reference.
| Tool | CLI | Answers |
|---|---|---|
impact_analysis | impact-analysis | What depends on a symbol, with the edge that proves it. |
explain_flow | explain-flow | How A reaches B, as ranked evidence-backed paths. |
dependency_cycles | dependency-cycles | Circular dependencies as bounded strongly connected groups. |
architecture_health | architecture-health | Hubs, hotspots, and dead-code candidates. |
untested_code | untested-code | Files, or classes and functions, no test reaches. |
suggest_location | suggest-location | Where new code for a feature belongs. |
Each tool takes the bounds that make sense for it: max_depth or max_nodes/max_edges cap the walk, timeout_ms caps the time, min_confidence filters weaker static facts (it never upgrades them), and edge_kinds narrows which relationships count. Exceeding a bound sets truncated on the envelope and records why in bounds, so a partial answer never passes for a complete one.
Impact analysis
Use impact_analysis before you change a symbol. It walks the graph backwards from the symbol to everything that statically depends on it, up to max_depth (1–8, default 6) hops.
For a class, interface, trait, enum or module the walk also starts from what it contains (a module's classes and their members, at most 500), since a change to a class is mostly a change to its methods. A caller of a method that never names the class, such as one calling through what another method returns, is then found next door, and each dependant reached through a member names it in via_member. The members themselves are not listed.
A call through an interface or a parent class reaches every implementation. The graph records such a call as one into the supertype's method, so for a method the walk also takes what calls the methods of the same name its class's ancestors declare (over extends and implements). The supertype's method is passed through, never listed itself, and via names the edge into it. This over-approximates the way a static answer has to: a caller of the interface counts for each implementation, the same call dead-code analysis makes when it keeps a method that fulfils a supertype's alive, and such a hop is probable at best. Test reach and the pane's blast radius walk the same way. A method a trait supplies is not linked to the interface method it satisfies: only extends and implements between classes are followed.
A constructor runs whenever its class is constructed. The graph records new Foo() as a constructs edge into the class Foo, not into its constructor, so for a constructor the walk also takes what constructs its class, or a subclass that declares no constructor of its own. Only constructs edges count there: a type named in a signature constructs nothing. The class is passed through, never listed itself. Test reach and the pane's blast radius walk the same way.
A PHP property read or write on a receiver the scan can type ($this, a typed variable or parameter, a static fetch on a named class) is a references edge to the property. Any other use is not recorded against it: an untyped receiver, a chained fetch such as $this->a->b, and properties in the other languages. So for a property the walk also takes what uses its class, the class passed through and never listed. Which use touches the property is a guess, so such a hop is probable at best. Test reach and the pane's blast radius walk the same way.
knossos impact-analysis project_... 'Knossos\Scanner\ScannerClient' --jsondependants is a flat, BFS-ordered list rather than grouped by distance, so sort or filter on distance and path_confidence yourself. Each entry carries the via edge that justifies it, with its origin, confidence and the evidence location (path, start_line, end_line), so the answer is checkable instead of asserted. Over MCP the default compact verbosity collapses via to the edge kind. Ask for verbosity: "full", or use --json on the CLI, to get the whole edge. counts breaks the result down by_distance and by_confidence, and entry_points lists the ways into the system among the dependants: routes, commands and endpoints, and classes classified as a controller, a command or an entry point. Test code is never an entry point. This is the same definition the agent brief and the session brief use, so all three name the same components.
The result always carries the warning "Impact is a conservative static blast radius; it does not guarantee that a dependant will break." Reflection, configuration-driven wiring and dynamic dispatch are invisible to a static scan.
The pane draws the same walk as rings around the component:

Explain flow
Use explain_flow to answer "how does a request here reach code there?". It traces static paths between two components and returns up to max_paths (1–20, default 5) of them within max_depth (1–12, default 6) hops, searching for at most timeout_ms (default 3000).
knossos explain-flow project_... 'App\Http\CheckoutController' 'App\Billing\InvoiceGenerator' --jsonEach path holds its nodes, its hops and a score. A hop is an edge with the same evidence a single relationship carries. Paths are ranked by their weakest edge first, then by fewest hops, so a short chain of certain edges beats a short chain of guesses. Only flow relationships count (routes_to, calls, dispatches, handles, listens_to, constructs, injects, binds, observes, depends_on, imports, uses_middleware, calls_endpoint, resolves_to and launches), so a link through extends or implements is not a path. The two endpoint kinds are what carry a path from a caller's fetch or route() call to the handler that serves it, as from request to handler describes.
A call through an interface or a parent class lands on that method, while an implementation or override is what runs. When calls is followed, a path steps from such a method into each method that implements or overrides it, as a hop of kind implemented_by. Which one runs is a guess, so that hop is derived, probable and has no evidence line, and min_confidence: certain leaves it out.
A pair with no static path returns an empty paths list rather than an error. That is a real answer, though it proves nothing about the runtime.
The search is bounded by timeout_ms and by 10,000 states queued, so one component with thousands of callees cannot exhaust it. A full queue accepts no new states but still searches the ones it holds. When a bound cuts the search, truncated is true, bounds.truncation_reasons names each bound met (time_limit, queue_limit and others), and the summary says the search was truncated. bounds.visited_states and bounds.queued_states say how far the search got. An empty paths list from a truncated search means none were found before that bound, not that none exist.

Dependency cycles
Use dependency_cycles before a refactor to see which modules are tangled. It reports circular dependencies as bounded strongly connected groups rather than one enumerated cycle per path, which keeps the output proportional to the tangle instead of exponential in it.
knossos dependency-cycles project_... --limit=20 --jsonSelf-loops are excluded unless you pass --include-self-loops: a recursive function is a real self-edge and almost never what someone hunting circular imports is looking for. The same goes for a cycle whose members all belong to one class, interface, trait or enum, such as a tree walk whose methods call each other, and for a self-call inside a reported cycle, which is not listed among its relationships. The quality gate's new_cycles applies the same rule. Pass --within-type (within_type over MCP) to list those one-type cycles of two or more members after the others, each marked within_type: true with its type; a symbol that only calls itself stays out, unless self-loops are asked for too, and then it is marked the same way. Those cycles have a --limit of their own: result_limit only says that cycles between types were cut, and bounds.within_type_truncated says whether these were. An import that only the compiler needs, such as a TypeScript import type, is erased at runtime and does not count, so a loop closed only by such imports is not reported. The result says so in its warnings.
A re-export facade is left out too, unless you pass --include-facades (include_facades over MCP): a re_exports edge, and an imports edge between a module and one of its own ancestors. A parent that re-exports its children (Rust's pub use child::Item;, a package __init__.py, an index.ts barrel) while they import what they share back through it (use super::Shared;) is the ordinary layout, and with those edges every such parent and child read as one cycle, hiding a real one between siblings among them. bounds.facade_edges_ignored counts the edges left out. Each listed relationship carries the path and line it was found at.
The default bounds cover the whole graph of most projects: max_nodes (default 200,000) counts only the symbols that take part in a selected relationship, and max_edges defaults to 500,000. The search reads bare endpoint pairs first and loads names, files and lines only for the cycles it reports, so a graph of tens of thousands of relationships is searched well inside the default timeout_ms of one second: Knossos's own 84,000 relationships take about 0.3 s. Past roughly 250,000 the one second runs out before max_edges does, so such a graph meets time_limit first; pass a larger timeout_ms (up to 5,000) for a complete answer. When a bound does stop the search, the summary names it, and the Claude Code pane shows the count as ? rather than 0+ when nothing was found before the stop. A cycle that runs through an edge whose node no longer exists, which only a graph written before foreign keys were enforced can hold, lists the members it could load and is marked truncated with missing_detail.

Architecture health
Use architecture_health to decide where cleanup or extra test coverage pays off most. One call ranks the hubs (the most depended-on components), the static_hotspots, and the dead_code_candidates, and adds an in_degree_histogram. Test-role components and, unless include_tests/include_external say otherwise, external and unresolved components are left out of the rankings: an unfiltered hub list is dominated by framework symbols and says nothing about your own structure. bounds counts what was left out, so the filtering is auditable.
knossos architecture-health project_... --limit=20 --jsonA hub's score is its degree, the number of edges in and out, counted over every selected relationship in the project. max_nodes keeps the components the ranking can list first (external and test components only after them, unless you include those), highest degree first, and drops the rest, so a cut node window never hides a hub or the callers it counts. The top limit components are always ranked, even when timeout_ms runs out while the degrees are counted; the summary then still says the ranking was truncated. A hotspot adds twice its cross-boundary degree, plus three if it takes part in a cycle. The cycle check runs with the same max_nodes (default 200,000) and max_edges as the rest of the call, inside what is left of timeout_ms; when it is cut short, bounds.cycle_scan_truncated says so, cycle_scan is added to bounds.truncation_reasons, the result is truncated and the summary names it, because a hotspot may then be missing its cycle bonus. Hotspots are static structural signals and predict neither change frequency nor defects. For that, read change review.
The dead-code half of the result is the subtlest thing Knossos reports. It splits what nothing references from what only tests reach. What it excludes before reporting, and why, is in dead-code candidates.

Untested code
untested_code lists what no test reaches through the graph: whole files by default, largest first, or each class, function and method with granularity: components. One walk runs forward from every test component along the same edges impact analysis reads, so a helper three calls below a tested function counts as tested. An implementation a test reaches through its interface counts too, and so does a constructor whose class a test constructs. A composition root that builds the application is reached but never walked out of, or every service would read as tested by a test that only boots the app. A program a test runs as a process is reached when the test names the file it runs (a launches edge), which for Rust includes a binary named through env!("CARGO_BIN_EXE_<name>"); one whose path comes from an environment variable a script sets cannot be seen, and the result says so in its warnings.
Test files, tool configs (vitest.config.ts, conftest.py) and TypeScript declaration files are left out: none holds code a test would reach. A component with no_inbound_edge has no inbound edge at all; whether that makes it dead is for the dead-code report to say, since it knows the entry points and framework conventions.
knossos untested-code /path/to/project --path=src/billing
knossos untested-code /path/to/project --granularity=components --limit=100The answer is static. A test that reaches code through a framework, a callback or an untyped receiver is not seen, so treat the list as where to look first, not as a coverage figure. A walk cut short by max_nodes or timeout_ms says so in bounds.truncation_reasons, since everything past the cut would read as untested.
Suggest location
Use suggest_location to find where new code belongs. It ranks existing boundaries by how well a described feature fits them, so a new file lands somewhere cohesive instead of wherever the author happened to be.
knossos suggest-location project_... "refund a completed checkout" --jsonEach candidate shows its factors (name, member and role relevance, and internal dependency cohesion) next to the score, so a ranking you disagree with can be argued with. The ranking block says which mode was applied. Cohesion counts dependency relationships only, the same kinds impact_analysis follows: contains, which links every declaration to its own members, is left out, so a boundary is not rewarded for how many declarations it holds. Members and relationships are read within timeout_ms, max_members and max_edges, and bounds.truncation_reasons names whichever cut the read.
Optional semantic ranking
suggest_location defaults to ranking_mode: deterministic. This mode is offline, reproducible, inspectable and always available.
Library integrators can inject an implementation of Knossos\Query\SemanticRanker into ArchitectureQueryService::forDatabase() and request semantic_if_available through the MCP tool or the service. The provider receives only the bounded feature text and candidate boundary text, and must return one finite normalized score from 0 through 1 for every candidate within the supplied timeout. Knossos adds at most 20 semantic points to the deterministic score and reports the provider, the applied mode and a semantic_relevance factor.
The packaged CLI and MCP runtime configure no external provider on purpose, so an opt-in semantic request reports provider_unavailable and returns the exact deterministic ordering. Missing or extra candidates, non-numeric or out-of-range scores, exceptions and deadline overruns produce the same fallback, with a provider_failed reason cut to 200 bytes. Project code is never sent to a provider or executed by the core. A custom provider is responsible for its own data-handling policy.