Project configuration
A knossos.json in the root of a project tells Knossos what to skip, where the boundaries are, which rules to check and how much a scan may spend. Every scan reads it, from the CLI, the MCP server or the watcher. You need one when the defaults scan too much, or when you want boundaries and policies that belong to the repository and not to whoever scans it.
Use either knossos.json or knossos.jsonc. Keeping both is an error. JSONC accepts comments and trailing commas without changing string contents.
A minimal file
{
"$schema": "./schemas/project-config-v1.schema.json",
"version": 1
}version is required and must be 1. The $schema line gives editors completion; the schema is project-config-v1.schema.json.
This repository's own knossos.json is a worked example with ignores, boundaries and deny policies.
Settings
Unknown keys are an error. These are the keys:
| Key | Shape | What it does |
|---|---|---|
ignores | up to 100 strings | Relative patterns to skip, on top of the built-in exclusions. |
limits | object | Discovery and worker bounds, below. |
boundaries | up to 50 objects | Named groups of components, by path or by PHP namespace. |
frameworks | up to 20 strings | Hints for static analysis of a supported framework. |
snapshot_retention | integer, 0 to 20 | How many historical snapshots to keep. |
policies | up to 50 objects | Architecture rules between boundaries. |
quality_budgets | object of integers, 0 to 100000 | Allowed regressions for the quality gate. |
dead_code_suppressions | up to 200 strings | Components to leave out of the dead-code candidates. |
diagnostic_suppressions | up to 200 objects | Diagnostics not to report, by code and optionally path. |
web_roots | object, up to 50 entries | URL prefixes a web server maps to project folders. |
enrichers | up to 32 names | Installed enrichers whose facts this project wants. |
gates | up to 20 objects | Commands the project runs before a commit. |
Ignores
Patterns are relative to the project root. Absolute paths and parent traversal (..) are rejected, and a pattern is at most 500 bytes. The built-in exclusions come in two groups.
These apply anywhere in the tree, before your patterns, and a ! pattern cannot re-include them:
- dependency and tool directories:
vendor,node_modules,.next,.nuxt,.venv,venv,__pycache__,.tox,.mypy_cache,.pytest_cache,.pnpm-store,.yarn,.stryker-tmp,.worktreesand the VCS and IDE folders.gitand.idea; - Knossos's own namespace:
.knossosand anything starting with.knossos-, such as.knossos-srcand.knossos-ci; - Laravel IDE Helper stubs (
_ide_helper*), the VitePress.vitepress/cacheand.vitepress/distdirectories, and the Laravel pathspublic/build,storage/framework,storage/attachments,storage/debugbarandstorage/logsat the project root; - minified bundles (
*.min.js,*.min.mjs,*.min.cjs), and JavaScript compiled beside its source: a.jsending with asourceMappingURLcomment next to a same-named.ts.
Build output, build, dist, coverage and site, is skipped only directly under the project root or directly under a manifest root. A manifest root is a directory holding one of these files, matched by name without regard to case:
composer.jsonpackage.jsonpyproject.tomlCargo.tomlrequirements.txt, orrequirements-followed by any name and.txt, such asrequirements-dev.txttsconfig.json, ortsconfig.followed by any name and.json, such astsconfig.app.jsonjsconfig.json, orjsconfig.followed by any name and.json
A directory of that name anywhere else, such as src/build or apps/site when apps holds no manifest, is scanned. Each skipped directory is reported as an info diagnostic, DISCOVERY_BUILD_OUTPUT_SKIPPED, unless your own patterns or a .gitignore already leave it out. The diagnostic names the pattern that re-includes only that directory, such as "!/packages/a/dist". Your patterns decide after this rule, so a ! pattern re-includes build output: "!/dist" scans the one at the root, and "!dist" scans every anchored dist.
The configuration file itself cannot be ignored. Its scan settings are part of the scanner configuration fingerprint: changing ignores, frameworks, limits.max_files or limits.max_file_bytes invalidates the cached contributions, so the next scan reads every file again. The other settings reuse every cached file.
Some settings are frozen at scan time: ignores, snapshot_retention, dead_code_suppressions and diagnostic_suppressions take effect when the next scan runs, and until then the graph answers as the last scan left it. Others are read on every call: policies, quality_budgets, limits.refresh_budget_ms and limits.watch_scan_timeout_ms apply to the next query without a scan. Editing knossos.json in any way makes the graph stale, so a query that refreshes picks up the frozen settings too.
Limits
| Key | Range | Meaning |
|---|---|---|
max_files | 1 to 100,000 | Files discovered per scan. |
max_file_bytes | 1 to 100,000,000 | Size of the largest file a worker reads. |
worker_timeout_ms | 1,000 to 120,000 (30,000) | How long a worker may stay silent during one request. |
worker_memory_mb | 64 to 65,536 | Heap cap for a language worker. |
watch_scan_timeout_ms | 10,000 to 3,600,000 (300,000) | How long one scan of the shared watcher may run. |
refresh_budget_ms | 0 to 600,000 (5,000) | How long refresh_if_stale may rescan inside one query. |
Every file a worker reports and every heartbeat restarts the worker_timeout_ms wait, and no request runs longer than 120,000 milliseconds. The PHP, Python and Rust workers show life between files only, so for them the limit applies to each file: one file that takes longer to parse fails the scan with WORKER_TIMEOUT. The TypeScript worker sends a heartbeat every 5 seconds for the whole request, because it builds a program before it reports any file, so for it only the 120,000 millisecond cap applies. When a worker hits its heap cap, the scan error names limits.worker_memory_mb as the fix.
watch_scan_timeout_ms bounds each scan of the shared watcher the Claude Code mod starts. It is a project key rather than a flag because the mod's hooks start that watcher. A scan past the limit is stopped and retried, and the watcher stops after 3 timeouts in a row. The watcher reads the value before each scan.
refresh_budget_ms caps the rescan a query runs when the graph is stale and the call asked for refresh_if_stale, which is the default. Knossos estimates the rescan from the project's recent scans: the median duration of the last 10, spread over the files in the graph, plus the fixed cost of the fastest recent incremental scan. A drift whose estimate is over the budget is not rescanned; the query answers from the last graph with a warning naming the estimate. Raise the budget when your client waits longer than 5 seconds for a tool call, or set it to 0 to keep every rescan out of queries. Queries read the value when they run.
Boundaries
{
"boundaries": [
{ "name": "core", "path_prefix": "src" },
{ "name": "billing", "namespace_prefix": "App\\Billing" }
]
}Each boundary has a unique name and exactly one of path_prefix (project relative) or namespace_prefix. Policies refer to boundaries by name.
Frameworks
laravel, livewire, symfony, django, fastapi, flask, nextjs, nestjs, react, vue, axum, actix and rocket. Any other value fails the scan.
A hint matters only where a framework is otherwise detected from a manifest:
| Hint | Effect |
|---|---|
laravel, symfony | Turns on the PHP worker's Laravel or Symfony facts when composer.json does not require the framework. |
livewire | Turns on the PHP worker's Livewire facts and rules when composer.json does not require livewire/livewire. |
axum, actix, rocket | Turns on the Rust worker's routes for that framework when Cargo.toml does not depend on it. |
django, fastapi, flask | None today: the Python worker recognises these per file, from what each file imports. |
nextjs, nestjs, react, vue | None today: the TypeScript worker recognises these per file, from imports, decorators and the file layout. |
A scan that names a hint without effect warns FRAMEWORK_HINT_NO_EFFECT: Framework hints have no effect yet: react. Knossos detects those frameworks from imports and manifests., listing each such hint, and configuration.framework_hints still echoes every hint given. Changing any hint still counts as a change to the scan settings, so cached results are rebuilt.
Policies
A policy has an id, a from_boundary, and at least one of allow_targets or deny_targets, each a list of boundary names. An optional edge_kinds list limits it to some relationship kinds. Architecture rules explains how they are checked.
Quality budgets
The supported keys are new_cycles, boundary_violations, error_diagnostics, warning_diagnostics, hub_degree_growth, unreferenced_candidates and public_surface_changes. Each is a count the quality gate tolerates against a baseline snapshot. See change review.
Dead-code suppressions
Each entry is a canonical name, matched exactly or, with a trailing *, as a prefix. Matching components are omitted from the architecture_health dead-code candidates, and bounds.suppressed_candidates reports how many were. A bare "*" suppresses every candidate in the project, so do not commit it. To mark one component as a false positive without editing the file, use an annotation.
Web roots
An HTML page names a script by URL, and the page cannot say which folder the server serves that URL from. Discovery works it out when exactly one scanned file fits (see dead-code candidates). When it cannot, name the mapping:
{
"version": 1,
"web_roots": {
"/static/": "web/public/"
}
}Each key is a URL path prefix that starts and ends with /. Each value is a project-relative folder that ends with / and does not climb out of the project. A root URL in a page that starts with a key resolves under its folder, so /static/app.mjs names web/public/app.mjs. When two keys match, the longer one wins. A mapped URL whose file is not in the scan is reported as a warning; it is never looked for anywhere else.
web_roots is new in Knossos 0.33.0. An older Knossos rejects a configuration that uses it with PROJECT_CONFIG_UNKNOWN_KEY.
Enrichers
{
"version": 1,
"enrichers": ["acme-rest"]
}Each entry names an enricher that the installation defines in enrichers.json, beside roots.json in the data directory, with knossos enricher add or by hand (see External enrichers). A name starts with a lowercase letter and holds lowercase letters, digits, _ and -, up to 64 characters. A path, a command line or an uppercase name is rejected: the project requests an enricher by name, and never carries a command to run.
Gates
{
"version": 1,
"gates": [
{ "name": "cs", "command": "vendor/bin/php-cs-fixer fix" },
{
"name": "docs",
"command": "npx prettier --check docs",
"applies_to": ["docs/*"]
}
]
}A gate is a command you run before a commit. name is 1 to 40 lowercase letters, digits and hyphens, and unique in the file. command is 1 to 300 characters, quoted as written and never run by Knossos. applies_to is an optional list of up to 10 globs over project-relative paths. A gate without it covers every path. A * crosses /, so src/* matches src/Query/A.php. The order of the list is kept.
Precedence
Values resolve in this order:
- An explicit CLI or MCP scan argument.
- The checked-in configuration.
- The built-in default.
--snapshot-retention=0 overrides a configured value, and an explicit empty boundaries list in an MCP scan disables the configured boundaries for that scan. Omitted arguments inherit the file.
A scan result reports the configuration source, the precedence rule, the framework hints, the policy count, the reviewed quality budgets, and the effective worker timeout and stream limits. It never copies absolute project roots into that metadata.
Validation
A configuration that breaks a rule fails before discovery, with a stable diagnostic prefix:
| Prefix | Cause |
|---|---|
PROJECT_CONFIG_AMBIGUOUS | Both knossos.json and knossos.jsonc exist. |
PROJECT_CONFIG_UNKNOWN_KEY | A key outside the lists above, at any level. |
PROJECT_CONFIG_VERSION_UNSUPPORTED | version is missing or not 1. |
PROJECT_CONFIG_INVALID | A value out of range, an unsupported framework, a malformed boundary, policy or budget. |
PROJECT_CONFIG_UNSAFE | A path matcher that is absolute or climbs out of the project, or a file over 1,000,000 bytes. |
PROJECT_CONFIG_UNREADABLE | The file exists and cannot be read. |
The file is never executed.
Diagnostic suppressions
A diagnostic that is wrong for your project, such as a deprecation your own compiler does not report, can be put aside. Each entry names its code, and optionally the path of the file it is reported on, exactly or as a prefix with a trailing *, and a reason:
{
"version": 1,
"diagnostic_suppressions": [
{ "code": "TS5101", "reason": "our tsc 5.9 does not deprecate it" },
{ "code": "TS2688", "path": "examples/*" }
]
}list_diagnostics leaves the matching diagnostics out of its list and its total, and counts them in suppressed.