{"id":51847108,"url":"https://github.com/inth3shadows/codeshot","last_synced_at":"2026-07-23T14:01:58.809Z","repository":{"id":368863205,"uuid":"1175400625","full_name":"inth3shadows/codeshot","owner":"inth3shadows","description":"Claude Code companion: click code blocks in your terminal to stage them in a new Windows Terminal or iTerm2 tab","archived":false,"fork":false,"pushed_at":"2026-07-14T00:16:15.000Z","size":81,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-14T01:15:46.435Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inth3shadows.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-07T16:59:09.000Z","updated_at":"2026-07-14T00:16:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/inth3shadows/codeshot","commit_stats":null,"previous_names":["inth3shadows/codeshot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/inth3shadows/codeshot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inth3shadows%2Fcodeshot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inth3shadows%2Fcodeshot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inth3shadows%2Fcodeshot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inth3shadows%2Fcodeshot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inth3shadows","download_url":"https://codeload.github.com/inth3shadows/codeshot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inth3shadows%2Fcodeshot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35804545,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-23T14:01:58.303Z","updated_at":"2026-07-23T14:01:58.796Z","avatar_url":"https://github.com/inth3shadows.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Codeshot\n\n**A picture of what calls what.** Renders a symbol's [CodeGraph](https://github.com/colbymchenry/codegraph) call trail (who calls it, what it calls) — or a whole repo's file-level dependency graph — as an image.\n\n---\n\n## What it does\n\n```bash\ncodeshot RollAutoSnapshot --path ~/code/myrepo --out callgraph.png\n```\n\nPulls the symbol's callers/callees straight from CodeGraph's index (`codegraph callers`/`callees --json`) and renders them through [graphviz](https://graphviz.org/) — a real diagram, not hand-drawn ASCII. Test callers are shown dashed so production call paths stand out; a module-level/import reference CodeGraph couldn't resolve to a real call site is shown dotted-gray instead of looking like a confirmed call.\n\n## Why this exists\n\n`TECHNICAL.md`-style docs usually stop at a whole-system, hand-drawn diagram — accurate for the big picture, but nobody hand-draws a diagram for \"what exactly touches this one function.\" Codeshot fills that gap: point it at a symbol, get back a picture, generated from the live index instead of remembered or redrawn by hand.\n\n## Install\n\n```bash\nnpm install -g github:inth3shadows/codeshot\n```\n\n**Requirements:**\n- Node.js ≥ 18\n- [`codegraph`](https://github.com/colbymchenry/codegraph) CLI on PATH, with the target repo indexed (`codegraph init`)\n- `graphviz` (`dot`) on PATH — `brew install graphviz` / `apt install graphviz`\n\nCodeshot checks for both on startup and tells you exactly what's missing and how to install it.\n\n## Usage\n\n```bash\ncodeshot \u003csymbol\u003e [--path \u003crepoPath\u003e] [--out \u003cfile.png\u003e] [--limit \u003cn\u003e] [--max-render \u003cn\u003e] [--format \u003cfmt\u003e] [--depth \u003cn\u003e]\n```\n\n- `--path` — repo to query (defaults to cwd)\n- `--out` — output file (defaults to a temp file named after the chosen `--format`; path is printed on success). 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.\n- `--limit` — max callers/callees to fetch (defaults to 50; must be a positive integer). Codeshot warns on stderr if a result may be truncated — see [TECHNICAL.md](TECHNICAL.md#configuration) for why and its one known false-positive case.\n- `--max-render` — cap how many distinct nodes are drawn in the image, independent of `--limit` (unset by default: no cap). This is one shared budget across callers, callees, and `--depth`'s transitive edges combined — not a separate `N` for each. Useful for symbols with hundreds of callers, where a high `--limit` keeps the truncation warning accurate but would otherwise produce an unreadably tall image.\n- `--format` — output format, passed straight to `dot -T\u003cfmt\u003e` (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 node also carries the file its symbol 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.\n- `--embed \u003cfile.md\u003e` — instead of just writing an image, insert (or, on re-runs, refresh in place) the diagram inside an existing markdown doc, using idempotent `\u003c!-- codeshot:\u003cid\u003e:start/end --\u003e` markers (the `doctoc`/`terraform-docs` pattern). The image is written to a stable path next to the doc so the relative link resolves and both can be committed. Refreshes an existing doc — it won't create one. Works in both symbol and `--architecture` mode. See [USAGE.md](USAGE.md#embedding-a-diagram-in-your-docs-and-keeping-it-fresh).\n- `--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. Compares rendered bytes, so it needs the same `graphviz` version that generated the committed image.\n- `--depth` — how many hops of callers-of-callers / callees-of-callees to draw beyond the direct trail (defaults to `1`, i.e. today's direct-only behavior; 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 an internal, non-configurable 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 [TECHNICAL.md](TECHNICAL.md#configuration) for the exact number and rationale.\n\n## Whole-repo architecture diagram\n\n```bash\ncodeshot --architecture --path ~/code/myrepo --out architecture.svg --format svg\n```\n\nA second mode, distinct from the single-symbol trail above: instead of one\nsymbol's callers/callees, it enumerates every symbol in the repo's CodeGraph\nindex and probes each one's callees, then aggregates the results into a\n**file-to-file** dependency graph (edge label = number of calls between that\npair of files). Self-file edges (a function calling another function in the\nsame file) are dropped — this is about cross-file coupling, not intra-file\nstructure. Test files render dashed, same visual language as symbol mode.\n\nThis is a real, data-derived graph, not a hand-drawn architecture diagram —\nit won't look like a curated conceptual pipeline diagram, it'll look like\nwhat the code actually calls into. On a repo of any real size this is a\nslow operation (one sequential `codegraph` call per enumerated symbol), so\ntwo extra flags exist specifically for this mode:\n- `--max-symbols` — cap how many symbols get probed (default 500). Codeshot\n  warns on stderr if this cuts the scan short.\n- `--depth` has no effect here and is rejected if passed — there's no\n  multi-hop file-traversal concept to apply it to.\n\n`--limit` and `--max-render` are reused with the same meaning as symbol\nmode (callees fetched per probed symbol; distinct nodes actually drawn,\nhere ranked by busiest file rather than caller/callee priority).\n\nSee [TECHNICAL.md](TECHNICAL.md#architecture) for the known limitation\naround same-named symbols across files, and why the graph can be slow on\nlarger repos.\n\n## Design decisions\n\n**Why shell out to the CodeGraph CLI instead of reading its SQLite index directly?**\nThe CLI's `--json` output is a stable, documented contract; the on-disk schema isn't. Slower, but survives CodeGraph upgrades.\n\n**Why graphviz instead of a JS graph-drawing library?**\nZero new npm dependencies, and `dot` already produces clean, deterministic layouts — no layout algorithm to hand-tune.\n\n**Standalone tool, not a CodeGraph PR — for now.** A native `codegraph render` would be strictly better (no shell-out, ships free via MCP). This stays a separate tool until it's proven useful across real repos; premature upstreaming risks getting redesigned in review before the idea is validated.\n\n## Status\n\nEarly — 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.\n\n**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`](install/uninstall-legacy.ps1) (Windows) or [`install/uninstall-legacy.sh`](install/uninstall-legacy.sh) (macOS) once to remove the leftover protocol handler registration, Claude Code Stop hook entry, and `~/.codeshot` directory.\n\n## Related Documentation\n\n- [Technical Reference](TECHNICAL.md) — architecture, file descriptions, configuration, maintenance\n- [Usage Guide](USAGE.md) — day-to-day usage and troubleshooting\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finth3shadows%2Fcodeshot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finth3shadows%2Fcodeshot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finth3shadows%2Fcodeshot/lists"}