npm package: @philippwassibauer/agentlens
Description: Observability for AI coding agents — tracks sessions, tool calls, file changes, and provides analytics
Latest version: 0.1.1

# agentlens

observability for ai coding agent harnesses — [pi](https://github.com/nicholasgasior/pi-coding-agent), aider, claude code, cline, cursor.

tracks agent sessions (tool calls, prompts, file changes, errors, git activity, PR lifecycle) and provides team analytics. local-first: next.js + sqlite, no external services.

```mermaid
graph TB
    subgraph Harnesses["coding agent harnesses"]
        PI["pi<br/><i>extension api</i>"]
        AIDER["aider<br/><i>planned</i>"]
        CLAUDE["claude code<br/><i>planned</i>"]
        CLINE["cline<br/><i>planned</i>"]
    end

    subgraph Server["agentlens server"]
        API["next.js api routes<br/>localhost:3333"]
        DB[("sqlite<br/>data/agentlens.db")]
        SCORE["scoring engine"]
        GH["github client"]
    end

    subgraph Dashboard["dashboard ui"]
        TEAM["team dashboard"]
        LIST["session list"]
        REPLAY["session replay"]
    end

    PI -->|"POST /api/events"| API
    AIDER -.->|"POST /api/events"| API
    CLAUDE -.->|"POST /api/events"| API
    CLINE -.->|"POST /api/events"| API

    API --> DB
    DB --> SCORE
    SCORE --> API
    API --> GH
    GH -->|"poll pr status"| GHAPI["github api"]

    API --> TEAM
    API --> LIST
    API --> REPLAY
```

## quickstart

```bash
# clone and install
git clone https://github.com/philippWassibauer/agentlens.git
cd agentlens
pnpm install

# start the server
pnpm dev
# → http://localhost:3333

# install the pi plugin (symlink)
mkdir -p .pi/extensions
ln -sf ../../plugin .pi/extensions/agentlens

# or install globally
ln -sf $(pwd)/plugin ~/.pi/agent/extensions/agentlens
```

that's it. start a pi session and events flow automatically.

## what it captures

the pi plugin hooks into agent lifecycle events and sends them to the local server. zero overhead — all POSTs are fire-and-forget.

| event           | what's captured                                            |
| --------------- | ---------------------------------------------------------- |
| `session_start` | user, project, git repo/branch, pi version                 |
| `user_prompt`   | redacted prompt text, length                               |
| `tool_call`     | tool name, args summary, result summary, duration, success |
| `file_change`   | path, action (create/edit)                                 |
| `error`         | error message, which tool failed, recoverable flag         |
| `heartbeat`     | ping every 30s (detects crashed sessions)                  |
| `session_end`   | git status, test detection                                 |
| `pr_snapshot`   | open PRs on the branch at session end                      |

all secrets are redacted locally before any data leaves the machine.

→ [plugin details](docs/plugin.md)

## scoring

each session gets a composite score from 0 to 1: `outcome × efficiency`.

**outcome** — did the code work?

| signal                 | score |
| ---------------------- | ----- |
| tests pass + committed | 1.0   |
| committed, no tests    | 0.7   |
| uncommitted changes    | 0.4   |
| tests failed           | 0.1   |
| crashed / abandoned    | 0.0   |

**efficiency** — how many prompts? (fewer = better)

| prompts | multiplier |
| ------- | ---------- |
| ≤ 10    | 1.0        |
| 11–15   | 0.9        |
| 16–20   | 0.75       |
| > 20    | 0.5        |

→ [full scoring details](docs/scoring.md)

## dashboard

| page           | route           | what it shows                                        |
| -------------- | --------------- | ---------------------------------------------------- |
| team dashboard | `/`             | metrics, charts, failure patterns, skill performance |
| session list   | `/sessions`     | filterable, paginated session table                  |
| session replay | `/sessions/:id` | full timeline with diffs, test output, scoring       |

→ [dashboard guide](docs/dashboard.md)

## development

```bash
pnpm dev          # start dev server on :3333
pnpm test         # run all tests (157 passing)
pnpm test:watch   # watch mode
pnpm build        # production build
```

| variable             | default                 | description                       |
| -------------------- | ----------------------- | --------------------------------- |
| `AGENTLENS_ENDPOINT` | `http://localhost:3333` | where the plugin sends events     |
| `GITHUB_TOKEN`       | (from `gh auth token`)  | github api access for pr tracking |

→ [development guide](docs/development.md)

## documentation

| doc                                  | description                                                  |
| ------------------------------------ | ------------------------------------------------------------ |
| [architecture](docs/architecture.md) | system design, data flow, database schema, project structure |
| [plugin](docs/plugin.md)             | pi plugin events, redaction, installation, configuration     |
| [api reference](docs/api.md)         | all endpoints with request/response examples                 |
| [scoring](docs/scoring.md)           | outcome × efficiency scoring engine                          |
| [evaluation](docs/evaluation.md)     | llm-based qualitative eval checks, insights extraction       |
| [team sync](docs/team-sync.md)       | push insights to shared server, insight server api           |
| [pr tracking](docs/pr-tracking.md)   | github pr lifecycle monitoring                               |
| [dashboard](docs/dashboard.md)       | ui pages, design system, components                          |
| [development](docs/development.md)   | setup, testing, tech stack, project structure                |
| [roadmap](docs/roadmap.md)           | vision, multi-harness plans, intelligence features           |

## license

MIT