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

  1. Entry Point – hooks/register.tsx is executed when the mod loads.
  2. register.tsx imports feed.ts and map.ts.
  3. feed.ts subscribes to the engine’s event emitter.
  4. Each event is transformed into a map action (e.g., TOOL_CALL, MODEL_STEP) and passed to map.ts.
  5. map.ts emits a React state update; draw.ts renders the updated stations.
  6. For narrow terminals, register.tsx also loads terminal.tsx, which consumes the same map state and renders a text‑only view.
  7. braille.ts listens to map state changes and outputs braille characters via the terminal.

WHAT THIS CODE TOUCHES OUTSIDE ITSELF

  • CLI – claude commands for installing/updating the plugin.
  • Filesystem – reads .claude‑plugin manifest files, writes no data elsewhere.
  • Network – none; all data is local and read‑only from the event stream.

WHAT EACH FILE IS RESPONSIBLE FOR

FileResponsibility
.claude‑plugin/plugin.jsonDeclares the mod and its hook directory.
.claude‑plugin/marketplace.jsonRegisters the mod in the marketplace.
hooks/register.tsxHook registration and entry point.
hooks/feed.tsNormalises event streams for the map.
hooks/map.tsHolds map state, defines stations.
hooks/draw.tsSVG rendering of stations.
hooks/terminal.tsxTerminal‑only rendering.
hooks/braille.tsBraille output.
Test filesEnsure 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.yml runs a linting and test pipeline on every push.
  • Licensing – LICENSE is 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.