See how a repo fits together before you touch it
One command turns any codebase into an interactive flowchart: the whole repo as a tree on the left, and any node you pick drawn with what it depends on, what uses it, and what lives inside it.
Install from your agent, run on your machine - no model, no tokens.
12 modules import from here - the highest fan-in in the repo. session.ts is the file they all touch.
Used by
12 modules · 0 outward deps
Install
Install once, map any repo
Pick Claude Code or Codex, install birdsEye once, then run it in any repo. Both paths start the same local tree-sitter pipeline and write one self-contained map.
Claude Code
Use the Claude Code plugin marketplace and run the slash command in any repo.
- 00Open Claude Code
in your terminal
claude - 01Add the marketplace
once per machine
/plugin marketplace add tamalCodes/birdsEye - 02Install the plugin
once per machine
/plugin install birdseye@birdseye-marketplace - 03Build the map
inside any repo
/birdseye:map - 04Open the map
any browser, no server
birdseye/index.html
$ means terminal. > means agent prompt.
Needs Python 3.10+ on the machine (and ideally uv). birdsEye sets up its own virtualenv - point $BIRDSEYE_PYTHON at an interpreter to skip that.
Updating, and the one thing that can go wrong
Claude update
Auto-update is off for third-party marketplaces. Pull a new version, then install the plugin again.
/plugin marketplace update birdseye-marketplaceCodex update
Refresh the marketplace snapshot, then install the plugin again if a newer version is available.
codex plugin marketplace upgrade birdseye-marketplaceIf Claude marketplace add is refused
Marketplace names are global, so adding is refused when birdseye-marketplace is already registered on your machine from another source. Drop the old Claude registration, then add it again.
/plugin marketplace remove birdseye-marketplaceWhat it does
The first twenty minutes in a new repo, done for you
“Where does this live, what does it lean on, and what breaks if I change it?” Every time you - or an agent - opens an unfamiliar codebase, that is the question. birdsEye answers it from a picture instead of a grep, offline, in seconds.
The major modules, up front
The top level is a handful of boxes - the feature modules, plus one General-purpose group for the shared code everything imports. You see the spine of the repo before you read a line of it.
One node at a time
Pick a module, folder or file and the canvas draws that node alone: what it depends on to the left, what uses it to the right, and its own contents below. The whole graph is never dumped on screen, so a big repo stays as readable as a small one.
Dependency arrows that follow you
Every import, rolled up to whichever level is open. Select a node and the panel tells you exactly what it depends on and what depends on it - the plain-language blast radius.
Parsed, not guessed
80 file extensions through tree-sitter - TypeScript, Vue, Python, Go, Rust, Java, C#, Swift, Dart, SQL, Terraform and more. Deterministic: the same repo always produces the same map, so it diffs cleanly.
The map
One HTML file you can hand to anyone
- Click any file and it opens where you actually work - VS Code, Cursor, JetBrains, Zed.
- Self-contained: it opens from file:// with no server and no network at all.
- It remembers what you had expanded, and ships a light and a dark theme.
- The whole repo stays browsable as a collapsible tree beside the canvas.
How it works
No model in the loop. Zero tokens.
Extraction is a tree-sitter parse - it runs on your machine and reads nothing back to anyone. Everything else is a few hundred lines of Node. Same repo in, same map out, every time.
structure.mjs scan
Finds the code root and makes a first-pass guess at which folders are features and which are shared infrastructure.
ast.mjs
Parses every source file with tree-sitter, then resolves each import to the exact file it points at.
build.mjs
Rolls that flat graph into the containment tree - root, modules, folders, files - the viewer draws.
render.mjs
Inlines the vendored Cytoscape into one self-contained HTML file. No CDN, no server.
Where it stops
A map you can trust is a map that admits what it cannot see
Python 3.10+ is required
Parsing runs on tree-sitter, which birdsEye installs into its own virtualenv on the first run. No Python, no map.
A wrong edge is never guessed
An import resolves to a real file or it is left out. A missing edge is cheap; a wrong one poisons trust in the whole map.
Your source tree is left alone
Nothing is written into it except birdseye.config.json, and only after a direct yes. Setup asks one question at a time. The map and its cache live in a gitignored folder.
FAQ
Before you run it
What does it cost to run?
Nothing. There is no model call anywhere in the pipeline - extraction is a local tree-sitter parse. The only network access is a one-time pip install of the parser on the first run.
Does my code leave my machine?
No. Everything is parsed locally and reported nowhere. There is no birdsEye server - nothing is uploaded to us, because there is no us to upload to.
Which languages does it cover?
80 file extensions across 33 grammars - JavaScript/TypeScript, Vue, Svelte, Astro, Python, Go, Rust, Java, Kotlin, Scala, C#, PHP, Swift, Ruby, Dart, Perl, C/C++, CUDA, Objective-C, Lua, Elixir, Julia, Zig, OCaml, Fortran, Pascal, Verilog, Common Lisp, SQL, Terraform, PowerShell, shell, Groovy/Gradle and MSBuild project files. A file in an unsupported language still counts toward its folder's totals, it just has no dependency edges. A monorepo with several package roots is approximated as one today.
How stable is it?
Very early. Expect rough edges and breaking changes between versions. The earlier readiness, routes and docs views are dormant while the structure map settles.