Skip to content
inth3shadowsPublic

About

Architecture diagrams that fail CI when they go stale. Generates call-graph and dependency diagrams from your code, embeds them in your docs, and fails the build when the code drifts.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Codeshot

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.


What it does

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.

In GitHub Actions

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.

Why this exists

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.

Install

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@latest

Codeshot 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:

  • codegraph CLI on PATH, 1.6.0 or later, with the target repo indexed (codegraph init). --architecture reads codegraph's index directly and needs the qualifiedName that 1.6.0's query --json carries; 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 --diff attribute 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.

Whole-repo architecture diagram

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 svg

Instead 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 first n directory segments and draw those as the nodes (--group-depth 1 on src/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-depth and --max-render, so neither can hide a violation.
  • --source snapshot:<file> — draw from a graph-assay snapshot (graph-assay/snapshot@1 JSON) 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's subject.name cut to letters, digits, ., _ and -, at most 40), so it can sit beside the codegraph one in the same doc. --path plays no part in that name. Edge kinds codeshot doesn't draw (another tool's overrides, say) are named on stderr rather than dropped silently. The default is --source codegraph; symbol and --diff modes reject --source.
  • --source scip[:<file>] — draw from a SCIP index (<--path>/index.scip by 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-symbols counts files, and codegraph isn't needed. The --embed marker and image name get -scip-<indexer> (codeshot-arch-scip-go.svg), plus the --path subdirectory when bare --source scip reads the index from there.
  • --depth and --max-depth-nodes have 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.

Diff-scoped diagram

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 svg

Instead 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 --diff diffs the working tree against HEAD (both staged and unstaged changes — "what have I changed right now"; note this is git diff HEAD, not bare git diff, which only covers unstaged edits and would miss anything already git added). --diff-ref <range> diffs an explicit ref or range instead (e.g. origin/main...HEAD) — use this form for --embed --check in 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-symbols apply here too: --limit bounds 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-symbols now caps how many changed symbols get probed (not the whole repo), and --max-render bounds 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.
  • --depth and --max-depth-nodes have no effect here and are rejected if set to anything but their defaults — no multi-hop traversal in this mode.
  • Composes with --embed/--check the same as the other modes — a changed-files diagram in a PR description, kept fresh and CI-guarded. --diff-ref gets its own marker id and default filename (codeshot:diff-<ref>, same pattern --group-depth uses 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 --diff keeps the plain codeshot:diff id.
  • 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).

Single-symbol trail

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 to 1, i.e. direct callers/callees only; must be a positive integer). Codeshot fetches this itself, one sequential codegraph call per newly discovered node — CodeGraph has no multi-hop traversal of its own for callers/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 sequential codegraph calls); Codeshot warns on stderr if it hit that cap before finishing — see --max-depth-nodes below 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 to 200; must be a positive integer). Only applies with --depth > 1; has no effect with --architecture or --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.

Flags shared by every mode

  • --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.svg without --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 your codegraph reports 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 --architecture the nodes are files (or groups, with --group-depth), busiest kept first; in --diff the 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 --limit keeps the truncation warning accurate but would otherwise produce an unreadably large image.
  • --format — output format, passed straight to dot -T<fmt> (defaults to png). svg is a good alternative for large graphs — it stays crisp at any zoom level and keeps text selectable, unlike a raster PNG. In svg (and svgz) 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 format dot -T supports works; an unsupported one fails with dot'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 (the doctoc/terraform-docs pattern). Without --out the 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: exit 0 if up to date, exit 1 if the code has drifted from the committed image. Built for a CI job / pre-commit hook so a stale diagram fails the build. For svg it compares graph structure, so CI needs no pinned graphviz; other formats compare bytes and do need the same graphviz version that generated the committed image.

Design decisions

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.

Upgrading from 0.4

  • --architecture draws 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 --check once with no code change: rerun the same --embed command and commit the result. With --max-render, a file tied with another for the last slot can swap in, which changes the picture once.

Upgrading from 0.3

0.4.0 is a Go rewrite with the same flags and output. Three things changed:

  • Default --embed image names no longer include the checkout directory (#51). If you embedded an --architecture or --diff diagram without --out, rename the committed image (codeshot-arch-myrepo.svg → codeshot-arch.svg) or rerun --embed once and commit the result. Diagrams embedded with an explicit --out are unaffected.
  • codegraph 1.6.0 is the minimum (was 1.5.0), because --architecture now always reads the index directly. CODESHOT_INDEX_READ is gone.
  • Install is a release binary or go install, not npm. In GitHub Actions, replace the npm install of codeshot with uses: inth3shadows/codeshot@<sha>.

Status

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.

Related Documentation

About

Architecture diagrams that fail CI when they go stale. Generates call-graph and dependency diagrams from your code, embeds them in your docs, and fails the build when the code drifts.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages