Proto Atlas
Protobuf & gRPC schema visualizer for VS Code. See how your .proto files connect.
Proto Atlas opens a live, interactive graph next to your .proto file. Messages, enums and services
appear as cards, and edges run from each field or rpc to the type it uses. The graph follows your
cursor as you type, and clicking any card or field takes you back to its source line.
Status: early release (0.1.x). The core experience is in place and tested; the
roadmap lists what is next. Bug reports and feedback are very welcome.
Install
Requires VS Code 1.100 or later (desktop, or a browser host such as vscode.dev).
- Marketplace: open the Extensions view, search for Proto Atlas, and select Install. Or run
ext install yeoyujie.proto-atlas from the Quick Open prompt (Ctrl+P).
- From a
.vsix: run code --install-extension proto-atlas-<version>.vsix.
- From source: see Build from source.
Features
- Live schema graph. Message, enum and service cards with field rows, oneof groups, map fields and
nested types. Edges start at the exact field row that references a type; streaming rpcs animate.
- Two-way cursor sync. Moving the caret in the editor highlights the matching card and row and pans it
into view. Clicking in the graph reveals that line in the editor.
- Navigation that scales. ELK layered layout, arrow-key spatial navigation, double-click to focus
on a node, breadcrumbs, a minimap and a zoomed-out overview mode for large schemas.
- Whole-workspace awareness. Imports resolve across files using
buf.yaml / buf.work.yaml, your
workspace folders or custom import roots. Well-known google.protobuf.* types work without their sources.
- protoc-style diagnostics. Unresolved types, missing imports, duplicate or reserved field numbers
and names, proto3 enum-zero rules and more, shown on the affected cards and rows. Files with syntax
errors still render whatever parsed.
- proto2 and proto3, including groups,
required fields and reserved ranges.
- Fits your theme. Styled entirely from VS Code theme tokens, and checked in Dark Modern, Light Modern
and High Contrast.
- Works on the web. Runs in desktop VS Code and in browser hosts such as vscode.dev and github.dev.
- Plays well with others. Syntax highlighting only applies to
.proto files no other extension claims,
so it won't conflict with vscode-proto3
or Buf.
- Private. No telemetry and no network calls. Your schemas never leave your machine.
Usage
Open any .proto file, then use one of:
- the Open Preview to the Side button in the editor title bar
- Ctrl+K V (Cmd+K V on macOS)
- Proto Atlas: Open Preview or Proto Atlas: Open Preview to the Side from the Command Palette
The preview follows whichever .proto editor is active and updates as you type.
Settings
| Setting |
Default |
Description |
protoAtlas.importPaths |
[] |
Extra import roots, like protoc's -I. Relative paths resolve against each workspace folder. buf.yaml and buf.work.yaml are detected automatically. |
protoAtlas.hideWellKnownTypes |
false |
Hide google.protobuf.* types (such as Timestamp) from the graph. Fields still show the type name. |
Build from source
Requires Node.js 24 (see .nvmrc) and pnpm 10.
git clone https://github.com/yeoyujie/proto-atlas.git
cd proto-atlas
pnpm install
pnpm package # builds and writes a .vsix to apps/extension/
code --install-extension apps/extension/proto-atlas-*.vsix
Or run it without installing: open the repo in VS Code and press F5 (see
Development).
Roadmap
- Command palette for jumping to any type, focus mode, hover cards
- Export the graph as SVG/PNG
- Diagnostics overlay and visual regression tests
- Open VSX release
- Binary data inspector: decode protobuf payloads against your schema
Contributing
Issues and pull requests are welcome. For a bug report, include the VS Code version, the
extension version, and, where you can share it, a minimal .proto that reproduces the problem.
Before opening a pull request, run pnpm lint, pnpm typecheck and pnpm test; CI runs the
same checks plus the integration and end-to-end suites. Commit messages follow
Conventional Commits (feat(core): ..., fix(webview): ...).
Development
pnpm install
pnpm build # webview (Vite) + extension (esbuild)
pnpm test # Vitest unit and snapshot tests across all packages
pnpm test:integration # extension tests in a headless VS Code web host
pnpm test:e2e # Playwright end-to-end tests against VS Code web
pnpm typecheck
pnpm lint # Biome; `pnpm format` to fix
Press F5 in VS Code to launch the Extension Development Host (desktop and web launch configs
are included). To work on the UI on its own, pnpm samples generates graph data from fixtures/ for the
webview's browser dev harness.
Architecture
.proto sources ──► tree-sitter parse ──► extract (per file, cached) ──► link ──► ProtoGraph
│
webview (React Flow + ELK) ◄── typed messages ◄── GraphView projection
Only files that change are re-parsed, so a single-file edit rebuilds the graph in well under a millisecond
on the bundled fixtures.
| Path |
Purpose |
packages/core |
Pure TypeScript: parser → binder → ProtoGraph → projections. No vscode, no React. |
packages/protocol |
Typed, runtime-validated (Valibot) host ⇄ webview messages. |
packages/webview |
React 19 + Tailwind v4 UI rendered inside the VS Code webview. |
apps/extension |
The VS Code extension host, bundled for both desktop (Node) and web. |
fixtures |
Sample proto workspaces used by tests, snapshots and the dev harness. |
Acknowledgements
License
MIT © yeoyujie
