serve

Serve the navigator with the code city as a tab, over this model.

One page, built from one graph under one view: the Navigate tab (tree and per-node incoming/outgoing dependencies), the City tab (the 3D city, full-width; a selected building offers Open in navigator, which reveals that type on Navigate), then Graph, Cycles, Coupling and Vocabulary (the selected scope’s words as a cloud and a table; a word lists the names that carry it, each one click from Navigate). The server hands out /navigator.json, /city.json and /vocabulary.json — each exactly the file navigator, city --layout and vocabulary --out would have written — beside the built frontend, and answers two lookups: /insight.json?id=ID, a node’s explanation from the insights store, and /carriers.json?term=WORD[&scope=ID][&class=CLASS][&limit=N], the names of a scope that carry a word, from the model it holds (404 for an unknown scope or term, 400 for a request it cannot ask). Stdout stays empty; the process runs until Ctrl-C.

Synopsis

codegraph serve [model.jsonl...] [--name STR] [--height METRIC] [--height-scale <linear|sqrt|log>] [--footprint METRIC] [--footprint-scale <linear|sqrt|log>] [--carry M1,M2] [--history-metrics FILE] [--framework <spring>] [--port N] [--host ADDR] [--internal-only] [--declared-only] [--no-cache] [--insights FILE]
codegraph serve --app [--data-dir DIR] [--extractors FILE] [--port N] [--host ADDR] [city flags…]

Arguments

Argument	Meaning	Default
`<model.jsonl...>`	One or more model.jsonl paths, loaded together as ONE union (decision 5). With no path, the model the extractor writes in this directory.	`<current-dir>-codegraph.jsonl`

Options

Option	Meaning	Default
`--name STR`	Display name for the corpus in the page header; defaults to the basename of each model’s root.	—
`--height METRIC`	Metric driving building height. Built in: degree, fanIn, fanOut, fields, loc, members, methods, one. Open forms: attribute:, sum:. With a change-history side-car: history: (the type’s own), history-file: (its file). From the names: vocabulary: (the word’s weight in the type’s names).	`loc`
`--height-scale <linear\|sqrt\|log>`	How height follows its metric.	`linear`
`--footprint METRIC`	Metric driving building footprint. Built in: degree, fanIn, fanOut, fields, loc, members, methods, one. Open forms: attribute:, sum:. With a change-history side-car: history: (the type’s own), history-file: (its file). From the names: vocabulary: (the word’s weight in the type’s names).	`members`
`--footprint-scale <linear\|sqrt\|log>`	How the footprint SIDE follows its metric; sqrt makes the AREA proportional.	`sqrt`
`--carry M1,M2`	Extra metrics to measure onto every building, comma-separated, bound to nothing.	—
`--history-metrics FILE`	The change-history side-car the history:/history-file: metrics read (what ‘codegraph-metrics –history’ wrote).	`<model>.history-metrics.jsonl` beside each model
`--framework <spring>`	Classify types by a framework’s own vocabulary (service, repository, controller…) and offer it as a color channel. An inference from written annotations; absent means the city says nothing about roles.	—
`--port N`	Port to listen on; 0 picks a free one (announced on stderr).	`4177`
`--host ADDR`	Address to bind. 0.0.0.0 is every interface, so the page is reachable from other machines; 127.0.0.1 keeps it to this one.	`0.0.0.0`
`--internal-only`	Drop stub (external) entities and every edge touching one.	—
`--declared-only`	Keep only `declared` facts; drop derived and dynamic-candidate edges.	—
`--no-cache`	Read the model.jsonl directly; never build or reuse a sibling model.db.	—
`--insights FILE`	The insights store behind the page’s explanation panel (what ‘codegraph explain’ wrote). With none, or one an older codegraph wrote that no ‘codegraph explain’ has migrated yet, the page shows no explanations.	`<model>.insights.db` beside the first model
`--app`	The desktop app’s daemon: no model on argv; bind 127.0.0.1:0 under a per-launch token, print one JSON line {port, token} on stdout, open folders through POST /jobs, exit when stdin closes.	—
`--data-dir DIR`	With –app: where models, their model.db caches, the page’s artifacts and the recents live.	the OS application-data directory, `codegraph/` under it
`--extractors FILE`	With –app: the extractor registry, a JSON list of { name, path, extensions[], launch?, env? } — the daemon runs an entry, never a language.	— (only model.jsonl files open)
`-h, --help`	Show this help.	—

The app daemon (`--app`)

The same page, served the way the desktop app needs it — and the development loop for that app: run it from a checkout and open the URL in a browser.

A capability URL, not an open port. The daemon binds 127.0.0.1:0 (unless --host/--port say otherwise), prints exactly one line on stdout, {"port":N,"token":"…"}, and serves everything under /<token>/. Outside the token every route is 404; a request whose Origin header is not the page’s own is 403.
Routes. The page and its assets; app (the registered extractors and the current project); recent; navigator.json, city.json and vocabulary.json (the current project’s artifacts, 404 until one is open; no carriers.json, since the daemon holds no model between jobs); POST jobs with {"src": "<folder or model.jsonl>", "extractor"?: "<name>"} → 202 with the job, 409 while another runs, 422 when several extractors claim the folder (candidates, most files first — the page asks, never guesses), when none does (seen extensions), when the name is unknown or the file is not a model.jsonl, 404 for a path that is not there; jobs/current, a server-sent event stream that replays the current job’s events to a subscriber and then streams the rest — started, phase (detect, extract, build), progress (the extractor’s own stderr lines), done, failed (exit code and the last stderr lines) — or idle when nothing has run.
The registry (--extractors FILE) is data: [{ "name": "java", "path": "/…/codegraph-java", "extensions": [".java"], "launch": "exec" }, …]. launch is exec, java (a jar) or node (a script) and is inferred from the path when absent; env adds variables to the process. Detection is a census of the folder’s file extensions (dot-directories and node_modules skipped) against every entry’s extensions.
--data-dir holds one directory per opened folder — its model.jsonl, the model.db cache built beside it, navigator.json, city.json, vocabulary.json and a project.json — plus recent.json. Reopening a folder whose claimed files have the same paths, sizes and mtimes skips the extractor; the build is skipped too when the city flags have not changed.
It dies with its parent: stdin EOF and SIGTERM both close the server and kill a running extractor.

$ codegraph serve --app --data-dir /tmp/codegraph-data --extractors registry.json
{"port":40467,"token":"99ef68e1619647f1b30e2ce25fea99e8"}

(the line above is stdout; stderr narrates each job: job: detect — 16 files for java, job: extract — running java on …, job: build — …, job: done — src: 137 nodes, 131 dependency rows.)

Exit codes

0 ok · 1 internal error (a bug) · 2 usage error · 3 findings.

3 when the load was not clean; the page is still served and one warning says so, followed by each artifact’s own caveats.

Example

$ codegraph serve fixtures/java/expected/model.jsonl --host 127.0.0.1
cache: not used — disabled by --no-cache. Reading the model.
warning: 2 types left out — the model gives them no module, so there is no district to stand them in.
warning: 2 arrows dropped — an endpoint is not a building in this view.
warning: height is unmeasured on 18 buildings (metric loc) — those are drawn at the channel minimum, not at zero.
codegraph at http://localhost:4177/ — Ctrl-C to stop.

Bound to every interface, the last line reads codegraph at http://localhost:4177/ (every interface — reachable from other machines) — Ctrl-C to stop. It never prints http://0.0.0.0:4177/.