Skip to content

project-brief.md

Latest commit

 

History

History
100 lines (76 loc) · 3.04 KB

project-brief.md

File metadata and controls

100 lines (76 loc) · 3.04 KB
Raw

AgentMeter Project Brief

One-line Description

AgentMeter is an open-source, cross-platform local dashboard for measuring coding agent session usage from local JSONL session files.

Problem

Existing LLM observability tools are strong when they are placed in front of API traffic or instrumented inside an application. They are less suitable when the goal is to inspect local coding-agent sessions that already happened.

AgentMeter focuses on that gap:

  • no proxy;
  • no cloud service;
  • no provider-side integration;
  • no required code instrumentation;
  • just local session files, parsed and displayed clearly.

Initial Scope

The current version supports:

  • Codex local sessions;
  • Claude Code local sessions;
  • CodeBuddy local sessions;
  • WorkBuddy local sessions;
  • generic JSONL session directories;
  • multiple configured source roots for users running several coding agents;
  • token usage from local session data;
  • session duration from local JSONL timestamps;
  • tool-call statistics from local session events;
  • SQLite indexing;
  • local browser UI;
  • synchronized terminal UI MVP.

Interface Direction

AgentMeter should support two local interfaces over one shared application core:

  • Web UI for the current dashboard-oriented experience.
  • TUI for terminal-first workflows, SSH sessions, and users who prefer staying inside a shell.

The two interfaces should share the same database, indexing pipeline, pricing rules, query semantics, and user-visible definitions for tokens, cost, duration, status, filters, and session identity.

Non-goals For MVP

  • Proxy or gateway mode.
  • Cloud sync.
  • Team dashboards.
  • Authentication.
  • Remote database.
  • Automatic uploads or telemetry.
  • Complex eval workflows.
  • Divergent Web-only and TUI-only business logic for the same usage concepts.

User

The first user is a developer who uses local coding agents and wants to understand:

  • token burn;
  • estimated cost;
  • session history;
  • active time versus wall time;
  • model usage;
  • tool-call behavior;
  • project-level usage.

Product Principles

  • Read-only against source session data.
  • Prefer actual usage data over estimation.
  • Clearly label unknown, missing, and estimated values.
  • Keep data local unless the user explicitly exports it.
  • Store normalized data so UI queries do not repeatedly rescan raw JSONL.
  • Make raw source traceability possible for debugging.
  • Design for fast local diagnosis with clear hierarchy and consistent UI patterns rather than a marketing-page feel; use docs/ui-design.md as the practical Web UI guide.

First Usable Version

The first useful Web build should let a user open AgentMeter, point it at one or more local agent data directories if needed, index sessions, and inspect:

  • overview totals;
  • daily usage;
  • session list;
  • session detail timeline;
  • model usage;
  • tool-call counts and durations.

The first useful TUI build exposes the same core data in a terminal: Overview totals, session list, session detail, tool aggregates, settings, index trigger, and clear parse/pricing status labels.