Every command runs on the project given by --root (default: the current folder), written before the command name: cg --root ~/code/shop impact cancel_order. cg COMMAND --help prints the same text.
Values in Default apply when the option is left out. The JSON answers of the main commands are described in Formats.
- Start here:
start·locate·search·impact·verify·review - Explore:
find·show·callers·callees·path·context·source·map·flows·architecture·features·prepare·explore·export - Index and maintenance:
index·stats·check·dead·catalog·selftest - Agents:
mcp·change
Start here: index the project and show what to ask it, with ready commands.
cg [--root ROOT] start [-h] [--json] [--lang {en,it}]
| Argument | Meaning | Default | Values |
|---|---|---|---|
--json |
print the machine-readable JSON answer | ||
--lang LANG |
language of the guide (default: from the environment) | en, it |
From the text of a request to the places to change, their callers and tests; no model calls.
cg [--root ROOT] locate [-h] [--limit LIMIT] [--max-chars MAX_CHARS] [--min-conf {high,medium,low}] [--json] text
| Argument | Meaning | Default | Values |
|---|---|---|---|
text |
the request, issue or stack trace, as text | ||
--limit LIMIT |
candidate places to return, 1-10 | 5 |
|
--max-chars MAX_CHARS |
budget for the whole answer in characters, 512-16000 | 5000 |
|
--min-conf MIN_CONF |
lowest edge confidence to follow: high, medium or low | medium |
high, medium, low |
--json |
print the machine-readable JSON answer |
Find the code for a request: full-text BM25 over names, paths, signatures and bodies, fused with the call graph.
cg [--root ROOT] search [-h] [--mode {hybrid,lexical}] [--limit LIMIT] [--depth {1,2,3}] [--min-conf {high,medium,low}] [--max-chars MAX_CHARS] [--json] query
| Argument | Meaning | Default | Values |
|---|---|---|---|
query |
words to search; word roots and synonyms widen it when exact words miss | ||
--mode MODE |
hybrid (text and graph, default) or lexical (text only) | hybrid |
hybrid, lexical |
--limit LIMIT |
results to return | 10 |
|
--depth DEPTH |
graph steps from the best text matches, 1-3 | 2 |
1–3 |
--min-conf MIN_CONF |
lowest edge confidence to follow: high, medium or low | medium |
high, medium, low |
--max-chars MAX_CHARS |
budget for the whole answer in characters | 9000 |
|
--json |
print the machine-readable JSON answer |
What breaks if this changes: callers up to a depth, each with its callsite, and the tests reached.
cg [--root ROOT] impact [-h] [--file] [--depth DEPTH] [--min-conf {high,medium,low}] [--limit LIMIT] [--json] target
| Argument | Meaning | Default | Values |
|---|---|---|---|
target |
symbol, or a file path with --file | ||
--file |
TARGET is a file: impact of every definition in it | ||
--depth DEPTH |
caller levels to follow | 3 |
|
--min-conf MIN_CONF |
lowest edge confidence to follow: high, medium or low | medium |
high, medium, low |
--limit LIMIT |
callers to show | 40 |
|
--json |
print the machine-readable JSON answer |
Tests that reach a function or file, proposed and never run.
cg [--root ROOT] verify [-h] [--file] [--plan] [--min-conf {high,medium,low}] [--depth {1,2,3,4,5}] [--json] target
| Argument | Meaning | Default | Values |
|---|---|---|---|
target |
symbol, or a file path with --file | ||
--file |
TARGET is a file | ||
--plan |
accepted for compatibility; verify always proposes tests and never runs them | ||
--min-conf MIN_CONF |
lowest edge confidence to follow: high, medium or low | medium |
high, medium, low |
--depth DEPTH |
caller levels to follow | 3 |
1–5 |
--json |
print the machine-readable JSON answer |
What a change touched: signatures, calls and findings compared with a base, plus a test plan.
cg [--root ROOT] review [-h] [--base BASE] [--staged] [--baseline BASELINE] [--save-baseline SAVE_BASELINE] [--force] [--max-chars MAX_CHARS] [--min-conf {high,medium,low}] [--depth {1,2,3,4,5}] [--json] [--summary]
| Argument | Meaning | Default | Values |
|---|---|---|---|
--base BASE |
Git revision to compare with, e.g. HEAD or main | ||
--staged |
review only staged changes | ||
--baseline BASELINE |
compare findings with a baseline file saved earlier | ||
--save-baseline SAVE_BASELINE |
save the current findings to this file | ||
--force |
overwrite the file given to --save-baseline | ||
--max-chars MAX_CHARS |
budget for the whole answer in characters | 20000 |
|
--min-conf MIN_CONF |
lowest edge confidence to follow: high, medium or low | medium |
high, medium, low |
--depth DEPTH |
caller levels for the test plan | 3 |
1–5 |
--json |
print the machine-readable JSON answer | ||
--summary |
with --json: a compact answer (base, counts, new findings, tests with commands, limits); text output is already a summary |
Find definitions by name; * matches any characters.
cg [--root ROOT] find [-h] [--kind KIND] [--limit LIMIT] pattern
| Argument | Meaning | Default | Values |
|---|---|---|---|
pattern |
name or qualified name, e.g. cancel_* or Order.cancel | ||
--kind KIND |
only this kind: function, method, class, ... | ||
--limit LIMIT |
results to show | 40 |
One definition: file, lines, signature, callers and callees.
cg [--root ROOT] show [-h] symbol
| Argument | Meaning | Default | Values |
|---|---|---|---|
symbol |
name or qualified name |
Direct callers of a function, each with its callsite.
cg [--root ROOT] callers [-h] [--min-conf {high,medium,low}] symbol
| Argument | Meaning | Default | Values |
|---|---|---|---|
symbol |
name or qualified name | ||
--min-conf MIN_CONF |
lowest edge confidence to follow: high, medium or low | low |
high, medium, low |
Functions a function calls directly.
cg [--root ROOT] callees [-h] [--min-conf {high,medium,low}] symbol
| Argument | Meaning | Default | Values |
|---|---|---|---|
symbol |
name or qualified name | ||
--min-conf MIN_CONF |
lowest edge confidence to follow: high, medium or low | low |
high, medium, low |
Shortest call path from one function to another.
cg [--root ROOT] path [-h] [--min-conf {high,medium,low}] src dst
| Argument | Meaning | Default | Values |
|---|---|---|---|
src |
calling function | ||
dst |
called function | ||
--min-conf MIN_CONF |
lowest edge confidence to follow: high, medium or low | low |
high, medium, low |
Source of a function with the callers, callees and tests an agent needs, within a budget.
cg [--root ROOT] context [-h] [--budget BUDGET] [--max-chars MAX_CHARS] [--json] [--profile {understand,change,debug,review}] [--line LINE] [--min-conf {high,medium,low}] symbol
| Argument | Meaning | Default | Values |
|---|---|---|---|
symbol |
name or qualified name | ||
--budget BUDGET |
budget in tokens (about 4 characters each) | 2500 |
|
--max-chars MAX_CHARS |
budget in characters; overrides --budget | ||
--json |
print the machine-readable JSON answer | ||
--profile PROFILE |
what the context is for: understand, change, debug or review | change |
understand, change, debug, review |
--line LINE |
pick the definition that contains this line when the name is ambiguous | ||
--min-conf MIN_CONF |
lowest edge confidence to follow: high, medium or low | medium |
high, medium, low |
A window of source around a line and Unicode column, checked against the index.
cg [--root ROOT] source [-h] [--line LINE] [--column COLUMN] [--max-chars MAX_CHARS] [--json] path
| Argument | Meaning | Default | Values |
|---|---|---|---|
path |
file path inside the project | ||
--line LINE |
line number | 1 |
|
--column COLUMN |
Unicode column on that line | 0 |
|
--max-chars MAX_CHARS |
characters of source to return | 1200 |
|
--json |
print the machine-readable JSON answer |
Modules of the project: size, dependencies between them and the most-called functions.
cg [--root ROOT] map [-h] [--depth DEPTH] [--limit LIMIT] [--min-conf {high,medium,low}] [--scope {all,production,tests}] [--json]
| Argument | Meaning | Default | Values |
|---|---|---|---|
--depth DEPTH |
directory levels that make a module | 2 |
|
--limit LIMIT |
modules, dependencies and hotspots to show | 25 |
|
--min-conf MIN_CONF |
lowest edge confidence to follow: high, medium or low | medium |
high, medium, low |
--scope SCOPE |
all files, production only or tests only | all |
all, production, tests |
--json |
print the machine-readable JSON answer |
Functional map: declared purposes, their code references and witnessed direct links; technical candidates are separate.
cg [--root ROOT] flows [-h] [--limit LIMIT] [--max-chars MAX_CHARS] [--min-conf {high,medium,low}] [--json] [query]
| Argument | Meaning | Default | Values |
|---|---|---|---|
query (optional) |
words in the declared purpose or technical candidate name | `` | |
--limit LIMIT |
declared nodes to return, 1-100 | 25 |
|
--max-chars MAX_CHARS |
budget for the whole JSON answer including its newline, 512-16000 | 12000 |
|
--min-conf MIN_CONF |
lowest edge confidence to follow: high, medium or low | medium |
high, medium, low |
--json |
accepted for compatibility; flows always returns structured JSON |
Observations on the project structure and the resources it declares.
cg [--root ROOT] architecture [-h] [--json]
| Argument | Meaning | Default | Values |
|---|---|---|---|
--json |
print the machine-readable JSON answer |
Feature cards: groups of related code with their entry points.
cg [--root ROOT] features [-h] [--query QUERY] [--json]
| Argument | Meaning | Default | Values |
|---|---|---|---|
--query QUERY |
only features matching these words | `` | |
--json |
print the machine-readable JSON answer |
Evidence package for changing a feature: places, impact and tests, within a budget.
cg [--root ROOT] prepare [-h] [--symbol SYMBOL] [--verify-symbol VERIFY_SYMBOL] [--intent INTENT] [--max-chars MAX_CHARS] [--min-conf {high,medium,low}] [--depth {1,2,3}] [--json] [feature]
| Argument | Meaning | Default | Values |
|---|---|---|---|
feature (optional) |
feature name from features | ||
--symbol SYMBOL |
start from this symbol instead of a feature | ||
--verify-symbol VERIFY_SYMBOL |
also plan tests for this symbol (repeatable) | ||
--intent INTENT |
what the change should do, in words | `` | |
--max-chars MAX_CHARS |
budget for the whole answer in characters | 12000 |
|
--min-conf MIN_CONF |
lowest edge confidence to follow: high, medium or low | medium |
high, medium, low |
--depth DEPTH |
caller levels to follow | 2 |
1–3 |
--json |
print the machine-readable JSON answer |
Open the local dashboard in the browser.
cg [--root ROOT] explore [-h] [--workspace WORKSPACE] [--port PORT] [--no-open]
| Argument | Meaning | Default | Values |
|---|---|---|---|
--workspace WORKSPACE |
folder the dashboard may choose projects from | ~ |
|
--port PORT |
local port; 0 picks a free one | 0 |
|
--no-open |
print the URL without opening the browser |
Write an offline interactive HTML page of the call graph.
cg [--root ROOT] export [-h] [--output OUTPUT] [--symbol SYMBOL] [--depth {1,2,3,4,5}] [--min-conf {high,medium,low}] [--max-nodes MAX_NODES] [--max-edges MAX_EDGES] [--force]
| Argument | Meaning | Default | Values |
|---|---|---|---|
--output OUTPUT |
.html path inside the root (default: .code-graph/explore.html) | .code-graph/explore.html |
|
--symbol SYMBOL |
export only the neighbourhood of this symbol | ||
--depth DEPTH |
steps around --symbol | 2 |
1–5 |
--min-conf MIN_CONF |
lowest edge confidence to follow: high, medium or low | low |
high, medium, low |
--max-nodes MAX_NODES |
stop above this many nodes | 5000 |
|
--max-edges MAX_EDGES |
stop above this many edges | 50000 |
|
--force |
replace an existing HTML file |
Build or refresh the index (only files whose content changed are re-parsed).
cg [--root ROOT] index [-h] [--full]
| Argument | Meaning | Default | Values |
|---|---|---|---|
--full |
rebuild every file instead of only the changed ones |
Size of the index: files, lines, definitions, calls and edges by confidence.
cg [--root ROOT] stats [-h] [--json]
| Argument | Meaning | Default | Values |
|---|---|---|---|
--json |
print the machine-readable JSON answer |
Static candidates for defects: wrong argument counts, missing methods, call cycles between files, PHP name clashes.
cg [--root ROOT] check [-h] [--limit LIMIT] [--json] [--include-diagnostics]
| Argument | Meaning | Default | Values |
|---|---|---|---|
--limit LIMIT |
findings to show | 60 |
|
--json |
print the machine-readable JSON answer | ||
--include-diagnostics |
also list parser and analysis diagnostics |
Definitions nothing calls in the graph, with a verdict on how sure that is.
cg [--root ROOT] dead [-h] [--all] [--limit LIMIT]
| Argument | Meaning | Default | Values |
|---|---|---|---|
--all |
also show ambiguous and unverified candidates | ||
--limit LIMIT |
candidates to show | 60 |
API catalog: check (what the index uses that the catalog does not know) or validate.
cg [--root ROOT] catalog [-h] [--json] [--limit LIMIT] {check,validate}
| Argument | Meaning | Default | Values |
|---|---|---|---|
catalog_command |
check or validate | check, validate | |
--json |
print the machine-readable JSON answer | ||
--limit LIMIT |
entries to show | 40 |
Run the built-in parser and call-resolution checks.
cg [--root ROOT] selftest [-h]
No options.
MCP server on stdio for Codex, Claude Code and other clients (read-only tools).
cg [--root ROOT] mcp [-h]
No options.
Guided change with agents: plan, approval, isolated edit, tests and a review by the other model.
cg [--root ROOT] change [-h] ACTION ...
| Action | What it does |
|---|---|
new |
open a change from an intent; nothing runs yet |
list |
changes in this project and their state |
show |
state, plan, tests and review of a change |
plan |
ask the author for a plan grounded in the graph |
approve |
approve the plan and the exact test command; the tests run once now as the baseline |
edit |
let the author edit in its isolated worktree |
verify |
re-index, run the approved tests on the edit, compare with the baseline and review the diff statically |
review |
ask the reviewer to read the diff |
integrate |
bring the reviewed change into its branch, or merge it with --merge |
discard |
drop a change that is not integrated: its worktree and branch are removed, the archive is kept |
cancel |
stop the step that is running |
Open a change from an intent; nothing runs yet.
cg [--root ROOT] change new [-h] --intent INTENT --author {codex,claude} --reviewer {codex,claude} [--allow-dirty] [--budget-usd BUDGET_USD]
| Argument | Meaning | Default | Values |
|---|---|---|---|
--intent INTENT |
what the change should do, in words | required | |
--author AUTHOR |
model that plans and edits | required | codex, claude |
--reviewer REVIEWER |
model that reviews; normally the other one | required | codex, claude |
--allow-dirty |
start although the checkout has uncommitted changes | ||
--budget-usd BUDGET_USD |
spending cap passed to Claude when it is the author or reviewer |
Changes in this project and their state.
cg [--root ROOT] change list [-h]
No options.
State, plan, tests and review of a change.
cg [--root ROOT] change show [-h] id
| Argument | Meaning | Default | Values |
|---|---|---|---|
id |
change id, as printed by new and list |
Ask the author for a plan grounded in the graph.
cg [--root ROOT] change plan [-h] [--yes] id
| Argument | Meaning | Default | Values |
|---|---|---|---|
id |
change id, as printed by new and list | ||
--yes |
Confirm starting the agent and sending context to its provider |
Approve the plan and the exact test command; the tests run once now as the baseline.
cg [--root ROOT] change approve [-h] --test-argv TEST_ARGV [--no-tests-reason NO_TESTS_REASON] id
| Argument | Meaning | Default | Values |
|---|---|---|---|
id |
change id, as printed by new and list | ||
--test-argv TEST_ARGV |
test command as a JSON list of arguments, never a shell string | required | |
--no-tests-reason NO_TESTS_REASON |
why an empty test command is acceptable |
Let the author edit in its isolated worktree.
cg [--root ROOT] change edit [-h] [--yes] [--feedback FEEDBACK] id
| Argument | Meaning | Default | Values |
|---|---|---|---|
id |
change id, as printed by new and list | ||
--yes |
Confirm starting the agent and sending context to its provider | ||
--feedback FEEDBACK |
what to change in a new edit round |
Re-index, run the approved tests on the edit, compare with the baseline and review the diff statically.
cg [--root ROOT] change verify [-h] id
| Argument | Meaning | Default | Values |
|---|---|---|---|
id |
change id, as printed by new and list |
Ask the reviewer to read the diff.
cg [--root ROOT] change review [-h] [--yes] [--same-client-reason SAME_CLIENT_REASON] id
| Argument | Meaning | Default | Values |
|---|---|---|---|
id |
change id, as printed by new and list | ||
--yes |
Confirm starting the agent and sending context to its provider | ||
--same-client-reason SAME_CLIENT_REASON |
why the reviewer may be the same model as the author |
Bring the reviewed change into its branch, or merge it with --merge.
cg [--root ROOT] change integrate [-h] [--merge] [--force-reason FORCE_REASON] id
| Argument | Meaning | Default | Values |
|---|---|---|---|
id |
change id, as printed by new and list | ||
--merge |
merge into the base branch instead of leaving a branch | ||
--force-reason FORCE_REASON |
why to integrate although the review or the tests block it |
Drop a change that is not integrated: its worktree and branch are removed, the archive is kept.
cg [--root ROOT] change discard [-h] id
| Argument | Meaning | Default | Values |
|---|---|---|---|
id |
change id, as printed by new and list |
Stop the step that is running.
cg [--root ROOT] change cancel [-h] id
| Argument | Meaning | Default | Values |
|---|---|---|---|
id |
change id, as printed by new and list |