Skip to content

Quickstart

A minimal walk-through: attach the callback, run your DSPy agent, open the dashboard.

1. Install

uv add ctxrot

ctxrot requires Python 3.12+ and DSPy ≥ 3.1.3.

2. Attach the callback

import dspy
from ctxrot import CtxRotCallback

callback = CtxRotCallback(db_path="ctxrot.db", store_content=True)

dspy.configure(
    lm=dspy.LM("openai/gpt-5.4-mini"),
    callbacks=[callback],
)
  • A new session is created automatically each time a top-level DSPy module starts. Every LM call and tool call is recorded to SQLite.
  • Set store_content=True to also store full prompt messages and completion text — required for repetition detection.

3. Run your agent as usual

react = dspy.ReAct("question -> answer", tools=[tool_a, tool_b])
result = react(question="What is the capital of France?")

No changes to your agent code — the callback just listens.

4. View the dashboard

ctxrot --db ctxrot.db

The TUI opens on the Feed — a list of sessions with LM-call and tool-call feeds.

5. Run a local analysis

Without leaving the terminal, you can compute repetition and efficiency metrics for the latest session:

ctxrot analyze --db ctxrot.db

See Concepts for what the numbers mean, and the CLI reference for every command and flag.

Next