Faro is a VS Code extension for turning agent reasoning about a codebase into guided, navigable code beacons.
- Author a path in chat with an agent.
- Inspect the path in the Faro sidebar.
- Reveal the matching code directly in the editor.
[Placeholder: Faro Home screenshot][Placeholder: Faro Path screenshot][Placeholder: Faro Setup screenshot]
[Placeholder: short onboarding video or GIF]
Faro is currently a local MVP.
It is not published to the VS Code Marketplace yet, so the current way to try it is:
- install the repo locally
- install the extension into your VS Code
- add the local agent artifacts for this workspace
- use Faro from VS Code Chat and the Faro sidebar
- Node.js 23.x or newer
- npm
- VS Code 1.109 or newer
Install dependencies:
npm installInstall the extension locally into your VS Code:
make install-localInstall the local Faro agent artifacts for this workspace:
make upsert-agent-local SCOPE=localOpen the repository in VS Code:
code .If needed, run Developer: Reload Window once so VS Code picks up the local extension and generated agent files.
- Open the Chat view in VS Code.
- Select the
Faro Path Authorcustom agent. - Make sure the local
FaroMCP server is enabled for the workspace. - Ask for a path around a concrete code-reading goal.
Example:
Create a Faro path that explains how the main VS Code view is built and wired.
- Open the
Faroactivity bar item. - Use the main Faro view:
Hometo enter the productPathto read the active pathSetupto manage local/global agent integrations
- Use
Prev,Next, andRevealto walk the path in code.
- the
Faroactivity bar item is visible - the main Faro view opens correctly
Home,Path, andSetupare available- the active path is visible in
Path Prev,Next, andRevealwork
If you want to test Faro in an Extension Development Host instead of installing it into your normal VS Code profile:
make dev-hostExpected local MVP behavior:
- the
Faroactivity bar item is visible - the main Faro view opens correctly
Pathshows an empty state until an agent-authored path existsPrev,Next, andRevealwork from the path routeSetupshows local/global integration targets
Workspace-local artifacts:
make upsert-agent-local SCOPE=localThis writes:
CLAUDE.md.github/copilot-instructions.md.github/agents/faro-path-author.agent.md.codex/skills/faro-author-paths/SKILL.md
Global artifacts:
make upsert-agent-global SCOPE=globalIf a Faro-owned global Copilot file already exists and differs, Faro refuses to overwrite it unless you opt in:
make upsert-agent-global SCOPE=global FORCE=1Example prompts:
Create a Faro path that explains how the main VS Code view is built and wired.
Create a Faro path that traces the authentication flow from entrypoint to session state.
Onboard me to the setup flow in this extension as a Faro path.
Faro is also a Claude Code plugin. /explain asks Claude for a tour of your changes or of existing code, and you walk it in a pane beside the chat: a hypothesis up top, five to seven steps in reading order, and for each step what it does, why, the lines to look at, and the code itself. The explanation follows program-comprehension research; the rules and the bibliography are in skills/faro-author-paths/comprehension.md.
Install it from a Claude Code terminal session:
/plugin install faro --marketplace pmarchini/faro
Answer y to add the marketplace, then pick a scope.
From a clone of this repository, one command does the same from your shell:
make install-claude-codeIt adds this checkout as the faro marketplace and installs the plugin from it, so the plugin loads in place and a git pull updates it (restart Claude Code or run /reload-plugins after). It is safe to run again. make install-claude-code MARKETPLACE=pmarchini/faro installs from GitHub instead, PLUGIN_SCOPE=project or local changes the scope (default user), and make uninstall-claude-code removes both. To try a checkout for one session only, start Claude Code with claude --plugin-dir /path/to/faro.
Use it:
/explain your uncommitted changes
/explain HEAD~3..HEAD a commit range
/explain feature/login a branch against its merge base
/explain #482 --goal "why do we retry?" a pull request (needs gh)
/explain src/billing/ --lens domain existing code
/explain "how does this plugin work?" a question about a flow
/explain last reopen the last tour
Flags: --depth brief|standard|deep, --lens flow|domain, --reader new|familiar, --goal "...".
In the pane, a column beside the chat: a rail on the left holds the Faro mark, the steps (titles wrap) and the tour's files as a folder tree with the current step's file marked; the reader on the right shows the step's story (its headline wraps under its number, beside the plan as a chip) and its code, which fills the rest of the height. The code is centred on the current beacon, beacon lines are tinted and listed under the code (● for the current one), f folds the lines far from every beacon into "N lines folded", and a track on the right marks where the beacons are. Keys: j/k move along the path, e/u show more or less, l switches between the flow and domain lens, b jumps to the next beacon, n/p scroll the code, f folds or unfolds, o shows the whole file, c folds or opens the code panel, h hides or shows the rail, a puts the step's suggested question in the prompt, x asks Claude to re-explain the step more simply, r refreshes a step whose code changed, q closes. In a narrow pane the steps and files stack above the reader; in a pane shorter than 18 rows, such as VS Code's integrated terminal, they give way to a one-line breadcrumb (faro 3/6 ✓✓▸○○○) and t shows the steps. Resuming a session (claude --resume, --continue, or switching to it from the session picker) brings back its tour, where you were in it, and the pane if it was open. /tour pin [name] keeps a tour across sessions; /tour list, /tour open <id> and /tour drop <id> manage them.
Tours are paths of paths. Any step can lead deeper: press d on it, or click a line of its code and then d, and Claude writes a short sub path that hangs from that step while you keep reading; the pane moves you into it when it lands. Steps the author thinks are worth a dive are marked ◆ with the question a dive would answer. Inside a sub path j/k move along it and step back out at either end, s surfaces one level, and the header reads as a breadcrumb (Session persistence › 2 › How a token is signed 1/2). The rail shows the paths as a tree, and m shows a map of every path. With a line picked, a asks about that line and n/p move the pick; click it again to let it go. Written sub paths are saved with the tour. Design and decisions: Claude Code tour plugin.
Core commands:
npm run check
npm test
npm run test:claude-code # the Claude Code plugin's hooks, through `claude plugin test`
make dev-hostIf Faro does not appear in VS Code:
- reinstall the extension with
make install-local - reload the VS Code window
- confirm the extension is enabled
If the custom agent does not appear in Chat:
- rerun
make upsert-agent-local SCOPE=local - reload the VS Code window
- check that
.github/agents/faro-path-author.agent.mdexists
If the MCP flow does not work:
- confirm the local
FaroMCP server is enabled for the workspace - verify the extension is active
- verify
npm run checkandnpm test