agentlens

observability for ai coding agent harnesses — pi, 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.

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

# 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

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

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

development

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

documentation

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

license

MIT