introspy 0.1.0__tar.gz

introspy-0.1.0/.claude/hooks/session-start.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+set -euo pipefail
+
+# Only run in remote (Claude Code on the web) environments
+if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
+  exit 0
+fi
+
+# Install dependencies
+cd "$CLAUDE_PROJECT_DIR"
+uv sync --quiet
+
+# Install pre-commit hooks
+bash scripts/install-hooks.sh

introspy-0.1.0/.claude/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "introspect": {
+      "type": "http",
+      "url": "http://127.0.0.1:8000/mcp"
+    }
+  }
+}

introspy-0.1.0/.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

introspy-0.1.0/.claude/skills/nolegend/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: nolegend
+description: >
+  Tufte-style Plotly charts in introspect's FastAPI/Jinja stack. Use this
+  whenever you add or modify a chart — bar, line, scatter, sparkline, or
+  any go.Figure-driven visualization. Trigger on words like "clean",
+  "minimal", "professional", "boardroom-ready", or whenever a new
+  visualization is being built or an existing one is unclear. Charts in
+  this repo are built server-side with go.Figure + nolegend.activate()
+  and bootstrapped client-side via Plotly.newPlot in base.html — there is
+  no Plotly Express or marimo here.
+---
+
+# nolegend — Plotly visualization rules for introspect
+
+*Remove the legend to become one.*
+
+Every chart should tell a story, not decorate the page. Apply Tufte's
+principles, then refine with the helpers from the `nolegend` package.
+
+## Where charts live in this project
+
+- Server side: `go.Figure` built in a handler (e.g.
+  `cost_breakdown.py:_build_figure`, `sessions.py:_render_multi_chart`),
+  serialised via `fig.to_json()`, embedded into a `<script
+  type="application/json">` tag.
+- Client side: `base.html`'s `initCostChart` JS finds elements with
+  `class="cost-chart"`, parses the JSON, and runs `Plotly.newPlot`. Click
+  / select handlers are added via `el.on('plotly_click', ...)` →
+  `htmx.ajax(...)` for HTMX fragment swaps.
+- Template: `nolegend.activate()` is called lazily on first render
+  (`_ensure_template()` pattern — keeps imports side-effect-free).
+- Plotly Express is **not** used. Build figures directly with
+  `go.Figure` and `add_trace`. Keep Plotly Express advice from upstream
+  nolegend out of this project.
+
+## Core principles
+
+1. **Maximize data-ink ratio.** Every pixel encodes data. Remove
+   gridlines, borders, backgrounds, decorations. The `tufte` template
+   does most of this — don't undo it with overrides.
+2. **No chartjunk.** No 3D, no gradient fills, no drop shadows, no
+   coloured backgrounds.
+3. **Direct-label over legends.** This is the load-bearing rule. With a
+   view toggle that flips trace visibility, set
+   `showlegend=False` on the layout and put the label on the line itself
+   (see "Direct labels on toggled views" below).
+4. **Titles convey insight, not description.** When the chart has its
+   own caption (most do here, via the surrounding `<h2>`), keep the
+   in-figure title empty so the plot area isn't pushed down.
+5. **Range frames.** Axes span the data range, not arbitrary round
+   numbers. The `tufte` template does this for line/scatter; bars
+   default to starting at 0.
+6. **Restrained colour.** ≤ 5 colours per chart. Gray (`#b0b0b0`) is
+   for context. Keep the most expensive / most important series in the
+   highest-contrast slot (e.g. `_INVOCATION_COLOR_PALETTE` puts red at
+   index 0 so the runaway subagent stands out).
+
+## Direct labels on toggled views
+
+The session detail Cost tab is the canonical example: one figure with
+multiple Scatter traces, view toggle (`Total / Agent / Category /
+Invocations`) flips visibility via `Plotly.restyle`. Without a legend
+the user can't tell which line is which — so we direct-label every
+line trace at its endpoint.
+
+Pattern (from `_render_multi_chart`):
+
+```python
+text_labels = [""] * len(ys)
+if ys:
+    text_labels[-1] = f" {name}"  # leading space avoids hugging the line
+
+fig.add_trace(go.Scatter(
+    x=x_axis,
+    y=ys,
+    mode="lines+text",
+    name=name,
+    line={"color": color, "width": 1.5},
+    text=text_labels,
+    textposition="middle right",
+    textfont={"color": color, "size": 11},
+    cliponaxis=False,
+    customdata=...,
+    hovertemplate=...,
+))
+```
+
+Plus, on the layout:
+
+```python
+fig.update_layout(
+    showlegend=False,
+    margin={"l": 60, "r": 110, "t": 20, "b": 60},  # right margin holds labels
+)
+```
+
+Why per-trace `text` rather than `add_annotation`:
+
+- Annotations are figure-wide and **don't toggle** with trace visibility.
+  When the user flips from "Total" to "By agent", annotation labels for
+  hidden traces would still float in space.
+- Per-trace `text` is part of the trace, so visibility toggling
+  (`Plotly.restyle({visible: ...})`) hides the labels too, automatically.
+- One label per trace at the last point (rest empty) is enough — the
+  reader sees the colour + name pair at the line endpoint.
+
+For stacked bar charts (cost-overview daily/hourly), use
+`add_annotation` instead — bars don't have an "endpoint" to attach text
+to, so place the label at the peak segment of each top-N group. See
+`cost_breakdown.py:_compute_top_group_annotations` for the pattern.
+
+## Hover, click, select interactivity
+
+Charts in this repo are interactive surfaces, not static images. Keep
+this in mind:
+
+- `customdata` is your friend. Put per-point identifiers
+  (uuid, day, session_id) in `customdata` so the click handler can fire
+  the right HTMX request. Example: session cost chart's bucket points
+  carry `[first_uuid, last_uuid, msg_count]`.
+- `hovertemplate` should reference customdata — it gives the user the
+  context they need before they decide to click.
+- `dragmode='select'` for any chart that supports box-filtering. Force
+  it via `Plotly.relayout` after `newPlot` in case the modebar resets it.
+- Line-only traces don't reliably populate `evt.points` on box-select.
+  Read `evt.range.x` and look up customdata from `el.data[trace_idx]`.
+- Markers always-visible: when a chart has a "marker overlay" trace
+  (spike/slope highlights), keep it visible across all view toggles by
+  flagging its trace index in the JS `viewMap` logic.
+
+## Colour rules (hard constraints)
+
+- Never use more than 5 colours in a single chart (excluding the
+  marker overlay).
+- Never use rainbow / jet colorscales — not perceptually uniform.
+- Never use red and green together without another differentiator.
+- Use `_MAIN_AGENT_COLOR` for "main / total" series so the same colour
+  consistently means the same thing across the app's charts.
+- For sequential data, `nolegend.SEQUENTIAL` or `viridis`.
+- When in doubt: fewer colours. One colour + gray usually suffices.
+
+## Pinned colour map for re-rendered panels
+
+When two panels show overlapping groups (e.g. daily totals and hourly
+drill-down by project), build a single canonical colour map from the
+all-time aggregate and pass it to both renderers. This way "project
+foo" is the same colour in every panel. See
+`cost_breakdown.py:_canonical_color_map` for the pattern.
+
+## Chart type selection
+
+Match the chart to the question, not the other way around.
+
+| Question type | Chart |
+|---|---|
+| How did it change over time? | Line |
+| How do groups compare? | Horizontal bar |
+| What's the relationship? | Scatter |
+| What's the distribution? | Histogram or box |
+| What's the composition? | Stacked bar |
+| What's the trend per group? | Small multiples (faceted bars/lines) |
+| What's the quick trend? | Sparkline |
+
+**Never use:** pie charts, donut charts, 3D charts, radar/spider charts,
+gauge charts.
+
+## Typography and titles
+
+- **In-card heading carries the title.** The surrounding `<h2>` in the
+  Jinja template is the chart's title — keep `fig.update_layout(title=...)`
+  empty so the plot area sits at the top of its card.
+- **Axis labels: only when non-obvious.** "Day" on a daily-bucket
+  x-axis is fine. "USD" on a cost y-axis is useful. Skip generic
+  "Value" / "Count".
+- **Font: serif (Georgia).** The `tufte` template handles this. The
+  base.html stylesheet pins `#js-plotly-tester` to Georgia too —
+  don't remove that rule, it prevents axis-title displacement after
+  HTMX swaps.
+
+## Anti-patterns to catch and fix
+
+| Anti-pattern | Fix |
+|---|---|
+| Legend box with 2+ entries on a toggled chart | Direct labels via per-trace `text` |
+| Gridlines visible | `showgrid=False` (template handles it) |
+| Default Plotly blue everywhere | Use the project palette constants |
+| Title says "Chart of X by Y" | Rewrite the surrounding `<h2>` as the insight |
+| Pie chart | Replace with horizontal bar |
+| Too many colours (>5) | Aggregate, fold into "Other", or use spotlight |
+| Y-axis starts at 0 when data starts at 800 | Trust the tufte template's range frame |
+| Annotations on a toggled-trace chart | Use per-trace `text` instead |
+| `fig.update_layout(title=...)` set | Drop it — the `<h2>` is the title |
+| HTMX swap rebuilds chart from scratch and loses selection state | Use `Plotly.restyle` for visibility flips |
+
+## Checklist before merging a chart change
+
+- [ ] `nolegend.activate()` called (lazy `_ensure_template()` pattern)
+- [ ] No legend box (direct labels or single series)
+- [ ] No gridlines, no in-figure title
+- [ ] ≤ 5 colours, palette pinned across panels if shared
+- [ ] Axes have units where non-obvious
+- [ ] Right margin ≥ 80–110px when direct-labeling
+- [ ] `customdata` carries enough info for click/select handlers
+- [ ] `cliponaxis=False` on text-bearing traces so end labels render
+- [ ] Test added in `tests/routes/` asserting the figure JSON
+  shape (e.g. trace name, customdata presence, no `<polyline>`)

introspy-0.1.0/.claude/skills/python-review/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: python-review
+context: fork
+description: Deep Python code quality review. Auto-invoke when finishing a task, before marking work complete, when the user asks to review code, or when preparing a PR. Focuses on design judgment, naming, performance, and test quality — things that ruff and ty cannot catch.
+---
+
+# Deep Code Review
+
+Review the changes for design quality — what automated tools miss. Report findings as 🔴 Must Fix, 🟡 Should Fix, 🟢 Suggestion.
+
+First, confirm `uv run poe check` passes (ruff, ty, tests). Fix those before proceeding.
+
+---
+
+## 1. Function Design
+
+Prefer pure functions: data in, data out, no side effects. When side effects are necessary (I/O, logging, state mutation), isolate them — push them to the edges, keep the core logic pure and testable.
+
+- Functions that both compute and mutate → split into a pure computation and a thin side-effecting wrapper.
+- Over ~30 lines → smell. Justify or split.
+- Mixed abstraction levels (HTTP parsing interleaved with business logic).
+- \>5 parameters → group into a dataclass or split.
+- Boolean params make call sites unreadable (`process(data, True, False)`) → enum or separate functions.
+- `@staticmethod` on a single-method class, or classes with only `__init__` + one method → just a function.
+- Inheritance for code reuse where composition is simpler.
+
+## 2. Naming
+
+- Single-letter variables outside comprehensions/lambdas. `d`, `x`, `r` — name the thing.
+- Generic names that mean nothing: `data`, `result`, `info`, `item`, `obj`, `tmp`, `val`, `manager`, `handler`, `processor`, `helper`, `utils`. Name the *what*.
+- Misleading: `users` that's a count, `get_` that mutates, `status` that's a bool.
+- Inconsistent: `user_id` / `userId` / `uid` across functions.
+- Unnecessary abbreviation. `cfg` is fine. `proc_dat_xfrm` is not.
+- Negated booleans (`not_found`, `is_not_valid`) → invert the name.
+
+## 3. Comments
+
+Comments exist for *why*, never *what*.
+
+- Restating code (`# increment counter` above `counter += 1`) → delete.
+- Commented-out code → it's in git, delete.
+- TODOs without a ticket reference → link to tracker or delete.
+- *Missing* why-comments on magic numbers, workarounds, performance hacks, non-obvious decisions.
+- Docstrings that parrot the signature (`"""Gets the user."""` on `get_user()`) → explain behavior/constraints/edge cases or remove.
+- Excessive inline comments on straightforward code → the code is too clever, simplify it.
+
+## 4. Error Handling Design
+
+Strategy, not syntax (ruff handles syntax).
+
+- `try` blocks wrapping 20 lines → wrap only what can throw.
+- `except Exception as e: raise Exception(str(e))` → destroys traceback/type. `raise` or wrap in domain exception.
+- `raise OtherError("failed")` discarding original → chain with `from e`.
+- Error types that are `str` or bare `Exception` → domain-specific exceptions.
+- `assert` for runtime validation in non-test code → stripped by `-O`, use `if`/`raise`.
+- String-based error discrimination (`if "not found" in str(e)`) → exception types.
+- Inconsistent strategy within a module: some functions return `None`, others raise. Pick one.
+
+## 5. Performance
+
+Patterns that cause real problems, not micro-optimization.
+
+- `in` on a `list` that should be a `set` (>~20 elements: O(n) vs O(1)).
+- `+` string concatenation in a loop → `"".join()`.
+- `await` in a loop → `asyncio.gather()` / `TaskGroup`.
+- N+1: querying a DB or API per item instead of batching.
+- `f.read()` on large files when line-by-line streaming works.
+- Repeated computation inside a loop → hoist or `@cache`.
+- Building a list only to immediately iterate it → use the iterator.
+- Unnecessary `.copy()` / `deepcopy` → restructure ownership.
+
+## 6. Test Quality
+
+- No assertions — calling code without checking results is not a test.
+- Weak assertions: `assert result is not None` without checking actual value.
+- Mocking 5 things → testing setup, not behavior. Restructure for testability.
+- 3+ tests differing only in input/output → `@pytest.mark.parametrize`.
+- Missing edge cases: empty input, error paths, boundary conditions.
+- Useless names: `test_process_data` → `test_returns_error_on_empty_input`.
+- 20 lines of setup for 2 lines of test → extract fixtures.
+
+## 7. Duplicated Logic
+
+- Functions/blocks doing the same thing with minor variations → extract with concrete params.
+- Watch for: HTTP handling, validation, serialization boilerplate, similar conditional chains.
+- Copy-paste with slight modifications — the second copy will drift into a bug.
+
+## 8. Module Design
+
+- God modules (>500 lines, mixed responsibilities) → suggest split.
+- In-function imports for lazy loading must have a `# lazy:` comment. Uncommented → why?
+- Side effects at import time (starting servers, DB connections, thread spawning at module level) → 🔴. Import must be inert.
+- Public names (`no _` prefix) that aren't intended API.
+- CLI entrypoints containing logic instead of parsing args and delegating.
+
+## 9. Dependencies
+
+- Mixed HTTP clients (`requests` + `httpx`) → pick one.
+- Mixed serialization (`json` + `orjson`/`msgspec`) → use what's in the dep tree.
+- Vendored code that should be a dep, or trivial deps that could be a 10-line util.
+
+---
+
+## Output
+
+Group by severity, then area. Each finding: **what** + **where** (file:line) + **why** + **concrete fix**.
+
+End with: X must-fix, Y should-fix, Z suggestions.
+
+$ARGUMENTS

introspy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+
+  format:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - run: uv run ruff format --check .
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - run: uv run ty check
+
+  vulns:
+    name: Dependency Vulnerabilities
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - run: uvx pysentry-rs .
+        continue-on-error: true
+
+  dead-code:
+    name: Dead Code Detection
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - run: uv run vulture src
+
+  unused-deps:
+    name: Unused Dependencies
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - run: uv run deptry .
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - run: uv run pytest -q --tb=short

introspy-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/introspy
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

introspy-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+cf/
+di/
+venv/
+.env
+*.so
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

introspy-0.1.0/CLAUDE.md

@@ -0,0 +1,50 @@
+# Introspect
+
+Explore Claude Code conversation logs via CLI, web UI, MCP server.
+
+## Architecture
+
+- `db.py` — DuckDB schema over `~/.claude/projects/**/*.jsonl`; materialized at server startup, lazy views as fallback
+- `refresh.py` — background rebuild loop + window picker (`1`/`7`/`30`/`month`)
+- `pricing.py` — model pricing as Python rates + DuckDB `CASE` SQL
+- `sql_fragments.py` — shared SQL building blocks (cost / tool / file / command rollups)
+- `projects.py` — git worktree-aware `cwd` → canonical project
+- `search.py` — FTS via BM25, ILIKE fallback
+- `api/routes.py` → `api/handlers/<name>.py` → `templates/<name>.html`
+- `api/handlers/_helpers.py` — shared: `parent(request)`, `conn(request)`, pagination, sort allowlists; re-exports SQL fragments
+- `mcp/` — FastMCP tools mounted on FastAPI; `refresh_bridge.py` plumbs `app.state` to stateless tool fns
+- `cli.py` — Typer commands
+
+## Key Patterns
+
+- **Adding a page**: handler in `handlers/`, route in `routes.py`, template, tests in `tests/routes/`
+- **DB access**: `request.state.conn` (read-only, per-request), `json_extract()` for JSON fields, `# noqa: S608` for dynamic SQL
+- **Pagination**: 1-based, fetch `size+1` to detect next page
+- **HTMX**: `parent(request)` selects `base.html` (full) vs `partial.html` (fragment)
+- **Charts**: build `plotly.graph_objects.Figure` server-side, style with `nolegend.activate()`, embed JSON for `Plotly.newPlot` (see `/python-review` skill `nolegend`)
+- **Cost SQL**: reuse `SESSION_COST_SUBQUERY` / `session_cost_subquery_filtered()` from `sql_fragments.py` — never hand-roll cost math in handlers
+- **Materialization**: `materialize_views()` runs on web startup and rebuilds derived tables (incl. `session_stats`, `assistant_message_costs`, `session_messages_enriched`); CLI commands call `ensure_materialized()` so they share the on-disk DB
+- **Views/tables** (`db.py`): `raw_data`, `raw_messages`, `project_map`, `logical_sessions`, `assistant_message_costs`, `tool_calls`, `session_messages_enriched`, `conversation_turns`, `session_titles`, `message_commands`, `file_reads`, `file_writes`, `session_stats`, `search_corpus`, `materialize_meta`
+
+## Test Fixtures (`conftest.py`)
+
+`make_user_message()`, `make_assistant_message()`, `write_jsonl()`, `glob_pattern()`. Route tests use `_patched_client()` context manager (defined in `tests/routes/conftest.py`).
+
+## Commands
+
+- `uv run introspect query "SELECT ..."` — ad-hoc SQL against the views (use this to study real data; `introspect views` lists them)
+- `uv run poe check` — run lint, typecheck, vulns, then tests
+- `uv run poe fix` — auto-format and fix lint issues
+- `uv run poe test` — run tests only
+- `uv run poe check-all` — run all checks including dead-code and unused-deps
+
+## Stack
+
+uv, ruff (lint/format), ty (type check), pytest, poethepoet (task runner)
+
+## Notes
+
+- ty is in beta — may produce false positives. Prefer `# ty: ignore[rule]` over blanket suppression.
+- Pre-commit hook auto-fixes and restages files. Only blocks on unfixable issues.
+- All user-facing features must have tests. When adding new routes, template variables, query parameters, or UI functionality, add corresponding tests in `tests/routes/`.
+- **IMPORTANT**: After completing any task, you MUST run the `/python-review` skill to review all changes. Apply all 🔴 Must Fix and 🟡 Should Fix findings before marking work as complete.

introspy-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: introspy
+Version: 0.1.0
+Summary: Explore and search Claude Code conversation logs
+Requires-Python: >=3.11
+Requires-Dist: duckdb>=1.2.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: nolegend>=0.1.2
+Requires-Dist: plotly>=5.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.15.0
+Requires-Dist: uvicorn>=0.34.0

introspy-0.1.0/README.md

@@ -0,0 +1,97 @@
+# Introspect
+
+Explore and search your Claude Code conversation logs using SQL, full-text search, a web UI, or an MCP server.
+
+## Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
+
+## Installation
+
+```bash
+uv sync
+```
+
+Activate the project's virtual environment before running the `introspect`
+commands below (or prefix each one with `uv run`):
+
+```bash
+source .venv/bin/activate
+```
+
+## Usage
+
+### Web UI
+
+```bash
+introspect serve
+# Runs on http://127.0.0.1:8000 by default
+introspect serve --port 3000 --host 0.0.0.0
+```
+
+### CLI
+
+```bash
+# List recent sessions
+introspect sessions
+
+# Show summary statistics
+introspect stats
+
+# Search conversation logs
+introspect search "some query"
+
+# Show tool call history
+introspect tools
+introspect tools --failed
+introspect tools --name Bash
+
+# Run an ad-hoc SQL query
+introspect query "SELECT * FROM logical_sessions LIMIT 5"
+
+# Rebuild the search index
+introspect refresh
+```
+
+### MCP Server
+
+```bash
+introspect mcp
+```
+
+This starts an MCP server over stdio for integration with Claude Code.
+
+Alternatively, the web server exposes the same MCP tools over HTTP at
+`http://127.0.0.1:8000/mcp`. To launch a Claude Code session wired up to it:
+
+```bash
+# In one terminal
+introspect serve
+
+# In another
+uv run poe claude
+```
+
+The `claude` poe task runs `claude --mcp-config .claude/mcp.json`, so the MCP
+server is only registered for that session — no changes to your global Claude
+Code config.
+
+## Development
+
+```bash
+# Install dependencies (including dev tools)
+uv sync
+
+# Auto-format and fix lint issues
+uv run poe fix
+
+# Run lint, typecheck, security scan, and tests
+uv run poe check
+
+# Run tests only
+uv run poe test
+
+# Run all checks including dead-code and unused-deps
+uv run poe check-all
+```