Why hooklens

Coding agents run commands, edit files, and call tools faster than you can read the transcript. hooklens records what happened through the agents' own hooks, so you can answer questions like:

• Which files did the agent change, and which did it only read?
• What shell commands ran, and which ones failed?
• Which MCP servers and tools did it use?
• Where did the time go, and how many tokens did the session cost?

It is a single Python package with no dependencies. Data stays in a local SQLite file, and the UI is a local web page. Nothing leaves your machine.

Features

• Timeline of every tool call, with duration and status. Long idle gaps are compressed.
• Graph of the session: tools, programs, files, MCP servers, and how often each was used.
• Event log with the input and a response excerpt of every call.
• Summary of files changed, files read, commands, and MCP servers.
• Tokens and model from the agent's transcript.
• Live view that updates while the agent works.
• One view for three agents. Claude Code, Codex, and Cursor events are normalized to one schema.

Supported agents

Quick start

uv tool install hooklens        # or: pipx install hooklens
hooklens install                # add hooks to every agent it finds

Start a new agent session (hooks load when a session starts), use the agent, then run:

hooklens show                   # opens http://127.0.0.1:7878

To install one agent at a time, use hooklens claude install, hooklens codex install, or hooklens cursor install.

Usage

Commands that delete data ask first. Add --dry-run to see what would be removed, or --yes to skip the question.

How it works

agent ──hook event (JSON)──> hooklens hook ──> SQLite (raw events)
                                                   │
                         hooklens show ──> normalize ──> sessions, events, files ──> local UI

1. Capture. The agent runs hooklens <agent> hook on each event. The hook stores the raw event and exits in about 30 ms. It never blocks or changes what the agent does.
2. Normalize. When you open the UI, hooklens maps each agent's events to one schema, pairs tool starts with their results, and reads token usage from the agent's transcript.
3. View. A small server on 127.0.0.1 serves the UI and a JSON API.

hooklens only uses hooks that report what happened. It never subscribes to hooks that can allow or block an action. Read design/architecture.md for the details and design/sequence.md for the full call flow.

Privacy and safety

• All data is in ~/.hooklens/hooklens.db. Nothing is sent over the network.
• Each string is trimmed to 4096 characters before it is stored, so full file contents and long outputs are not kept. Set HOOKLENS_MAX_FIELD to change the limit (0 keeps everything).
• Cursor sends your account email with each event. hooklens removes it before storage.
• hooklens backs up an agent config file before it changes it, and only ever edits its own entries.
• hooklens uninstall --purge removes everything hooklens created, and nothing else.

Configuration

Roadmap

See the milestones: the first PyPI release, importing past sessions, cost estimates, OpenTelemetry and SIEM export, and policy hooks for security tools.

Contributing

Contributions are welcome. Read CONTRIBUTING.md to get started.

make setup     # create .venv with the dev dependencies (needs uv)
make check     # lint, format check, and tests: the same checks as CI

License

Apache License 2.0. Copyright 2026 Kunal.