Add agent context analysis harness

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: yanpgwang

.claude-plugin/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "context-profiler-marketplace",
+  "owner": {
+    "name": "Yanpeng Wang"
+  },
+  "metadata": {
+    "description": "context-profiler skills for analyzing LLM agent traces and context evolution",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "context-profiler",
+      "description": "Analyze agent traces, transcripts, Langfuse exports, OpenTelemetry spans, and raw provider requests with context-profiler.",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/analyze-agent-context"
+      ]
+    }
+  ]
+}

.github/workflows/ci.yml

@@ -1,5 +1,36 @@
 name: CI
 
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Run smoke tests
+        run: uv run --python ${{ matrix.python-version }} --with pytest pytest tests/test_smoke.py -v
+
+      - name: Smoke test CLI help
+        run: uv run --python ${{ matrix.python-version }} context-profiler --help
+name: CI
+
 on:
   push:
     branches: [main]

.plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "context-profiler",
+  "description": "Agent context analysis harness for diagnosing context growth, tool bloat, repeated content, and turn-to-turn trace evolution.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Yanpeng Wang"
+  },
+  "skills": [
+    "./skills/analyze-agent-context"
+  ]
+}

CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.2.0 - Unreleased
+
+### Added
+
+- Agent-friendly CLI harness commands:
+  - `formats list`
+  - `formats describe`
+  - `schema`
+  - `validate`
+  - `normalize`
+  - `diagnose`
+- Cursor and Claude Code transcript JSONL ingestion.
+- Agent-readable diagnosis reports with input scope, confidence, limitations, issue codes, and recommendations.
+- Context diff evidence:
+  - turn-to-turn added/removed/retained token summary
+  - large addition hints
+  - high tool-use addition hints
+  - possible artifact churn hints
+- Tool context hotspot diagnosis:
+  - `TOOL_USE_DOMINATES_CONTEXT`
+  - `TOP_TOOL_CONTEXT_HOTSPOT`
+- Agent Skill distribution:
+  - `skills/analyze-agent-context/SKILL.md`
+  - `.plugin/plugin.json`
+  - `.claude-plugin/marketplace.json`
+- HTML timeline markers for large additions and high tool-use turns.
+
+### Changed
+
+- Default analysis now includes content repeat and field repeat analyzers.
+- README repositioned the project as a trace-source agnostic context analysis harness.
+- Examples focus on raw provider requests, coding-agent transcripts, Langfuse exports, and multi-turn trajectory adapters.

CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Thanks for helping improve `context-profiler`.
+
+## Development Setup
+
+```bash
+git clone https://github.com/Turdot/context-profiler.git
+cd context-profiler
+pip install -e .
+```
+
+For tests, this repository uses `pytest`:
+
+```bash
+PYTHONPATH=src uv run --with pytest pytest tests/test_smoke.py -v
+```
+
+## Project Boundaries
+
+`context-profiler` analyzes traces; it does not fetch or replay them.
+
+Prefer changes that improve one of these surfaces:
+
+- supported input formats
+- validation and schema guidance for agents
+- context/token analyzers
+- machine-readable diagnosis output
+- HTML report clarity
+- Agent Skills / plugin distribution
+
+Avoid adding provider-specific fetch clients unless there is a strong reason. Agents can use existing CLIs, SDKs, or APIs to fetch traces and pass the result to `context-profiler`.
+
+## Adding a Format
+
+When adding a new input format:
+
+1. Add format metadata in `src/context_profiler/formats.py`.
+2. Include `input_kind`, `confidence`, `analysis_scope`, `limitations`, and `agent_conversion_guidance`.
+3. Add parser/normalizer code in `src/context_profiler/adapters/` or an adjacent focused module.
+4. Add a small synthetic fixture under `tests/fixtures/`.
+5. Add smoke tests for `validate`, `normalize`, `diagnose`, and `analyze --html` if applicable.
+
+## Adding an Analyzer
+
+Analyzers should produce evidence, not overconfident claims.
+
+Good analyzer outputs:
+
+- stable issue codes
+- token counts
+- request/message indices
+- tool names
+- artifact keys
+- confidence and limitations when heuristic
+
+Avoid vague warnings without evidence.
+
+## Agent Skill Changes
+
+Canonical public skills live under `skills/`.
+
+Do not put product-distribution skills under `.agents/skills/` or `.claude/skills/`; those paths are for project-local agent behavior.
+
+If you add or rename skills, update:
+
+- `.plugin/plugin.json`
+- `.claude-plugin/marketplace.json`
+- `README.md`
+- tests covering the distribution files