Skip to content

Pathfinder v0.1.3

Choose a tag to compare

@skuttlebot skuttlebot released this 06 Oct 01:51
· 5 commits to main since this release
Immutable release. Only release title and notes can be modified.
9b976de

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.bat reuses 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_scan no 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_status reports the scan's state (running, done or failed) 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_MS environment 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:

  • require and include connect files, including the common __DIR__ . '/path' and dirname(__FILE__) . '/path' forms.
  • use statements connect to the file named after the class, following the usual PSR-4 convention. Group use statements 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 limit didn'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-snippet help 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.bat cases against a real older server.

Upgrade notes

  • Restart Pathfinder. Running launch.bat replaces 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.md or .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.js and MCP callers of deep dive: modules with more than 60 symbols now return the overview by default. Pass view: "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, plus codesign --force --sign - pathfinder on 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.