Repository navigation
Pathfinder v0.1.3
Pathfinder v0.1.3
Release notes for the changes made after v0.1.2, the last release shipped to testers. They include the interim v0.1.2c work (basic PHP support).
Summary
v0.1.3 makes Pathfinder work better with AI assistants and brings deep dive to the new 3D view.
- AI assistants are now told when to use Pathfinder instead of searching files, and receive smaller, drill-down results.
- Long scans no longer cut off an AI's tool call.
- The 3D perspective view is new, and deep dive works in it with the same gestures as 2D.
- The module map and deep-dive symbol cells now share one placement logic.
- Pathfinder shows when it is working.
launch.batreuses a running server or replaces it with the current build.- PHP projects are now scanned.
- HTML, PHP and CSS files now link to the assets they reference.
AI assistant integration
Pathfinder tells the assistant when to use it
Before this release, enabling an integration only registered Pathfinder's MCP server. The assistant received the tools but no guidance on when they beat searching files, so it usually fell back to grep. Pathfinder now delivers that guidance itself:
- On connect. The MCP server sends instructions with its handshake: use Pathfinder before grep for "what uses X", "what does X connect to", "what breaks if I change X", or an unfamiliar area. Claude Code loads these at session start, even while the tools themselves are deferred. This reaches every project that is already enabled; no action needed.
- In each tool description. Each description now opens with the question it answers, for example "Who uses, imports, or calls this file or node?". Tool search matches on this text.
- In the project's instruction file. Enabling an integration also writes a marked section to the client's instruction file. Disabling removes only that section. Your own content in the file is never changed, and the file is deleted only if Pathfinder's section was all it contained.
| Client | Configuration (as before) | Instruction file (new) |
|---|---|---|
| Claude Code | .mcp.json |
CLAUDE.md |
| Codex | .codex/config.toml |
AGENTS.md |
| VS Code (Copilot) | .vscode/mcp.json |
.github/copilot-instructions.md |
The integration panel and the integrations enable command now say which files they write.
Progressive deep dive
pathfinder_deep_dive now works the way the deep-dive UI does: open the module, then focus one symbol at a time.
| Target | Result |
|---|---|
| A module with up to 60 symbols | Every symbol and call, as before |
| A larger module | An overview: entry points, the most-connected symbols, the boundary with other modules, orphans, and a one-line index of every symbol |
| A symbol's stable key or label | That symbol in focus: what it calls and what calls it, with call sites |
Any module with view: "full" |
Every symbol and call |
On Pathfinder's own 234-symbol client file, the overview is 9.6KB and one symbol's focus is 5KB. The previous single result was 319KB.
Smaller results
All MCP results are now written compactly, without losing anything. Defaults, nulls, repeated fields and repeated key prefixes are stated once, and each result begins with a short legend explaining the rules. Measured on this repository:
| Tool | Before | After |
|---|---|---|
pathfinder_deep_dive, full view of a 234-symbol file |
319KB | 81KB |
pathfinder_working_set, three files |
51KB | 21KB |
pathfinder_impact |
47KB | 23KB |
lib/api.js still returns the full, uncompacted shapes. Compaction applies only to what an MCP client receives.
Scans no longer cut off a tool call
pathfinder_scanno longer blocks the MCP server. Other tool calls keep being answered while a scan runs.- A scan still running after 45 seconds continues in the background. The call returns "still running" instead of hitting the client's timeout.
pathfinder_statusreports the scan's state (running,doneorfailed) and its elapsed time.- A second scan request while one is running joins the running scan instead of starting another.
- Clients that request progress receive an update every 5 seconds.
- The 45-second wait can be changed with the
PATHFINDER_MCP_SCAN_WAIT_MSenvironment variable.
Assistants can keep module descriptions current
A new MCP tool, pathfinder_set_description, lets an assistant update a file's or module's description: the same field as the Description panel in the graph. Everything it writes starts with "[AI generated]", so it is never mistaken for a description a person wrote. It can't clear a description; use the graph UI or pathfinder describe for that.
Protocol
The MCP server now accepts MCP protocol versions 2025-06-18, 2025-03-26 and 2024-11-05, answering with the client's requested version when supported.
3D perspective view
New: View > 3D perspective
The graph can be viewed in perspective. Right-drag to orbit; a right-click without dragging still opens the context menu. Double-click a module to deep dive into it, and double-click empty space to leave. An axis gizmo shows the current orientation. Nodes dragged in 3D move in the plane you are looking at, and depth is kept per browser.
Deep dive works in 3D
Before this release, deep dive in 3D was unusable. Symbols drew about 23 times too large and covered the cell, and neighbouring modules could fill the screen. 3D now uses the same zoom model as 2D, so the deep-dive experience carries over:
- Symbols and labels are the same size as in 2D, with perspective making nearer ones larger.
- Scrolling into a module enters its deep dive, and scrolling back out leaves it.
- Entering a cell, warping across a call and leaving all animate, and Back/Forward (the mouse's side buttons) work.
- Panning moves the orbit centre, so orbiting always pivots on what is in the middle of the view.
- Switching between 2D and 3D keeps the same view and zoom, including mid deep-dive.
- Anything behind the camera is no longer drawn. Things very close to the camera fade out, connections are cut cleanly at the camera, and nearer nodes draw over farther ones.
Layout
One placement logic for the module map and symbol cells
Deep-dive cells now use the same placement engine as the module map: connected things are pulled together, and the most-connected symbol sits at the centre. On top of that, cells:
- set aside symbols with no calls inside the file in a ring around the call structure, the same way the module map sets aside unconnected modules;
- spread the result evenly across the cell, and keep symbols far enough apart that their labels don't stack in the flat view.
Measured across eight files of this repository, no two symbols now sit closer than about one label's height, where previously 91 pairs did.
- The module map's own layout is unchanged; it was verified identical module by module.
- New modules found by a rescan are now placed with the same engine, in all three axes. They previously always landed at depth 0.
- Hand-placed symbols keep their positions, and a symbol dragged in 3D now keeps its depth.
- Reset Layout also clears hand-placed symbol positions inside deep-dive cells.
Scanning
PHP support
PHP files are now part of the graph at file level:
requireandincludeconnect files, including the common__DIR__ . '/path'anddirname(__FILE__) . '/path'forms.usestatements connect to the file named after the class, following the usual PSR-4 convention. Groupusestatements aren't handled yet.- Top-level functions and classes are recorded.
Deep dive into PHP symbols isn't available yet; diagnostics say so for each PHP file.
Asset references
HTML and PHP files now link to the scripts, stylesheets and images they load (<script src>, <link href>, <img src>). CSS files now link to what they @import or reference with url(...). These appear as references_asset connections between files. Only references that resolve to a file in the project are recorded.
Interface
Working indicator
A small "working" pill appears in the bottom-left corner during anything slow: scanning, building the AI brief, generating a report, exporting JSON, comparing snapshots, reconciling, loading a deep dive and laying out the graph. It shows only for operations that take longer than a quarter of a second, so quick saves don't flicker it. The Rescan button is disabled while a scan runs.
Documentation files filter
Declutter has a new "Documentation files" option covering .md, .rst, .txt and similar files. Like test files, these are hidden by default.
Launching
Running launch.bat while Pathfinder is already running no longer opens the old server and then crashes. It now checks what is running on the port:
| Already running | Result |
|---|---|
| Nothing | Starts normally |
| Pathfinder, current build | Opens it in the browser and exits |
| Pathfinder, older build | Shuts it down and starts the current one |
| Another program | Leaves it alone and says so |
"Current build" means the running server's code matches the code on disk, so any change since it started counts as older. The packaged release's launchers (pathfinder.bat, pathfinder.sh) behave the same way. The same behavior is available from the command line as pathfinder serve --reuse.
Starting pathfinder serve on a port that's already taken now prints a plain explanation instead of a stack trace.
Fixes
- Database stall during scans. Every query made while a scan was writing waited about 5.5 seconds for a database lock, then carried on. Queries during a scan now take a few milliseconds.
- Deep dive ignored symbol targets. Asking for one symbol returned its whole file.
- Deep dive
limitdidn't limit output. It capped the symbol list but still returned every call; in the full view it now limits both. - Entry points listed as orphans. Framework-invoked entry points, such as HTTP routes and module startup, were reported as orphans in deep dive and diagnostics because nothing in the code calls them. They are no longer listed, so genuine dead code stands out.
- Planned modules missing from the AI briefing. Modules planned with the graph's New module button were left out of the briefing, which only read imported plans. Both now appear.
- Version reporting. The MCP server reported version 0.1.0 regardless of release; it now reports the package version, like the UI.
- Codex wording. The integration code and
codex-snippethelp text no longer describe Codex as using a global~/.codex/config.toml; Pathfinder writes a per-project.codex/config.toml.
Developer documentation
A new dev_documentation/ folder documents each family of scanner detection: imports, symbol calls, API and network, IPC, file/environment/database I/O, and entry points and orphans. It also covers packaging, the graph viewer, the VS Code extension, and a known-issues tracker. LICENSE.txt and USER_GUIDE.md moved to dev_documentation/general/.
Verification
- The full test suite passes: 79 tests, up from 50 at v0.1.2.
- New coverage includes:
- asset-reference parsing and resolution;
- writing and removing instruction-file sections, including preserving existing content and line endings;
- the MCP handshake (instructions within the client's 2,048-character limit, and version negotiation);
- a round-trip proof that compacted results lose nothing;
- all deep-dive views and their bounds;
- detection of current, older and foreign servers on the launch port.
- Checked by hand in a browser:
- 2D and 3D deep dive, including scroll-to-enter, scroll-to-exit, warp, Back, and switching projection mid-dive;
- the working indicator;
- background scans through the MCP server on a 1,000-file project;
- all four
launch.batcases against a real older server.
Upgrade notes
- Restart Pathfinder. Running
launch.batreplaces an older running server automatically. - Start a new AI session. The assistant then picks up the new server instructions and tool descriptions; no re-enable is needed.
- Re-enable integrations if you want the instruction-file section. This writes it to
CLAUDE.md,AGENTS.mdor.github/copilot-instructions.md. Commit that file if your team should share the guidance. - Rescan your projects to record PHP files and asset references.
- Deep-dive cells will look different the first time you open them, because they use the new placement. Hand-placed symbols keep their positions. Reset Layout gives every cell a fresh arrangement.
- For
lib/api.jsand MCP callers of deep dive: modules with more than 60 symbols now return the overview by default. Passview: "full"for the previous behavior.
Known limitations
-
The macOS builds are not signed with an Apple developer certificate. On first launch, run
xattr -dr com.apple.quarantine .in the unzipped folder, pluscodesign --force --sign - pathfinderon Apple Silicon. See the releases README. -
Projects whose module positions were saved in 2D appear flat in the 3D view. Saved modules keep their positions and have no depth yet.
-
In very dense cells, labels can still overlap somewhat more than with the old cell layout: 24 overlapping label pairs across nine sample files, against 19 before.