The docs-and-CI layer for CodeGraph. CodeGraph indexes your code so you (or an agent) can explore it. Codeshot turns that index into diagrams you commit to your docs, and into checks your build runs, so the architecture you wrote down stays the architecture you have, without anyone having to look.
Three jobs:
| Job | Command | Result |
|---|---|---|
| Keep doc diagrams honest | --embed <doc.md> --check |
exit 1 when the code has drifted from the diagram committed in your docs |
| Enforce architecture rules | --architecture --forbid 'src/ui/->src/db/' |
exit 1 when a file edge crosses a forbidden boundary (drawn red, listed on stderr) |
| Show what a PR touches | --diff --diff-ref origin/main...HEAD |
a diagram of the symbols defined in changed files (up to --max-symbols), with their callers/callees, for review |
# docs: embed (or refresh) a file-level architecture diagram in TECHNICAL.md
codeshot --architecture --out architecture.svg --embed TECHNICAL.md --format svg
# CI, one scan: exit 1 if that diagram no longer matches the code,
# or if the UI layer calls straight into the database layer
codeshot --architecture --out architecture.svg --embed TECHNICAL.md --format svg \
--check --forbid 'src/ui/->src/db/'Without --out, --embed writes the image next to the doc as codeshot-arch.<fmt> (codeshot-arch-d<n>, codeshot-diff[-<ref>]), the same in every clone. A --path below the repo root adds that subpath (codeshot-arch-services_api.<fmt>), so docs in one directory diagramming different subtrees don't share an image. Before 0.4.0 that name included the checkout directory; see Upgrading from 0.3.
For svg, --check compares graph structure (which nodes, which edges), not bytes, so a laptop and CI with different graphviz versions agree. It never writes, and it refuses to replace a real committed diagram with a blank one. Graphviz is the only thing it is tolerant of: generate the committed diagram with the same codegraph build as CI. Different codegraph builds can draw different edges for same-named symbols (see TECHNICAL.md).
Everything comes straight from CodeGraph's index and renders through graphviz, so it works for whatever languages CodeGraph indexes. Test callers are drawn dashed so production paths stand out; a module-level reference CodeGraph couldn't resolve to a real call site is drawn dotted-gray instead of looking like a confirmed call.
diagrams:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
# codegraph is a Node CLI (Node 22; it refuses 25+). codeshot itself is a Go binary.
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
with:
node-version: "22"
- run: sudo apt-get update && sudo apt-get install -y graphviz
- run: npm install -g @colbymchenry/codegraph@1.6.0
- uses: inth3shadows/codeshot@<commit-sha> # v0.4.0; puts `codeshot` on PATH
- run: codegraph init .
- run: >-
codeshot --architecture --out architecture.svg --embed TECHNICAL.md
--format svg --check --forbid 'src/ui/->src/db/'Use the same codegraph version locally when you regenerate the diagram. This repo's own ci.yml runs the same kind of gate, but against a pinned codegraph fork built from source, so its committed diagrams are generated with that fork, not npm.
Generated diagrams are easy; trusted ones aren't. Tools like madge, pyan and go-callvis draw the code as it is right now, on demand. None of them notices when the picture in your README stopped being true. Codeshot's diagrams are artifacts: committed next to the prose that explains them, regenerated by one command, and checked by the build like any other test.
Download a binary for your platform from Releases (checksums in checksums.txt), or build from source with Go 1.26+:
go install github.com/inth3shadows/codeshot/cmd/codeshot@latestCodeshot is a single static binary; it needs no Node of its own. codeshot --version prints the release version for release binaries and go install ...@vX.Y.Z, and dev for any other build.
Requirements:
codegraphCLI on PATH, 1.6.0 or later, with the target repo indexed (codegraph init).--architecturereads codegraph's index directly and needs thequalifiedNamethat 1.6.0'squery --jsoncarries; earlier builds also have a call-resolution bug that fabricates cross-file edges. A codegraph with upstream PR #1801 (merged after 1.6.0, not yet in an npm release; the inth3shadows/codegraph fork has it) additionally lets--diffattribute same-named symbols to the right file; CI runs that fork.graphviz(dot) on PATH —brew install graphviz/apt install graphviz
Codeshot checks for both on startup and tells you exactly what's missing and how to install it.
codeshot --architecture --path ~/code/myrepo --out architecture.svg --format svg
# ...or, on a repo with more files than fit in one readable picture:
codeshot --architecture --path ~/code/myrepo --group-depth 1 --out modules.svg --format svgInstead of one symbol's callers/callees, this mode enumerates every symbol in the repo's CodeGraph index, collects each one's callees, then aggregates the results into a file-to-file dependency graph (edge label = number of calls between that pair of files). Self-file edges (a function calling another function in the same file) are dropped — this is about cross-file coupling, not intra-file structure. Test files render dashed.
This is a real, data-derived graph, not a hand-drawn architecture diagram —
it won't look like a curated conceptual pipeline diagram, it'll look like
what the code actually calls into. Codeshot enumerates symbols with one
codegraph query and reads every callee edge from codegraph's index
(.codegraph/codegraph.db, found at or above --path) in one read-only query,
so the scan takes about a second. Flags specific to this mode:
--max-symbols— cap how many symbols get probed (default 500). Codeshot warns on stderr if this cuts the scan short.--group-depth <n>— roll files up into their firstndirectory segments and draw those as the nodes (--group-depth 1onsrc/api/user.js→src/), summing the call weights of every file pair that collapses into the same pair of groups. This is the readable view of a repo big enough that the per-file graph is a hairball. Unlike--max-render, which drops the least-busy files outright — taking every edge that touched them with it — grouping keeps every cross-module call and just draws it at module resolution. Calls that become intra-group are dropped, for the same reason same-file calls already are: this diagram is about coupling between modules, not inside them. So the summed weights on a grouped diagram are legitimately lower than the per-file one's, often much lower — that's the intra-module traffic, not a lost edge. Repo-root files (no directory to roll into) stay themselves.--forbid <from>-><to>— an architecture rule; repeat it for several. Each side is a repo-relative path: ending in/it means every file under that directory, otherwise one exact file (--forbid 'src/ui/->src/db/'). Any file edge a rule matches is listed on stderr with its weight and drawn red, and the run exits 1 after the diagram is written, so CI fails with the picture as evidence. Rules are checked on the per-file edges, before--group-depthand--max-render, so neither can hide a violation.--source snapshot:<file>— draw from a graph-assay snapshot (graph-assay/snapshot@1JSON) instead of the codegraph index under--path. Any tool graph-assay has an adapter for can feed the diagram this way, and codegraph doesn't need to be installed. A snapshot exported from a codegraph index draws the same diagram, byte for byte, as reading that index. With--embed, a snapshot diagram gets its own marker and image name (codeshot-arch-snapshot-<tool>.<fmt>, where<tool>is the snapshot'ssubject.namecut to letters, digits,.,_and-, at most 40), so it can sit beside the codegraph one in the same doc.--pathplays no part in that name. Edge kinds codeshot doesn't draw (another tool'soverrides, say) are named on stderr rather than dropped silently. The default is--source codegraph; symbol and--diffmodes reject--source.--source scip[:<file>]— draw from a SCIP index (<--path>/index.scipby default), as written by scip-go, scip-typescript, scip-python and other compiler-backed indexers. A file depends on another when it refers to a symbol defined there; a reference to a package alone (a Go import) draws nothing. Edges are file to file (SCIP indexers such as scip-go record no enclosing function), so--max-symbolscounts files, and codegraph isn't needed. The--embedmarker and image name get-scip-<indexer>(codeshot-arch-scip-go.svg), plus the--pathsubdirectory when bare--source scipreads the index from there.--depthand--max-depth-nodeshave no effect here and are rejected if set to anything but their defaults — there's no multi-hop file-traversal concept to apply them to.
Of the shared flags, --max-render caps the
distinct files (or groups, with --group-depth) drawn, busiest first. The
index read is complete, so --limit has no effect in this mode; passing it prints a warning.
A name that exists in more than one file (two handles, or two index.js
files) has its edges attributed to the right file: the index read keys each
definition by name, file and qualified name, so same-named symbols never share
an answer. See TECHNICAL.md.
codeshot --diff --path ~/code/myrepo --out changed.svg --format svg
# ...or against a specific range/ref, for reproducibility in CI:
codeshot --diff --diff-ref origin/main...HEAD --path ~/code/myrepo --out pr.svg --format svgInstead of the whole repo or one named symbol, this mode diagrams
just the symbols defined in changed files — every symbol codegraph's
index attributes to a file git diff reports as touched — bolded as the
diagram's roots, with their direct callers/callees fanned out around them
in the usual house style. Built on the same per-symbol callers/callees
fetch as single-symbol mode, just run once per changed
symbol instead of once for the one you named.
- No value after
--diffdiffs the working tree against HEAD (both staged and unstaged changes — "what have I changed right now"; note this isgit diff HEAD, not baregit diff, which only covers unstaged edits and would miss anything alreadygit added).--diff-ref <range>diffs an explicit ref or range instead (e.g.origin/main...HEAD) — use this form for--embed --checkin CI, where there's no working tree to diff and the default would make the check flap for reasons unrelated to the code. --limit,--max-render, and--max-symbolsapply here too:--limitbounds each changed symbol's callers/callees fetch (per definition, with a codegraph that reports them — so a changed symbol whose name also exists in another file, and has two definitions in its own, can bring in more than--limit),--max-symbolsnow caps how many changed symbols get probed (not the whole repo), and--max-renderbounds only the callers/callees pulled in around the changed symbols — every changed symbol itself is always drawn, since it's the reason the diagram exists.--depthand--max-depth-nodeshave no effect here and are rejected if set to anything but their defaults — no multi-hop traversal in this mode.- Composes with
--embed/--checkthe same as the other modes — a changed-files diagram in a PR description, kept fresh and CI-guarded.--diff-refgets its own marker id and default filename (codeshot:diff-<ref>, same pattern--group-depthuses for--architecture), so a release-range diagram and a PR-range diagram can live in the same doc without one silently overwriting the other; a bare--diffkeeps the plaincodeshot:diffid. - A changed symbol whose name also exists in another file gets only its own file's callers/callees on a codegraph that reports them per definition (upstream #1801, unreleased after 1.6.0). Otherwise, including npm 1.6.0, it gets the merged result for every same-named definition, and codeshot warns rather than silently misattributing edges (see TECHNICAL.md).
Codeshot can also draw one symbol's caller/callee trail as a static image:
codeshot RollAutoSnapshot --path ~/code/myrepo --out callgraph.png
# full form
codeshot <symbol> [--path <repoPath>] [--out <file>] [--limit <n>] [--max-render <n>] [--format <fmt>] [--depth <n>]For ad-hoc exploration, CodeGraph's own codegraph node, callers and callees answer faster. This mode earns its place when you want that trail embedded in a doc (--embed) and kept current (--check).
Two flags apply only to this mode:
--depth— how many hops of callers-of-callers / callees-of-callees to draw beyond the direct trail (defaults to1, i.e. direct callers/callees only; must be a positive integer). Codeshot fetches this itself, one sequentialcodegraphcall per newly discovered node — CodeGraph has no multi-hop traversal of its own forcallers/callees. Each additional hop is drawn in a progressively lighter shade so you can tell how far a node is from the symbol at a glance. There's a safety cap on total nodes discovered (a well-connected symbol at--depth 3+ can otherwise mean hundreds of sequentialcodegraphcalls); Codeshot warns on stderr if it hit that cap before finishing — see--max-depth-nodesbelow to raise it, or TECHNICAL.md for the default and rationale.--max-depth-nodes— raises (or lowers)--depth's safety cap on total discovered nodes (defaults to200; must be a positive integer). Only applies with--depth > 1; has no effect with--architectureor--diff, and is rejected there if set to anything but its default. Useful for a genuinely well-connected symbol whose graph is real but incomplete at the default cap — see the depth-budget warning it's meant to answer.
--path— repo to query (defaults to cwd)--out— output file (defaults to a temp file named after the chosen--format; path is printed on success). Its directory must already exist. If the extension doesn't match--format(e.g.--out diagram.svgwithout--format svg), Codeshot warns on stderr instead of silently writing the wrong data under that name.--limit— max callers/callees fetched per symbol (defaults to 50; must be a positive integer); see each mode for what it bounds there. Codeshot warns on stderr when results were cut off, naming the real total when yourcodegraphreports one — see TECHNICAL.md for what older versions fall back to.--max-render— cap how many distinct nodes are drawn in the image, independent of--limit(unset by default: no cap). In--architecturethe nodes are files (or groups, with--group-depth), busiest kept first; in--diffthe changed symbols are always drawn and the cap covers only the callers/callees around them; in single-symbol mode it is one shared budget across callers, callees, and--depth's transitive edges. Useful when a high--limitkeeps the truncation warning accurate but would otherwise produce an unreadably large image.--format— output format, passed straight todot -T<fmt>(defaults topng).svgis a good alternative for large graphs — it stays crisp at any zoom level and keeps text selectable, unlike a raster PNG. Insvg(andsvgz) output, each symbol node also carries the file it lives in as a hover tooltip, so you can tell same-named symbols apart without cluttering the boxes (open the file in a browser to see them; GitHub's SVG sanitizer may strip tooltips when the image is embedded in a README). Any formatdot -Tsupports works; an unsupported one fails withdot's own error listing the valid ones.--embed <file.md>— instead of just writing an image, insert (or, on re-runs, refresh in place) the diagram inside an existing markdown doc, using idempotent<!-- codeshot:<id>:start/end -->markers (thedoctoc/terraform-docspattern). Without--outthe image goes next to the doc under a fixed name (codeshot-arch.<fmt>,codeshot-diff.<fmt>,codeshot-callgraph-<symbol>.<fmt>), so it is the same in every clone. Refreshes an existing doc — it won't create one. Works in every mode. See USAGE.md.--check— (only with--embed) verify the committed diagram and its doc block are current without changing anything: exit0if up to date, exit1if the code has drifted from the committed image. Built for a CI job / pre-commit hook so a stale diagram fails the build. Forsvgit compares graph structure, so CI needs no pinnedgraphviz; other formats compare bytes and do need the samegraphvizversion that generated the committed image.
Why the CodeGraph CLI, with a direct index read only for --architecture?
The CLI's --json output is a stable, documented contract; the on-disk schema isn't. --architecture is the exception: through the CLI it needs one process per symbol (48.7s on this repo), so it reads .codegraph/codegraph.db read-only instead (about a second), and fails with a clear message if the schema has changed. --diff and single-symbol mode use the CLI only.
Why Go? One static binary with no runtime to install, a pure-Go SQLite driver (modernc.org/sqlite, no cgo) that reads codegraph's index the same way on every platform, and the language of SCIP's reference tooling, which is the next graph source on the roadmap.
Why graphviz instead of a graph-drawing library?
dot already produces clean, deterministic layouts — no layout algorithm to hand-tune.
Standalone tool, not a CodeGraph PR. CodeGraph's upstream main has an interactive viewer (codegraph ui, not yet in a release) for exploration; Codeshot stays out of that lane and owns the committed, CI-checked side — embedded diagrams, drift checks, architecture rules. Those are build-pipeline concerns a code index doesn't need to carry, and keeping them separate lets each evolve on its own release cadence.
--architecturedraws edges in a fixed order. Each symbol's edges are now ordered by target file (and symbols with the same file and name by qualified name), so the codegraph index and a snapshot of it draw the same bytes. The graph is unchanged, but the order of statements in the DOT can change once. Committed SVG diagrams still pass--embed --check, which compares structure. A committed PNG or DOT diagram can fail--checkonce with no code change: rerun the same--embedcommand and commit the result. With--max-render, a file tied with another for the last slot can swap in, which changes the picture once.
0.4.0 is a Go rewrite with the same flags and output. Three things changed:
- Default
--embedimage names no longer include the checkout directory (#51). If you embedded an--architectureor--diffdiagram without--out, rename the committed image (codeshot-arch-myrepo.svg→codeshot-arch.svg) or rerun--embedonce and commit the result. Diagrams embedded with an explicit--outare unaffected. - codegraph 1.6.0 is the minimum (was 1.5.0), because
--architecturenow always reads the index directly.CODESHOT_INDEX_READis gone. - Install is a release binary or
go install, not npm. In GitHub Actions, replace the npm install of codeshot withuses: inth3shadows/codeshot@<sha>.
Early — actively used and maintained on real repos. Previous design (a terminal protocol-handler for staging Claude Code's suggested commands) was retired; see git history if you're curious what that looked like.
Ran the old installer? If you installed the retired design (install/install.ps1 or install/install.sh, no longer in this repo), run install/uninstall-legacy.ps1 (Windows) or install/uninstall-legacy.sh (macOS) once to remove the leftover protocol handler registration, Claude Code Stop hook entry, and ~/.codeshot directory.
- Technical Reference — architecture, file descriptions, configuration, maintenance
- Usage Guide — day-to-day usage and troubleshooting