ctxray

See how you really use AI.

X-ray your AI coding sessions across Claude Code, Cursor, ChatGPT, and 6 more tools. Discover your patterns, find wasted tokens, catch leaked secrets — all locally, nothing leaves your machine.

Quick start

pip install ctxray

ctxray scan                    # discover prompts from your AI tools
ctxray wrapped                 # your AI coding persona + shareable card
ctxray insights                # your patterns vs research-optimal
ctxray privacy                 # what sensitive data you've exposed

Works in your pipeline

Drop ctxray into your CI as a prompt quality gate. No LLM, no API key, no network —

More screenshots

`ctxray rewrite` — rule-based prompt improvement

`ctxray build` — assemble prompts from components

What a bad prompt looks like

All commands

Discover your patterns

Optimize your prompts

Manage

Supported AI tools

Installation

pip install ctxray              # core (all features, zero config)
pip install ctxray[chinese]     # + Chinese prompt analysis (jieba)
pip install ctxray[mcp]         # + MCP server for Claude Code / Continue.dev / Zed

Auto-scan after every session

ctxray install-hook             # adds post-session hook to Claude Code

Browser extension

Capture prompts from ChatGPT, Claude.ai, and Gemini directly in your browser. Live quality badge shows prompt tier as you type — click "Rewrite & Apply" to improve and replace the text directly in the input box.

1. Install the extension from Chrome Web Store or Firefox Add-ons

2. Connect to the CLI: `ctxray install-extension`

3. Verify: `ctxray extension-status`

Captured prompts sync locally via Native Messaging — nothing leaves your machine.

CI integration

GitHub Action

# .github/workflows/prompt-lint.yml
name: Prompt Quality
on: pull_request

jobs:
  lint:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: ctxray/ctxray@main
        with:
          score-threshold: 43     # experimentally validated (below = 83% failure rate)
          model: claude           # optional: model-specific rules
          strict: true
          comment-on-pr: true

pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/ctxray/ctxray
    rev: v3.0.0
    hooks:
      - id: ctxray-lint-score     # quality threshold gate (score >= 43)
      # - id: ctxray-lint-claude  # Claude-specific rules + threshold
      # - id: ctxray-lint-gpt    # GPT-specific rules + threshold

Direct CLI

ctxray lint --score-threshold 43  # exit 1 below experimentally validated threshold
ctxray lint --score-threshold 50  # or set your own bar
ctxray lint --model claude        # model-specific lint rules
ctxray lint --strict              # exit 1 on warnings
ctxray lint --json                # machine-readable output

Project configuration

ctxray init   # generates .ctxray.toml with all rules documented

# .ctxray.toml (or [tool.ctxray.lint] in pyproject.toml)
[lint]
score-threshold = 43   # experimentally validated quality threshold
model = "claude"       # model-specific rules (claude/gpt/gemini)

[lint.rules]
min-length = 20
short-prompt = 40
vague-prompt = true
debug-needs-reference = true

Prompt Science — research foundation

Prompt Science

Scoring is calibrated against 10 peer-reviewed papers covering 30+ features across 5 dimensions:

Cross-validated findings that inform our engine:

• Position bias is architectural — present at initialization, not learned. Front-loading instructions is effective for prompts under 50% of context window (3 papers agree)
• Moderate compression improves output — rule-based filler removal doesn't just save tokens, it enhances LLM performance (2505.00019)
• Prompt quality is independently measurable — prompt-only scoring predicts output quality without seeing the response (ACL 2025, 2503.10084)
• Quality threshold at score ~43 — our own experiment (30 prompts, 5 tiers, 2 models) found a step function: below 43, 83% failure rate; above 43, 94% success (Pearson r=0.56, Spearman ρ=0.64)
• Format preferences are model-dependent — XML benefits Claude, Markdown benefits GPT, but having *any* structure matters more than the specific format (PromptBridge 2512.01420)

Model-specific scoring (`--model claude/gpt/gemini`) applies research-backed adjustments for each model's known preferences and sensitivities.

All analysis runs locally in

How it works — architecture

How it works

Data sources:
 ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
 │Claude Code│ │  Cursor  │ │  Aider   │ │ ChatGPT  │ │ 5 more.. │
 └─────┬────┘ └─────┬────┘ └─────┬────┘ └─────┬────┘ └─────┬────┘
       └─────────────┴───────────┴─────────────┴─────────────┘
                                 │
                    scan -> dedup -> store -> analyze
                                 │
              ┌──────────────────┼──────────────────┐
              v                  v                  v
        ┌──────────┐     ┌──────────────┐    ┌──────────┐
        │ insights │     │  patterns    │    │ sessions │
        │ wrapped  │     │  repetition  │    │ projects │
        │ style    │     │  privacy     │    │ agent    │
        └──────────┘     └──────────────┘    └──────────┘

Key design decisions:

• Pure rules, no LLM — scoring and rewriting use regex + TF-IDF + research heuristics. Deterministic, private,

Conversation Distillation

Conversation Distillation

`ctxray distill` scores every turn in a conversation using 6 signals:

• Position — first/last turns carry framing and conclusions
• Length — substantial turns contain more information
• Tool trigger — turns that cause tool calls are action-driving
• Error recovery — turns that follow errors show problem-solving
• Semantic shift — topic changes mark conversation boundaries
• Uniqueness — novel phrasing vs repetitive follow-ups

Session type (debugging, feature-dev, exploration, refactoring) is auto-detected and signal weights adapt accordingly.

Why ctxray?

After Promptfoo joined OpenAI and Humanloop joined Anthropic, ctxray is the independent, open-source alternative for understanding your AI interactions.

• 100% local — your prompts never leave your machine
• No LLM required — pure rule-based analysis, Previously published as `reprompt-cli`. Same tool, new name, clean namespace.

Privacy

• All analysis runs locally. No prompts leave your machine.
• `ctxray privacy` shows exactly what you've sent to which AI tool.
• Optional telemetry sends only anonymous feature vectors — never prompt text.
• Open source: audit exactly what's collected.

Links

• PyPI: ctxray
• Chrome Extension: Chrome Web Store
• Firefox Add-on: Firefox Add-ons
• Changelog: CHANGELOG.md

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT