_                    _   ___           _       _     _
    / \   __ _  ___ _ __ | |_|_ _|_ __  ___(_) __ _| |__ | |_
   / _ \ / _` |/ _ \ '_ \| __|| || '_ \/ __| |/ _` | '_ \| __|
  / ___ \ (_| |  __/ | | | |_ | || | | \__ \ | (_| | | | | |_
 /_/   \_\__, |\___|_| |_|\__|___|_| |_|___/_|\__, |_| |_|\__|
         |___/                                 |___/
          Local-first observability for OpenAI Codex usage

Sessions · rollouts · token usage · costs · search · repositories · models · skills

Get started · Features · Architecture · Configuration · Contributing · Runbook

---

AgentInsight turns local Codex session data into a private analytics workspace. It discovers sessions, parses rollout events, estimates cost from token usage, indexes prompts and responses for search, and surfaces dashboard, repository, model, and skills analytics without uploading your provider files.

Project status

AgentInsight is in active alpha development. It is intended for local-only usage, private experimentation, and iterative validation against real Codex usage data. APIs, database tables, and analytics views may still change before a stable release.

What it does

• Session discovery - reads local Codex state and session files from configured provider paths.
• Rollout parsing - streams sessions/**/*.jsonl events without loading large files fully into memory.
• Cost estimation - calculates usage from rollout token events with configurable pricing.
• Search - indexes prompts, responses, repositories, and models with results linked back to sessions.
• Dashboard analytics - summarizes sessions, costs, tokens, cache behavior, and activity over time.
• Repository analytics - groups usage and behavior by local project.
• Model analytics - compares model usage, cost, and token patterns.
• Skills analytics - surfaces usage patterns for coding-agent skills and workflows.
• Task and prompt insights - includes token waste analysis, task context recommendations, and prompt optimization.
• Local-first operation - reads provider data as source material and stores the AgentInsight index locally.

Preview

How it works

Local Codex home
  state_*.sqlite
  sessions/**/*.jsonl
        |
        v
AgentInsight API
  provider adapters -> rollout parser -> local SQLite index -> analytics services
        |
        +--> AgentInsight UI
        |     dashboard -> sessions -> search -> repositories -> costs -> models -> skills -> insights
        |
        +--> AgentInsight MCP
              read-only local context tools for MCP-compatible coding clients

AgentInsight treats Codex data as read-only input. Provider-owned files such as history.jsonl, sessions/, and state_*.sqlite are never modified. Application-owned data is written only to the configured AgentInsight data path.

Get started

The fastest way to run the full stack is Docker Compose:

docker compose up --build -d

Then open:

Service	URL
UI	http://localhost:5173
API	http://localhost:8081
Health check	http://localhost:8081/api/health
MCP health check	http://localhost:8081/api/mcp/health

Stop the stack with:

docker compose down

For native development, troubleshooting, and AI-assisted implementation workflows, see the AgentInsight runbook.

Configuration

Runtime configuration lives in a root .env file. It is intentionally ignored by Git.

AGENTINSIGHT_CODEX_HOME=/path/to/.codex
AGENTINSIGHT_DATA_PATH=/path/to/.agentinsight
AGENTINSIGHT_DB_PATH=/path/to/.agentinsight/agentinsight.db
AGENTINSIGHT_API_PORT=8081
AGENTINSIGHT_UI_PORT=5173
SERVER_PORT=8081

For Docker Compose, AGENTINSIGHT_CODEX_HOME is mounted read-only at /codex and AgentInsight data is stored in the agentinsight-data volume.

Native development

Backend:

cd agentinsight-api
set -a
. ../.env
set +a
./gradlew bootRun

Frontend:

cd agentinsight-ui
npm install
npm run dev

MCP CLI:

cd agentinsight-mcp
go run ./cmd/agentinsight-mcp version
go run ./cmd/agentinsight-mcp tools
go run ./cmd/agentinsight-mcp doctor --api-url http://localhost:8081

MCP client setup, including Claude Desktop stdio configuration, is documented in agentinsight-mcp/docs/client-config.md.

Validation commands:

npm run build
npm run test
cd agentinsight-mcp && go test ./...

Project layout

agentinsight-api/  Spring Boot API, parsing, persistence, analytics services
agentinsight-ui/   React/Vite analytics UI
agentinsight-mcp/  Go MCP adapter for local AgentInsight context
docs/              Local runbooks and operational notes
assets/images/     README screenshots
.github/           Issue, pull request, and release templates

Development model

AgentInsight uses requirement-driven development. New behavior should start from a documented requirement or issue, and pull requests should explain the requirements implemented, acceptance criteria satisfied, and tests added. See CONTRIBUTING.md for the workflow.

Key modules

Area	Description
Dashboard	Session, cost, token, cache, and activity summaries
Sessions	Session explorer and rollout transcript replay
Search	Prompt, response, repository, and model search linked to sessions
Costs	Configurable cost estimation from token events
Repositories	Usage and activity by local project
Models	Token, cache, and cost patterns by model
Skills	Analytics for coding-agent skill usage
Token Waste Advisor	Evidence-backed waste reports and prompt-only analysis
Task Context Analyzer	Repository-scoped context recommendations for new tasks
Prompt Optimization	Focused prompt generation, review, comparison, and local save workflows
MCP Adapter	Read-only local AgentInsight context exposed to MCP-compatible clients

Cost accuracy

Cost calculations originate from rollout token events. The preferred source is token_count, including input tokens, cached input tokens, and output tokens. Pricing is configurable in:

agentinsight-api/src/main/resources/pricing.yml

Pricing must not be hardcoded into business logic.

Documentation

Topic	Link
Runbook	docs/RUNBOOK.md
Contributing	CONTRIBUTING.md
Changelog	CHANGELOG.md
Security	SECURITY.md
License	LICENSE
Root agent instructions	AGENTS.md
API agent instructions	agentinsight-api/AGENTS.md
UI agent instructions	agentinsight-ui/AGENTS.md
MCP README	agentinsight-mcp/README.md
MCP agent instructions	agentinsight-mcp/AGENTS.md
MCP architecture	agentinsight-mcp/docs/architecture.md
MCP client config	agentinsight-mcp/docs/client-config.md
MCP tools	agentinsight-mcp/docs/tools.md
MCP privacy	agentinsight-mcp/docs/privacy.md
Docker Compose	docker-compose.yml

Releases

Releases are created from version tags by the GitHub Actions release workflow. The first public release is v0.1.0; release notes are tracked in CHANGELOG.md.

Privacy model

AgentInsight is designed for local analysis of local coding-agent data:

• Provider files are read-only.
• Imports continue past corrupt files and unknown events.
• Metrics are reproducible from imported source data.
• No random sampling or hidden calculations are used for analytics.
• Search and analytics results remain traceable to sessions.