ctx generate

ctx generate builds a first knowledge base out of the code itself: it runs the external Graphify CLI to extract a code graph, turns the graph’s subsystems and most-connected components into a pick-list, and stages your selection for your agent to verify and write up.

When you’d reach for it

Reach for it when ctx migrate comes back with No existing knowledge found to migrate. — a service with real code and no prose. It gives an agent a map to start from: which subsystems exist, which symbols everything hangs off, and where in the tree each one lives.

Two caveats worth internalising before you run it. First, ctx generate shells out to a separate tool you must install yourself: uv tool install graphifyy (pipx or pip work too). Nothing is vendored, and there’s no fallback path — no graphify on PATH, no candidates. Second, what it stages is a scaffold, not documentation. Every slice file opens with a header telling the agent the content is auto-extracted, that INFERRED edges are guesses, and that it must read the cited source before writing anything. Treat the output as a reading list, not as pages.

Synopsis

ctx generate                        # analyze this project, pick, stage
ctx generate --list                 # run the analysis and print candidates only
ctx generate --type entity          # narrow to components
ctx generate --all --yes            # stage everything, no prompts
ctx generate --from ../other-repo --backend gemini

Flags

Flag	Type	Default	Description
--all	bool	false	select every item without prompting
--backend	string	—	optional Graphify LLM backend for richer subsystem names (gemini|claude|ollama|...)
--from	string	—	codebase directory to analyze (default: this project)
--list	bool	false	only list what would be generated; stage nothing
--type	string	—	only items of this suggested type (concept|entity|analysis)
--yes, -y	bool	false	skip the confirmation prompt

--backend is handed only to Graphify’s clustering pass (graphify cluster-only … --backend=<name>), where it buys you human-sounding subsystem names instead of hub-derived ones. It is not passed to the extraction pass, so it cannot fix an extraction that fails for want of an API key — see Common errors. Clustering is best-effort anyway: if it fails, the run continues with the graph extraction already produced.

--from is a directory only. Unlike ctx migrate, it does not accept a git URL and does not clone anything.

--list skips the staging, not the work. Graphify still runs end to end and the slice files are still written into .contexo/.generate-cache/; the only thing --list suppresses is the manifest. Budget for the full analysis time whenever you invoke it.

--type accepts concept (a subsystem), entity (a component) or analysis (the codebase overview), and renumbers the list — the IDs at the prompt always refer to the list you’re looking at. --all answers the selection prompt but not the confirmation, so scripts need --all --yes together.

Flag	Type	Default	Description
--root	string	—	project root directory (default: current directory)

Examples

Analyze the current project and look at what you’d get:

ctx generate --list

ctx generate --list

Error: graphify extract failed: exit status 1: error: no LLM API key found (3 doc/paper/image file(s) need semantic extraction). Set GEMINI_API_KEY or GOOGLE_API_KEY (gemini), MOONSHOT_API_KEY (kimi), ANTHROPIC_API_KEY (claude), OPENAI_API_KEY (openai), DEEPSEEK_API_KEY (deepseek), or pass --backend. A code-only corpus needs no key. Or pass --code-only to index just the code (local AST, no key) and skip the non-code files.
[graphify extract] scanning ~/projects/acme-api
[graphify extract] found 4 code, 3 docs, 0 papers, 0 images
[graphify extract] 1 file(s) not classified (no supported extension or shebang), skipped: .gitignore

That capture is the failure mode you’re most likely to hit first, and it’s worth reading closely: Graphify’s extract step found non-code files (Markdown, papers, images) that it can only index semantically, so it demands an LLM key. ctx invokes graphify extract <root> with no flags, so the fix is on Graphify’s side — export one of the keys it names (GEMINI_API_KEY, ANTHROPIC_API_KEY, …) before running ctx generate. Passing --backend will not help here.

Stage everything the analysis found, without prompts:

ctx generate --all --yes

On success this prints Staged N item(s). Ask your agent: "finish the contexo generation". Say that to your agent and it works through the staged slices via ctx_generate.

Narrow to the components rather than the subsystems — useful when you want entity pages for the handful of types everything depends on:

ctx generate --type entity

How it works

1. Requires .contexo/ under the project root (--root, else the current directory), and graphify on PATH.

2. Runs graphify extract <project-root>, then best-effort graphify cluster-only <project-root> --no-viz (plus --backend=… if you passed one). Clustering adds community names and GRAPH_REPORT.md.

3. Graphify writes into a graphify-out directory inside whatever it analyzed — the project root, or the --from directory. ctx then moves that directory to .contexo/.generate-cache/graphify-out so the analyzed tree is left clean. If the move fails — a different volume, a file still open — it falls back to reading graphify-out in place, and that directory stays where Graphify put it for you to delete.

4. Parses graphify-out/graph.json (networkx node-link format) and maps it to candidates, in this order:

   • the GRAPH_REPORT.md overview → one analysis candidate, slug codebase-overview;
   • up to 15 communities, largest first → concept candidates named from community_name (or community <id> when clustering didn’t run);
   • up to 15 “god nodes” — the highest-degree symbol nodes, with file nodes excluded → entity candidates.

   So a repository of any size yields at most 31 items.

5. For each community and component it writes a Markdown slice under .contexo/.generate-cache/slices/ — community-<slug>-<id>.md and component-<slug>.md — listing members with path:line source references and the typed edges between them, under a header marking the whole thing auto-extracted and unverified.

6. If graph.json is missing or unparseable, the run degrades to the overview candidate alone rather than failing. If the report is missing too, there are no candidates and you get the shared catalog renderer’s message, No existing knowledge found to migrate.

7. After you pick and confirm, .contexo/migrate.json is written with kind: "generate", source_root, external_cache pointing at .contexo/.generate-cache, and one entry per pick. No pages are written and nothing is sent to the Contexo server.

8. ctx_generate then returns a GENERATE_RESUME directive for exactly those items: read each slice and the source files it cites to verify, call ctx_write_page with a name you chose from the real code (not the community label), write the <YYYY-MM-DD>-generate-<label> provenance page, ctx_push with no_distill=true, and finish with ctx_generate(done=true) — which clears the manifest and deletes .contexo/.generate-cache.

Caution

.contexo/migrate.json is one slot shared with ctx migrate. Staging a generate run overwrites a pending migration (and the reverse), and each MCP tool ignores the other’s manifest — ctx_migrate will not resume a kind: "generate" manifest, because framing code slices with distillation instructions would produce confidently wrong pages. Finish one flow before starting the other.

Note

The cache lives under a dot-directory on purpose: the page store skips dot-directories, so slices and Graphify artifacts can never be picked up by ctx push. The trade-off is that until the agent calls ctx_generate(done=true), .contexo/.generate-cache/ sticks around — it is safe to delete by hand if you abandon the run.

Common errors

• ctx generate needs Graphify — install it with `uv tool install graphifyy` (or pipx/pip install graphifyy) — no graphify executable on PATH. Checked before Graphify is asked to do any work, so nothing has been written yet.
• graphify extract failed: exit status 1: error: no LLM API key found … — the codebase contains docs/papers/images that Graphify wants to index semantically. Export one of the keys it lists and re-run. --backend applies to clustering only and won’t satisfy this.
• generate: no .contexo/ here — run 'ctx init' first — run from the project root or pass --root.
• generate: index 40 out of range 1..31 / generate: bad index "x" / generate: empty selection — the selection line didn’t parse. Use 1,2,5-7, all or *; indices are 1-based against the list as rendered after --type filtering.
• No existing knowledge found to migrate. (from a generate run) — Graphify produced neither a usable graph.json nor a GRAPH_REPORT.md. The message text is shared with ctx migrate; the cause here is an empty or failed analysis.

See also

• Generate guide — installing Graphify and the full walkthrough of verifying slices
• ctx migrate — the right command when the project already has docs
• ctx_generate — the MCP tool that consumes the staged manifest
• ctx push — where the agent sends the pages it writes