The Problem
When a Claude Code session runs, the user sees a flat list of tool calls, model steps, and hook invocations. Tracking where each action occurs—memory, files, shell, network, agents, skills—becomes tedious, and debugging race conditions is difficult. A visual, real‑time map would let developers see the flow of work and spot bottlenecks instantly.
What This Does
The lot‑map mod injects a live panel beside the chat. As Claude Code emits events, the panel lights up the corresponding station: Model, Memory, Files, Shell, Network, Browser, Agents, Skills, and Hooks. The map supports textual, pictorial, and braille output, enabling use in terminals and screen readers. All logic lives in the hooks/ directory; each hook is a small React component that listens to a specific event stream and updates the UI.
Key modules:
hooks/register.tsx– registers the mod with Claude Code and wires all hooks.hooks/map.ts– maintains the map state and draws stations.hooks/feed.ts– receives raw events from the engine and normalises them for the map.hooks/draw.ts– renders SVG shapes for stations.hooks/terminal.tsx– renders a terminal‑style pane for narrow terminals.hooks/braille.ts– renders braille‑dot characters for accessibility.
The plugin manifest (.claude‑plugin/plugin.json) tells Claude Code to load the hooks/ directory, keeping all logic local and preventing any outbound traffic.
How It Is Wired
INTERNAL CALL GRAPH
- Entry Point –
hooks/register.tsxis executed when the mod loads. register.tsximportsfeed.tsandmap.ts.feed.tssubscribes to the engine’s event emitter.- Each event is transformed into a map action (e.g.,
TOOL_CALL,MODEL_STEP) and passed tomap.ts. map.tsemits a React state update;draw.tsrenders the updated stations.- For narrow terminals,
register.tsxalso loadsterminal.tsx, which consumes the same map state and renders a text‑only view. braille.tslistens to map state changes and outputs braille characters via the terminal.
WHAT THIS CODE TOUCHES OUTSIDE ITSELF
- CLI –
claudecommands for installing/updating the plugin. - Filesystem – reads
.claude‑pluginmanifest files, writes no data elsewhere. - Network – none; all data is local and read‑only from the event stream.
WHAT EACH FILE IS RESPONSIBLE FOR
| File | Responsibility |
|---|---|
.claude‑plugin/plugin.json | Declares the mod and its hook directory. |
.claude‑plugin/marketplace.json | Registers the mod in the marketplace. |
hooks/register.tsx | Hook registration and entry point. |
hooks/feed.ts | Normalises event streams for the map. |
hooks/map.ts | Holds map state, defines stations. |
hooks/draw.ts | SVG rendering of stations. |
hooks/terminal.tsx | Terminal‑only rendering. |
hooks/braille.ts | Braille output. |
| Test files | Ensure each hook behaves as expected. |
The module graph is acyclic; the only hub is register.tsx, which has a small, well‑defined API. Changing a visual style affects only draw.ts and the corresponding CSS in hooks/. Adding a new station requires only a new entry in map.ts and a normalised event in feed.ts.
How To Use It
Setup The mod installs through Claude Code’s plugin system; no local build is required.
claude plugin install lot-map --marketplace alexeyw/lot-map
If the marketplace is missing:
claude plugin marketplace add alexeyw/lot-map
claude plugin install lot-map@lot-map
Configuration No environment variables are needed. The plugin’s privacy policy (see PRIVACY.md) guarantees no data leaves the machine.
Running It Open a new Claude Code session. The map pane appears automatically. If the terminal width is <144 columns, type /lot-map to switch to the text view.
Testing Locally The repo contains four test files under hooks/. Run them with the test runner specified in .github/workflows/check.yml (likely Jest). No additional scripts are required.
Real‑World Use
During a debugging session, a developer can see at a glance which files are being edited, which shell commands are executed, and when the network is accessed. For example, after a git push, the Network station lights up, and the map shows the Shell station that ran git. This immediate visual feedback speeds up triage of intermittent failures and clarifies the relationship between high‑level prompts and low‑level actions.
Code Health & Issues
- Tests – four test files (
braille.test.tsx,lot-map.test.tsx,principles.test.tsx,terminal.test.tsx) cover core hook functionality. - CI –
.github/workflows/check.ymlruns a linting and test pipeline on every push. - Licensing –
LICENSEis present. - Missing Build – No
package.json, so no explicit dependency graph or build script is available. The mod relies on Claude Code’s runtime to resolve imports, which may limit offline development.
The Bottom Line
lot‑map delivers a clear, local visual of Claude Code’s internal activity without any network traffic. It is easy to install, requires no configuration, and is well‑tested. The code is modular and readable, making future extensions straightforward. Ideal for developers who need instant insight into tool calls and model steps during interactive sessions.