Lint, profile, and optimize LLM context windows.

contextlint is a Python package and CLI for analyzing where context tokens go, identifying waste, and suggesting safer budget allocations for agent workflows.

The repository now has three clear areas:

• product and technical docs in docs/
• installable Python code in src/contextlint/
• tests in tests/

uv sync
uv run contextlint --help
uv run ctxbgt --help
pytest

• Profile a JSON messages payload from a file or stdin.
• Normalize tool schemas and messages into typed internal records.
• Produce a first-pass component breakdown for system prompts, tool definitions, conversation history, tool results, and a few heuristic categories.
• Expose the same profiling flow through the CLI and importable library functions.

{
  "messages": [
    { "role": "system", "content": "You are a careful coding assistant." },
    { "role": "user", "content": "Review this patch." },
    { "role": "tool", "content": "diff output here" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_code",
        "description": "Search the repository"
      }
    }
  ]
}

Run it with:

uv run contextlint profile trace.json
uv run contextlint lint trace.json
cat trace.json | uv run contextlint profile

contextlint/
├── docs/
│   ├── README.md
│   ├── architecture/
│   │   └── system-architecture.md
│   ├── planning/
│   │   └── implementation-plan.md
│   ├── research/
│   │   └── market-analysis.md
│   └── planning.md
├── pyproject.toml
├── README.md
├── src/
│   └── contextlint/
│       ├── __init__.py
│       ├── __main__.py
│       ├── cli.py
│       ├── commands.py
│       └── py.typed
└── tests/
    └── test_cli.py

Start with docs/README.md for the documentation map.

• docs/architecture/ holds technical design material.
• docs/planning/ holds execution plans and delivery sequencing.
• docs/research/ holds market and positioning research.
• docs/planning.md is the lightweight working roadmap for near-term priorities.

• The CLI entry point lives in contextlint.cli.
• Command handlers live in contextlint.commands.
• The reusable profiling pipeline lives in contextlint.profiler and contextlint.normalize.
• ctxbgt remains available as an alias for the main CLI.

1. Add the core context profile data model.
2. Implement token counting and message normalization.
3. Add the first lint and profile execution pipeline.
4. Introduce fixtures for representative message traces.