Perceptor

Perceptor X-rays your repository: an interactive, Obsidian-style dependency & behavior map, with static complexity and data-access risk read straight off each method — rendered right inside VS Code.

• Graph mode — folders as connection-sized circle nodes, dependencies as edges, in a force layout.
• Folder mode — a collapsible tree (folder → type → behaviors), with a method detail panel.
• Method insight — for any method: a static Big-O / complexity read, data-access (SQL/ORM) risk signals (N+1, SELECT *, unbounded finds…), and a Simulate flow storyboard that animates, step by step, what the method receives, every call it makes, and what it returns.
• Explain — ask your own local Claude for a complete plain-English explanation of a method, inline in its detail panel.
• Change tasks — add / move / edit a behavior or create files & folders from the map; the work is carried out by your own local Claude. No server, no hosted backend, your tokens.

Screenshots

Folder mode — collapsible tree with a method detail panel:

Method insight — complexity, data-access risk, and the Simulate-flow storyboard:

Explain — ask your own local Claude about a method, inline:

Change tasks — review and apply changes carried out by your local Claude:

Quick start (3 steps)

1. Get the file — perceptor-<version>.vsix.
2. Install it — open VS Code → Extensions panel (left sidebar) → click the … menu at the top → Install from VSIX… → pick the file.
3. Open the map — open any project folder, then click Perceptor in the bottom status bar (or press Cmd/Ctrl+Shift+P and run Perceptor: Open).

That's it — the map appears and updates by itself. (Optional: the AI edit/explain features need the free claude CLI installed; the map works fine without it.)

Installation

From the VS Code Marketplace (easiest):

Open the Extensions panel (Cmd/Ctrl+Shift+X), search for Perceptor, and click Install — or from the command line:

code --install-extension berkcansavur.perceptor

From a packaged .vsix file:

code --install-extension perceptor-*.vsix

…or in VS Code: Extensions panel → … menu → Install from VSIX… → pick the file.

Then open any folder and run Perceptor: Open (see Usage). To update, install a newer build the same way.

Build the .vsix yourself:

npm install
npm run package        # → packages/extension/perceptor-<version>.vsix

Requires the claude CLI on your PATH only if you use the AI-powered explain/change tasks; the map itself works without it.

Usage

1. Open a folder/workspace in VS Code.
2. Cmd/Ctrl+Shift+P → Perceptor: Open (or use the status-bar item).
3. Switch between Graph and Folder modes, pan / zoom / search, click a type to open it in the editor.
4. In Folder mode, click a behavior to open its detail panel — complexity, data-access risk, the Simulate-flow storyboard (press Run), and Explain.

The map refreshes automatically as files change.

Supported languages

Settings

Privacy

Everything runs locally. The analyzer and task engine run in the extension host on your machine; explain/change tasks invoke your own claude CLI with your own tokens. No code leaves your machine through this extension.

License

MIT © Berkcan Şavur