agentprof 0.1.0__tar.gz

agentprof-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 epicodic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentprof-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: agentprof
+Version: 0.1.0
+Summary: Analyse AI coding agent sessions: call trees, timings, tokens, cost and waste.
+Keywords: ai,agents,copilot,claude-code,llm,tokens,cost,observability
+Author: epicodic
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Dist: fastapi>=0.120
+Requires-Dist: uvicorn>=0.38
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/epicodic/agentprof
+Project-URL: Repository, https://github.com/epicodic/agentprof
+Project-URL: Issues, https://github.com/epicodic/agentprof/issues
+Description-Content-Type: text/markdown
+
+# agentprof
+
+[![PyPI](https://img.shields.io/pypi/v/agentprof?cacheSeconds=3600)](https://pypi.org/project/agentprof/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agentprof?cacheSeconds=3600)](https://pypi.org/project/agentprof/)
+[![CI](https://github.com/epicodic/agentprof/actions/workflows/ci.yml/badge.svg)](https://github.com/epicodic/agentprof/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/epicodic/agentprof/blob/main/LICENSE)
+
+**A profiler for AI coding agents: see where your agents spend time, tokens and money.**
+
+agentprof reads the session logs that Claude Code, OpenAI Codex CLI and VS Code Copilot Chat already write on your machine.
+It shows each session as a call tree of turns, subagents and tool calls, with an inline timeline, token counts, context growth, costs and hints about likely waste.
+Everything runs locally, so your sessions never leave your machine.
+
+![A Claude Code session as a call tree with timeline, cost, tokens and context per row](https://media.githubusercontent.com/media/epicodic/agentprof/main/docs/images/session-tree.png)
+
+## Features
+
+- **Call tree with timeline**: every prompt, subagent and tool call becomes a row with its duration, cost, tokens and peak context, next to a timeline bar for when it ran.
+  Nested subagents get their own colour-coded agent numbers, so you can follow a delegation chain at a glance.
+- **Cost and token accounting**: costs and tokens are given both per node and rolled up per subtree, with input, output, cache read and cache write tokens counted separately.
+  Estimated values are marked `≈`, and values the logs do not contain are shown as `–` instead of being guessed.
+- **Context tracking**: see how the context window grows call by call, where it peaks and where it was compacted.
+- **Agent summary**: one row per agent with its model, cache TTL, resumes, duration, own cost, share of the session cost and token breakdown.
+- **Node details**: open any turn or agent to see its timeline, cost per LLM call, context chart, subagents and a searchable list of LLM and tool calls, down to the raw prompt, result and tool arguments.
+- **Waste findings**: hints, not verdicts, about where time and money may have gone (see [Findings](#findings)).
+- **Live updates**: the session list fills in within seconds, and open sessions update while an agent is still working.
+- **JSON API for AI agents**: everything in the UI is also available as compact JSON, so an AI agent can analyse sessions itself, including how the agents and subagents in them worked together.
+
+![Node details with timeline, cost per LLM call, context growth, subagents and LLM calls](https://media.githubusercontent.com/media/epicodic/agentprof/main/docs/images/node-details.png)
+
+## Installation
+
+agentprof is a command-line tool that starts a local web app.
+Install it in its own isolated environment with [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/):
+
+```sh
+uv tool install agentprof
+# or
+pipx install agentprof
+```
+
+Or run it once without installing it:
+
+```sh
+uvx agentprof
+```
+
+agentprof requires Python 3.12 or newer.
+
+## Usage
+
+```sh
+agentprof
+```
+
+This starts a local server on `127.0.0.1:8765` and opens your browser.
+The session list appears immediately and fills in while sessions are summarised in the background; a session is analysed in full when you open it.
+
+```
+agentprof [SESSION] [--host 127.0.0.1] [--port 8765] [--no-browser]
+          [--claude-root DIR] [--codex-root DIR] [--copilot-root DIR]
+          [--pricing FILE]
+```
+
+| Option | Purpose |
+|---|---|
+| `SESSION` | Open a session directly: `<agent>:<id>` (e.g. `claude-code:<id>`), a bare id, or a session file path such as a Copilot chat export. |
+| `--host`, `--port` | Interface and port to bind. |
+| `--no-browser` | Do not open a browser. |
+| `--claude-root`, `--codex-root`, `--copilot-root` | Read sessions from a different directory. |
+| `--pricing` | Replace the bundled price table: per-model token prices and the USD value of a Copilot credit (`usd_per_credit`). |
+
+## Supported agents
+
+| Agent | Sessions read from | Cost |
+|---|---|---|
+| Claude Code | `~/.claude/projects` (or `$CLAUDE_CONFIG_DIR/projects`), including subagent transcripts | USD at API list prices, estimated |
+| OpenAI Codex CLI | `~/.codex/sessions`, including subagent rollouts | USD at API list prices, estimated |
+| VS Code Copilot Chat | `workspaceStorage` of VS Code and VS Code Insiders on Linux, macOS and Windows | Credits as reported by Copilot, converted to USD at $0.01 per credit |
+
+Claude Code and Codex costs are API-equivalent estimates; on a subscription you do not pay per token.
+Costs keep their native unit and are never added across units.
+
+## Findings
+
+agentprof flags likely waste as hints, not verdicts.
+Each finding is attached to the turn or agent it is about, and the session header counts them.
+
+| Finding | What it looks for |
+|---|---|
+| Repeated reads | The same file read several times with overlapping line ranges. |
+| Re-acquired context | A subagent reading files its parent agent had already read. |
+| Retry chains | Sibling agents started with very similar tasks. |
+| Repeated or failing commands | The same command run again and again, or a high tool failure rate. |
+| Polling loops | Long streaks of consecutive polling calls. |
+| Cost outliers | Agents that cost far more than their siblings. |
+| Context bloat | Large uncached prompts and low cache hit ratios. |
+| Cold cache rewrites | Large cache writes with little reuse, for example after the cache expired during a wait for the user. |
+| Idle parents | A parent agent idling after a child agent completed. |
+| Context jumps | Context that grew sharply between two calls. |
+
+## Local API for AI agents
+
+agentprof is useful to people, and just as useful to AI agents.
+While it runs, everything it knows about a session is available as JSON on the same port, so you can point an agent at a session and ask it what went wrong, why a run was expensive or how its subagents worked together.
+
+The API is built for this:
+
+- **Self-describing**: [`/api`](http://127.0.0.1:8765/api/) lists every endpoint with its parameters, and each session page links to its JSON, so a URL from the browser is enough to start with.
+  `/sessions/{id}?format=json` returns the same data as the API route.
+- **Agent by agent**: `/summary` gives one row per agent with its parent agent, so the delegation tree can be rebuilt without the full call tree.
+  Each row has the agent's topic, models, LLM calls, peak context, tokens, cache TTL, resumes, longest gap, its own cost and the cost of everything it delegated.
+- **Findings first**: `/findings` puts the likely waste with the highest estimated cost first.
+- **Bounded downloads**: `depth` and `fields` cut a large call tree down to what fits in a context window; prompts, results and tool arguments are only fetched for the node that needs them.
+- **Honest numbers**: every value says whether it is `exact`, `estimated` or `n/a`, so an agent can tell measurements from guesses.
+
+For example, ask your agent:
+
+```text
+agentprof is running on http://127.0.0.1:8765. Start at /api, open session
+claude-code:<id> and explain which subagents drove the cost, where they
+waited for each other, and what we could do differently next time.
+```
+
+| Endpoint | Returns |
+|---|---|
+| [`/api`](http://127.0.0.1:8765/api/) | Endpoint index with parameters and descriptions |
+| [`/docs`](http://127.0.0.1:8765/docs) | Interactive OpenAPI schema |
+| `/api/sessions` | All sessions, newest first |
+| `/api/sessions/events` | Server-sent events for session list updates |
+| `/api/sessions/{id}` | The full call tree with metrics and findings; `depth` and `fields=session,diagnostics,tree` bound a large download |
+| `/api/sessions/{id}/summary` | One compact row per agent, with its parent, cost and cache breakdowns |
+| `/api/sessions/{id}/findings` | Findings, ordered by estimated avoidable cost, severity and time |
+| `/api/sessions/{id}/nodes/{node_id}` | Prompt, result and raw tool arguments of one node |
+| `/api/sessions/{id}/diagnostics` | Parse counts and redacted details of malformed lines |
+| `/api/pricing` | The effective price table and its model matching rule |
+
+## Development
+
+```sh
+./bootstrap.sh             # install uv, Node (nvm), pnpm and all dependencies
+uv run agentprof           # run against your own sessions
+pnpm --dir frontend dev    # frontend dev server, proxies /api to port 8765
+uv run qa                  # lint, type check and tests for Python and the frontend
+uv run build-dist          # build and smoke-test the distributions
+```
+
+See [`docs/architecture.md`](https://github.com/epicodic/agentprof/blob/main/docs/architecture.md) for how the code fits together, [`AGENTS.md`](https://github.com/epicodic/agentprof/blob/main/AGENTS.md) for conventions and [`docs/releasing.md`](https://github.com/epicodic/agentprof/blob/main/docs/releasing.md) for releases.
+
+## License
+
+[MIT](https://github.com/epicodic/agentprof/blob/main/LICENSE)

agentprof-0.1.0/README.md

@@ -0,0 +1,152 @@
+# agentprof
+
+[![PyPI](https://img.shields.io/pypi/v/agentprof?cacheSeconds=3600)](https://pypi.org/project/agentprof/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agentprof?cacheSeconds=3600)](https://pypi.org/project/agentprof/)
+[![CI](https://github.com/epicodic/agentprof/actions/workflows/ci.yml/badge.svg)](https://github.com/epicodic/agentprof/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/epicodic/agentprof/blob/main/LICENSE)
+
+**A profiler for AI coding agents: see where your agents spend time, tokens and money.**
+
+agentprof reads the session logs that Claude Code, OpenAI Codex CLI and VS Code Copilot Chat already write on your machine.
+It shows each session as a call tree of turns, subagents and tool calls, with an inline timeline, token counts, context growth, costs and hints about likely waste.
+Everything runs locally, so your sessions never leave your machine.
+
+![A Claude Code session as a call tree with timeline, cost, tokens and context per row](https://media.githubusercontent.com/media/epicodic/agentprof/main/docs/images/session-tree.png)
+
+## Features
+
+- **Call tree with timeline**: every prompt, subagent and tool call becomes a row with its duration, cost, tokens and peak context, next to a timeline bar for when it ran.
+  Nested subagents get their own colour-coded agent numbers, so you can follow a delegation chain at a glance.
+- **Cost and token accounting**: costs and tokens are given both per node and rolled up per subtree, with input, output, cache read and cache write tokens counted separately.
+  Estimated values are marked `≈`, and values the logs do not contain are shown as `–` instead of being guessed.
+- **Context tracking**: see how the context window grows call by call, where it peaks and where it was compacted.
+- **Agent summary**: one row per agent with its model, cache TTL, resumes, duration, own cost, share of the session cost and token breakdown.
+- **Node details**: open any turn or agent to see its timeline, cost per LLM call, context chart, subagents and a searchable list of LLM and tool calls, down to the raw prompt, result and tool arguments.
+- **Waste findings**: hints, not verdicts, about where time and money may have gone (see [Findings](#findings)).
+- **Live updates**: the session list fills in within seconds, and open sessions update while an agent is still working.
+- **JSON API for AI agents**: everything in the UI is also available as compact JSON, so an AI agent can analyse sessions itself, including how the agents and subagents in them worked together.
+
+![Node details with timeline, cost per LLM call, context growth, subagents and LLM calls](https://media.githubusercontent.com/media/epicodic/agentprof/main/docs/images/node-details.png)
+
+## Installation
+
+agentprof is a command-line tool that starts a local web app.
+Install it in its own isolated environment with [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/):
+
+```sh
+uv tool install agentprof
+# or
+pipx install agentprof
+```
+
+Or run it once without installing it:
+
+```sh
+uvx agentprof
+```
+
+agentprof requires Python 3.12 or newer.
+
+## Usage
+
+```sh
+agentprof
+```
+
+This starts a local server on `127.0.0.1:8765` and opens your browser.
+The session list appears immediately and fills in while sessions are summarised in the background; a session is analysed in full when you open it.
+
+```
+agentprof [SESSION] [--host 127.0.0.1] [--port 8765] [--no-browser]
+          [--claude-root DIR] [--codex-root DIR] [--copilot-root DIR]
+          [--pricing FILE]
+```
+
+| Option | Purpose |
+|---|---|
+| `SESSION` | Open a session directly: `<agent>:<id>` (e.g. `claude-code:<id>`), a bare id, or a session file path such as a Copilot chat export. |
+| `--host`, `--port` | Interface and port to bind. |
+| `--no-browser` | Do not open a browser. |
+| `--claude-root`, `--codex-root`, `--copilot-root` | Read sessions from a different directory. |
+| `--pricing` | Replace the bundled price table: per-model token prices and the USD value of a Copilot credit (`usd_per_credit`). |
+
+## Supported agents
+
+| Agent | Sessions read from | Cost |
+|---|---|---|
+| Claude Code | `~/.claude/projects` (or `$CLAUDE_CONFIG_DIR/projects`), including subagent transcripts | USD at API list prices, estimated |
+| OpenAI Codex CLI | `~/.codex/sessions`, including subagent rollouts | USD at API list prices, estimated |
+| VS Code Copilot Chat | `workspaceStorage` of VS Code and VS Code Insiders on Linux, macOS and Windows | Credits as reported by Copilot, converted to USD at $0.01 per credit |
+
+Claude Code and Codex costs are API-equivalent estimates; on a subscription you do not pay per token.
+Costs keep their native unit and are never added across units.
+
+## Findings
+
+agentprof flags likely waste as hints, not verdicts.
+Each finding is attached to the turn or agent it is about, and the session header counts them.
+
+| Finding | What it looks for |
+|---|---|
+| Repeated reads | The same file read several times with overlapping line ranges. |
+| Re-acquired context | A subagent reading files its parent agent had already read. |
+| Retry chains | Sibling agents started with very similar tasks. |
+| Repeated or failing commands | The same command run again and again, or a high tool failure rate. |
+| Polling loops | Long streaks of consecutive polling calls. |
+| Cost outliers | Agents that cost far more than their siblings. |
+| Context bloat | Large uncached prompts and low cache hit ratios. |
+| Cold cache rewrites | Large cache writes with little reuse, for example after the cache expired during a wait for the user. |
+| Idle parents | A parent agent idling after a child agent completed. |
+| Context jumps | Context that grew sharply between two calls. |
+
+## Local API for AI agents
+
+agentprof is useful to people, and just as useful to AI agents.
+While it runs, everything it knows about a session is available as JSON on the same port, so you can point an agent at a session and ask it what went wrong, why a run was expensive or how its subagents worked together.
+
+The API is built for this:
+
+- **Self-describing**: [`/api`](http://127.0.0.1:8765/api/) lists every endpoint with its parameters, and each session page links to its JSON, so a URL from the browser is enough to start with.
+  `/sessions/{id}?format=json` returns the same data as the API route.
+- **Agent by agent**: `/summary` gives one row per agent with its parent agent, so the delegation tree can be rebuilt without the full call tree.
+  Each row has the agent's topic, models, LLM calls, peak context, tokens, cache TTL, resumes, longest gap, its own cost and the cost of everything it delegated.
+- **Findings first**: `/findings` puts the likely waste with the highest estimated cost first.
+- **Bounded downloads**: `depth` and `fields` cut a large call tree down to what fits in a context window; prompts, results and tool arguments are only fetched for the node that needs them.
+- **Honest numbers**: every value says whether it is `exact`, `estimated` or `n/a`, so an agent can tell measurements from guesses.
+
+For example, ask your agent:
+
+```text
+agentprof is running on http://127.0.0.1:8765. Start at /api, open session
+claude-code:<id> and explain which subagents drove the cost, where they
+waited for each other, and what we could do differently next time.
+```
+
+| Endpoint | Returns |
+|---|---|
+| [`/api`](http://127.0.0.1:8765/api/) | Endpoint index with parameters and descriptions |
+| [`/docs`](http://127.0.0.1:8765/docs) | Interactive OpenAPI schema |
+| `/api/sessions` | All sessions, newest first |
+| `/api/sessions/events` | Server-sent events for session list updates |
+| `/api/sessions/{id}` | The full call tree with metrics and findings; `depth` and `fields=session,diagnostics,tree` bound a large download |
+| `/api/sessions/{id}/summary` | One compact row per agent, with its parent, cost and cache breakdowns |
+| `/api/sessions/{id}/findings` | Findings, ordered by estimated avoidable cost, severity and time |
+| `/api/sessions/{id}/nodes/{node_id}` | Prompt, result and raw tool arguments of one node |
+| `/api/sessions/{id}/diagnostics` | Parse counts and redacted details of malformed lines |
+| `/api/pricing` | The effective price table and its model matching rule |
+
+## Development
+
+```sh
+./bootstrap.sh             # install uv, Node (nvm), pnpm and all dependencies
+uv run agentprof           # run against your own sessions
+pnpm --dir frontend dev    # frontend dev server, proxies /api to port 8765
+uv run qa                  # lint, type check and tests for Python and the frontend
+uv run build-dist          # build and smoke-test the distributions
+```
+
+See [`docs/architecture.md`](https://github.com/epicodic/agentprof/blob/main/docs/architecture.md) for how the code fits together, [`AGENTS.md`](https://github.com/epicodic/agentprof/blob/main/AGENTS.md) for conventions and [`docs/releasing.md`](https://github.com/epicodic/agentprof/blob/main/docs/releasing.md) for releases.
+
+## License
+
+[MIT](https://github.com/epicodic/agentprof/blob/main/LICENSE)

agentprof-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[project]
+name = "agentprof"
+version = "0.1.0"
+description = "Analyse AI coding agent sessions: call trees, timings, tokens, cost and waste."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = [
+    "ai",
+    "agents",
+    "copilot",
+    "claude-code",
+    "llm",
+    "tokens",
+    "cost",
+    "observability",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "fastapi>=0.120",
+    "uvicorn>=0.38",
+]
+
+[[project.authors]]
+name = "epicodic"
+
+[project.scripts]
+agentprof = "agentprof.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/epicodic/agentprof"
+Repository = "https://github.com/epicodic/agentprof"
+Issues = "https://github.com/epicodic/agentprof/issues"
+
+[project.entry-points."agentprof.adapters"]
+claude-code = "agentprof.adapters.claude_code.adapter:ClaudeCodeAdapter"
+codex = "agentprof.adapters.codex.adapter:CodexAdapter"
+copilot-vscode = "agentprof.adapters.copilot_vscode.adapter:CopilotVscodeAdapter"
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "agentprof-qa",
+    "httpx2>=2.13",
+    "pytest>=8.3",
+    "ruff>=0.16.8",
+    "ty>=0.0.83",
+]
+
+[tool.uv.workspace]
+members = ["tools/qa"]
+
+[tool.uv.sources.agentprof-qa]
+workspace = true
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+src = [
+    "src",
+    "tests",
+    "tools/qa/src",
+]
+extend-exclude = [
+    "docs",
+    ".agents",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["--import-mode=importlib"]

agentprof-0.1.0/pyproject.toml.orig

@@ -0,0 +1,67 @@
+[project]
+name = "agentprof"
+version = "0.1.0"
+description = "Analyse AI coding agent sessions: call trees, timings, tokens, cost and waste."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "epicodic" }]
+keywords = ["ai", "agents", "copilot", "claude-code", "llm", "tokens", "cost", "observability"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = ["fastapi>=0.120", "uvicorn>=0.38"]
+
+[project.scripts]
+agentprof = "agentprof.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/epicodic/agentprof"
+Repository = "https://github.com/epicodic/agentprof"
+Issues = "https://github.com/epicodic/agentprof/issues"
+
+[project.entry-points."agentprof.adapters"]
+claude-code = "agentprof.adapters.claude_code.adapter:ClaudeCodeAdapter"
+codex = "agentprof.adapters.codex.adapter:CodexAdapter"
+copilot-vscode = "agentprof.adapters.copilot_vscode.adapter:CopilotVscodeAdapter"
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "agentprof-qa",
+    "httpx2>=2.13",
+    "pytest>=8.3",
+    "ruff>=0.16.8",
+    "ty>=0.0.83",
+]
+
+[tool.uv.workspace]
+members = ["tools/qa"]
+
+[tool.uv.sources]
+agentprof-qa = { workspace = true }
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+src = ["src", "tests", "tools/qa/src"]
+extend-exclude = ["docs", ".agents"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["--import-mode=importlib"]

agentprof-0.1.0/src/agentprof/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""agentprof: analyse AI coding agent sessions."""
+
+from importlib.metadata import version
+
+__version__ = version("agentprof")

agentprof-0.1.0/src/agentprof/adapters/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""Agent adapters: turn agent-specific session files into the neutral model."""
+
+from importlib.metadata import entry_points
+
+from agentprof.adapters.base import AdapterConfig, AgentAdapter
+
+ENTRY_POINT_GROUP = "agentprof.adapters"
+
+
+def load_adapters(config: AdapterConfig) -> list[AgentAdapter]:
+    """Instantiate every adapter registered under the `agentprof.adapters` entry point group."""
+    registered = sorted(entry_points(group=ENTRY_POINT_GROUP), key=lambda entry_point: entry_point.name)
+    return [entry_point.load()(config) for entry_point in registered]

agentprof-0.1.0/src/agentprof/adapters/base.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""The adapter protocol and the lightweight types the registry works with."""
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from agentprof.model import CostMetric, Session
+
+
+def latest_mtime(paths: Iterable[Path]) -> float:
+    """The newest modification time among `paths`; paths that vanished meanwhile are ignored."""
+    times: list[float] = []
+    for path in paths:
+        try:
+            times.append(path.stat().st_mtime)
+        except OSError:
+            continue
+    return max(times, default=0.0)
+
+
+@dataclass(frozen=True)
+class AdapterConfig:
+    """User configuration shared by all adapters.
+
+    `roots` maps an adapter name to an overriding data root; `pricing_file` replaces the bundled price table.
+    """
+
+    roots: dict[str, Path] = field(default_factory=dict)
+    pricing_file: Path | None = None
+
+
+@dataclass(frozen=True)
+class SessionRef:
+    """A cheap handle to one session file."""
+
+    agent: str
+    native_id: str
+    path: Path
+    mtime: float
+
+    @property
+    def id(self) -> str:
+        return f"{self.agent}:{self.native_id}"
+
+
+@dataclass
+class SessionSummary:
+    """One row of the session list: only what an adapter can read without building the tree."""
+
+    id: str
+    agent: str
+    title: str
+    workspace: str | None
+    start_ms: float | None
+    end_ms: float | None
+    file_size: int
+    last_activity_ms: float | None = None
+    cost_total: CostMetric = field(default_factory=CostMetric.not_available)
+
+
+class AgentAdapter(Protocol):
+    """Turns one agent's session files into the neutral model.
+
+    Implementations are constructed with an `AdapterConfig` and registered under the entry point group
+    `agentprof.adapters`. `summarize` and `analyze` raise on sessions they cannot read.
+    """
+
+    name: str
+
+    def discover(self) -> Iterable[SessionRef]: ...
+
+    def open_path(self, path: Path) -> SessionRef | None: ...
+
+    def summarize(self, ref: SessionRef) -> SessionSummary: ...
+
+    def analyze(self, ref: SessionRef) -> Session: ...

agentprof-0.1.0/src/agentprof/adapters/claude_code/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""Claude Code adapter."""