Skip to content

Commit 934e380

Browse files
yanpgwangcursoragent
yanpgwang
and
cursoragent
committed
Add open source project guidance
Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent cf936bf commit 934e380

7 files changed

Lines changed: 215 additions & 34 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
name: Bug report
3+
about: Report a reproducible problem with context-profiler
4+
title: "[Bug]: "
5+
labels: bug
6+
---
7+
8+
## What happened?
9+
10+
11+
## Command
12+
13+
```bash
14+
context-profiler ...
15+
```
16+
17+
## Expected behavior
18+
19+
20+
## Actual behavior
21+
22+
23+
## Environment
24+
25+
- context-profiler version:
26+
- Python version:
27+
- OS:
28+
29+
## Input format
30+
31+
- [ ] OpenAI / Anthropic request
32+
- [ ] Langfuse trace
33+
- [ ] Cursor transcript
34+
- [ ] Claude Code transcript
35+
- [ ] Other:
36+
37+
## Safe reproduction data
38+
39+
Do not attach private traces, credentials, customer data, or production prompts. Use a minimal synthetic or redacted fixture.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
name: Feature request
3+
about: Suggest a new analyzer, workflow, or report feature
4+
title: "[Feature]: "
5+
labels: enhancement
6+
---
7+
8+
## Problem
9+
10+
11+
## Proposed solution
12+
13+
14+
## Example trace shape
15+
16+
Describe the structure without sharing private data.
17+
18+
## Why this belongs in context-profiler
19+
20+
`context-profiler` analyzes traces. It should not fetch traces, replay agent loops, or execute third-party tools.

‎.github/ISSUE_TEMPLATE/format_adapter.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
name: Format adapter request
3+
about: Request support for a trace, transcript, or trajectory format
4+
title: "[Format]: "
5+
labels: format-adapter
6+
---
7+
8+
## Format name
9+
10+
11+
## Source
12+
13+
Examples: LangSmith run export, OpenTelemetry/OpenInference spans, SWE-agent trajectory, academic dataset.
14+
15+
## Shape
16+
17+
List the important fields. Do not paste private traces.
18+
19+
```json
20+
{
21+
"example": "redacted or synthetic"
22+
}
23+
```
24+
25+
## Analysis value
26+
27+
What context behavior should this enable us to analyze?
28+
29+
- [ ] turn-to-turn growth
30+
- [ ] tool input/output bloat
31+
- [ ] repeated content
32+
- [ ] artifact churn
33+
- [ ] stale/superseded context evidence
34+
- [ ] other:

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
## Summary
2+
3+
-
4+
5+
## Test Plan
6+
7+
- [ ] `PYTHONPATH=src uv run --with pytest pytest tests/test_smoke.py -v`
8+
- [ ] `PYTHONPATH=src uv run context-profiler --help`
9+
10+
## Trace Data Safety
11+
12+
- [ ] This PR does not commit private traces, credentials, customer data, or production prompts.
13+
- [ ] New fixtures are synthetic or clearly redacted.
14+
15+
## Format / Analyzer Checklist
16+
17+
If this PR adds a format:
18+
19+
- [ ] Format metadata was added to `src/context_profiler/formats.py`.
20+
- [ ] Validation and/or normalization behavior is covered by tests.
21+
- [ ] A synthetic fixture was added under `tests/fixtures/`.
22+
23+
If this PR adds an analyzer:
24+
25+
- [ ] Findings include stable issue codes and concrete evidence.
26+
- [ ] Heuristic findings use hint language and confidence.

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ jobs:
1515
- "3.10"
1616
- "3.11"
1717
- "3.12"
18+
- "3.13"
1819

1920
steps:
2021
- uses: actions/checkout@v4
@@ -29,37 +30,3 @@ jobs:
2930

3031
- name: Smoke test CLI help
3132
run: uv run --python ${{ matrix.python-version }} context-profiler --help
32-
name: CI
33-
34-
on:
35-
push:
36-
branches: [main]
37-
pull_request:
38-
branches: [main]
39-
40-
jobs:
41-
test:
42-
runs-on: ubuntu-latest
43-
strategy:
44-
matrix:
45-
python-version: ["3.10", "3.11", "3.12", "3.13"]
46-
47-
steps:
48-
- uses: actions/checkout@v4
49-
50-
- name: Set up Python ${{ matrix.python-version }}
51-
uses: actions/setup-python@v5
52-
with:
53-
python-version: ${{ matrix.python-version }}
54-
55-
- name: Install dependencies
56-
run: |
57-
python -m pip install --upgrade pip
58-
pip install -e .
59-
pip install pytest
60-
61-
- name: Run tests
62-
run: pytest tests/ -v
63-
64-
- name: Verify CLI entry point
65-
run: context-profiler --help

‎CLAUDE.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# CLAUDE.md
2+
3+
This file guides AI coding agents working on `context-profiler`.
4+
5+
## Project Overview
6+
7+
`context-profiler` is a trace-source agnostic context analysis harness for LLM agents. It accepts raw provider requests, observability traces, local coding-agent transcripts, and future benchmark trajectories, then reports how context grows, repeats, and concentrates around tools/artifacts.
8+
9+
Core boundary: this project analyzes traces. It does not fetch traces, replay agent loops, or execute third-party tools.
10+
11+
## Common Commands
12+
13+
```bash
14+
# Run the smoke suite
15+
PYTHONPATH=src uv run --with pytest pytest tests/test_smoke.py -v
16+
17+
# Check CLI entry point
18+
PYTHONPATH=src uv run context-profiler --help
19+
20+
# Analyze a raw request
21+
PYTHONPATH=src uv run context-profiler analyze tests/fixtures/repeated_tool_calls.json --format openai
22+
23+
# Diagnose a transcript
24+
PYTHONPATH=src uv run context-profiler diagnose tests/fixtures/cursor_transcript.jsonl --format cursor-jsonl --json
25+
26+
# Generate HTML
27+
PYTHONPATH=src uv run context-profiler analyze tests/fixtures/cursor_transcript.jsonl --format cursor-jsonl --html /tmp/context-profiler-report.html
28+
```
29+
30+
## Architecture
31+
32+
- `src/context_profiler/cli.py` — Click CLI entry point.
33+
- `src/context_profiler/formats.py` — format registry exposed to agents.
34+
- `src/context_profiler/schemas.py` — JSON Schemas for agent-readable contracts.
35+
- `src/context_profiler/validation.py` — validation and canonical normalization helpers.
36+
- `src/context_profiler/profiler.py` — session/request loading and analyzer orchestration.
37+
- `src/context_profiler/analyzers/` — token, repeat, and field analyzers.
38+
- `src/context_profiler/context_diff.py` — turn-to-turn diff evidence and hints.
39+
- `src/context_profiler/diagnostics.py` — stable issue-code diagnosis JSON.
40+
- `src/context_profiler/reporters/` — CLI, JSON, and HTML reports.
41+
- `src/context_profiler/templates/report.html` — self-contained report UI.
42+
- `skills/` — public Agent Skills distribution.
43+
44+
## Format and Analyzer Rules
45+
46+
- Add synthetic fixtures under `tests/fixtures/`; do not commit real private traces.
47+
- Every supported format must have metadata in `formats.py` with `input_kind`, `confidence`, `analysis_scope`, `limitations`, and `agent_conversion_guidance`.
48+
- Keep analyzer outputs evidence-first: issue code, severity, token counts, request indices, tool names, artifact keys, and recommendation.
49+
- For heuristic findings, use hint language such as `possible_*` and include confidence.
50+
- Do not overclaim exactness for `agent-transcript`; transcripts may omit hidden prompts, tool definitions, rules, and provider compaction.
51+
52+
## Product Boundaries
53+
54+
Do not add provider-specific fetch clients to core. Agents can use Langfuse CLI, SDKs, Hugging Face tooling, or local transcript discovery to obtain data, then pass files or stdin to `context-profiler`.
55+
56+
Do not make Toolathlon a first-class multi-turn demo. Prefer genuinely multi-turn datasets such as `pagarsky/agent-trace`, `cx-cmu/agent_trajectories`, and SWE-agent trajectories for future research examples.
57+
58+
## Skill Distribution
59+
60+
Canonical public skills live in `skills/`.
61+
62+
Do not put product-distribution skills in `.agents/skills/` or `.claude/skills/`; those directories are for project-local agent behavior.
63+
64+
If skill paths change, update:
65+
66+
- `.plugin/plugin.json`
67+
- `.claude-plugin/marketplace.json`
68+
- README skill distribution section
69+
- tests covering manifests

‎SECURITY.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Security Policy
2+
3+
## Reporting Vulnerabilities
4+
5+
Please report security issues privately by opening a GitHub security advisory or contacting the maintainer.
6+
7+
Do not include private traces, credentials, API keys, customer data, or production prompts in public issues.
8+
9+
## Trace Data Safety
10+
11+
Agent traces often contain sensitive data:
12+
13+
- API keys and bearer tokens
14+
- customer messages
15+
- source code
16+
- internal file paths
17+
- prompts and tool schemas
18+
- stack traces and environment variables
19+
20+
Before sharing examples publicly, redact or synthesize trace content. Prefer minimal synthetic fixtures that reproduce the behavior being discussed.
21+
22+
## Project Boundary
23+
24+
`context-profiler` is a local analysis tool. It does not upload traces or call remote APIs by default.
25+
26+
Future integrations should preserve this boundary unless explicitly documented and opt-in.

0 commit comments

Comments
 (0)