Plexus

See where your coding agent is in your project, live.

Plexus is a small floating panel for macOS. It draws your project as a branching map and grows a new branch every time Claude Code, OpenAI Codex, or Grok Build reads, searches, or edits a file.

_{A real Claude Code session on this repo, replayed with the panel's ▶ Replay button (Fast speed).}

Agents can touch dozens of files a minute, and a scrolling log of tool calls doesn't show you where in the codebase that work is happening. Plexus draws the trail instead:

• Branches are the folders and files the agent has visited this session, drawn out from the project root.
• The glowing head is the agent itself. It walks to each new spot as the agent works, and the camera keeps the whole trail in view.
• The status pill reads Exploring while the agent is working and Idle when it's waiting on you.

The panel never takes focus, so you keep typing to your agent while it updates.

---

Live, next to your agent

_{The native macOS panel following Claude Code live, sped up 2×.}

Part	What it does
Title bar	The session's name. Hover over the panel to show the window buttons, Sessions (⌘P, to switch between live Claude Code, Codex, and Grok sessions), and Settings.
Exploring / Idle	Whether the agent is working right now.
▶ Replay	Replays the session's trail from the start, as in the GIF at the top.
⌖ Center	Fits the whole trail back into view.
Nodes	Click any folder or file to copy its path.

Press Esc to collapse the panel into a small floating orb, and click the orb to bring it back.

Three ways to draw the trail

The same session, from the Trail setting:

Neurons (default)	Tree	Circle

How it works

flowchart LR
    subgraph agents["Your agents"]
        CC["Claude Code"]
        CX["OpenAI Codex"]
        GK["Grok Build"]
    end

    subgraph disk["Local files"]
        T1["~/.claude/projects"]
        T2["~/.codex/sessions"]
        T3["~/.grok/active_sessions.json<br/>+ updates.jsonl"]
    end

    CC -- "PreToolUse hook" --> HOOK["plexus --hook"]
    CX -- "PreToolUse hook" --> HOOK
    GK -- "PreToolUse hook" --> HOOK
    CC -. transcript .-> T1
    CX -. transcript .-> T2
    GK -. session log .-> T3

    HOOK -- "POST /hook" --> BE
    T1 --> BE
    T2 --> BE
    T3 --> BE

    BE["Go backend<br/>127.0.0.1:7733<br/><i>tool call → file → folder</i>"]
    BE -- "live updates (SSE)" --> UI["Map (TypeScript)<br/>in a WKWebView"]
    UI --> PANEL["Floating macOS panel<br/>(Swift, never takes focus)"]

Loading

1. Hooks report each step as it happens. On first launch, Plexus adds a PreToolUse hook to Claude Code, Codex, and Grok. Before every tool call, the agent runs plexus --hook, which forwards the call to the local backend. Claude Code and Codex also get UserPromptSubmit and Stop hooks, which switch the status between Exploring and Idle.
2. Transcripts fill in what came before. The backend also reads recent local transcripts, so a session that was already halfway through its work still shows every folder it has touched.
3. Tool calls become folders. The backend pulls file paths out of each call (Read, Edit, Write, Grep, Glob, apply_patch, list and search commands, and so on), works out which folder each file is in, and adds that folder to the session's trail.
4. The map redraws live. The trail streams to the web view, which grows the branches and walks the agent's head to the newest spot.

What counts as a step

The agent…	Shows up on the map?
reads, edits, or writes a file	✅ The file and its folders join the trail
lists a directory or globs for files	✅ That directory joins the trail
greps or searches inside a path	✅ That path joins the trail
runs a shell command that names a path	✅ That path joins the trail
runs a shell command with no path (npm test, git status)	➖ Ignored
touches files outside the project root	➖ Ignored

When the panel appears

Plexus only shows up while you're working with an agent:

• You switch to an agent (Grok Build or Orca, Claude Code, Codex, or the terminal running one of them, such as Terminal, iTerm, or Ghostty): the panel appears.
• You switch to anything else (Mail, Safari…): it tucks itself away.
• You press Esc: it collapses to the orb until you click it.

When an agent session starts, its SessionStart hook runs plexus --ensure, which launches Plexus in the background, still hidden, so it's ready before the agent makes its first tool call.

Install

Requirements: macOS 13+, Go 1.23+, and a Swift toolchain (Xcode or the Command Line Tools).

git clone https://github.com/ryusudol/plexus.git
cd plexus
make dmg
open macos/dist/Plexus.dmg

Drag Plexus onto Applications and launch it. Plexus runs as a menu bar item with no Dock icon, and it installs the agent hooks the first time it starts.

Note

The build is not signed or notarized, so macOS Gatekeeper may block the first launch. If it does, right-click Plexus.app and choose Open.

Command	Output
make dmg	macos/dist/Plexus.app plus macos/dist/Plexus.dmg, ready to share
make app	Only macos/dist/Plexus.app

Run from source

go run ./cmd/plexus package-hud   # build the panel app
go run ./cmd/plexus               # start the backend + panel

Or run make app and then make start.

No agent running? Choose Menu bar → Walk Demo to watch Plexus walk a made-up project.

Controls

Action	How
Show the panel	Menu bar → Show Window
Collapse to the orb	Esc
Browse sessions	⌘P
Copy a folder's path	Click its node
Show or hide from the shell	go run ./cmd/plexus toggle
Quit the panel and backend	go run ./cmd/plexus quit, or Menu bar → Quit Plexus
Try it without an agent	Menu bar → Walk Demo

Settings

Hover over the panel and click the gear in its title bar.

Setting	Options
Color	The trail's accent color: pink (default), red, orange, yellow, green, blue, purple, or white
Trail	Neurons (organic, the default) · Tree (branching downward) · Circle (radial)
Glass	How opaque the panel is (40–100%)
Speed	How fast the agent's head walks: Slow · Medium · Fast
Follow	Focus stays on one session until another session gets a prompt · Project stays on the selected project
Theme	Dark · Light · System

Project layout

cmd/plexus/      CLI entry point: backend, hook client, app/DMG packaging
internal/        Go backend
  server/          HTTP API and live stream on 127.0.0.1:7733
  sessions/        tracks live sessions and which one is focused
  extract/         turns tool calls into file and folder visits
  claude/ codex/   transcript readers for each agent
  orca/ acp/       Grok Build / Orca session sources
  hooks/           installs the agent hooks
lib/             shared TypeScript: layout (neurons / tree / circle), demo tree
public/          the map UI that runs inside the panel's web view
macos/           Swift app: floating panel, orb, menu bar item
tests/           TypeScript tests (Go tests live next to their packages)

Run npm test for the Go and TypeScript tests, or make test for Go only.

Notes

• macOS only, for now. The map is web code, but Plexus is meant to be the floating panel next to your agent rather than a browser tab.
• Local only. Everything runs on your Mac. The backend listens only on 127.0.0.1, and Plexus doesn't send anything off your machine.