Skip to content

Getting Started

Jump to bottom
github-actions[bot] edited this page Mar 15, 2026 · 1 revision

Getting Started

Install

python3 -m pip install -e .[dev]

For exact tokenization via tiktoken:

python3 -m pip install -e .[tokenizers]

Core Workflow

# 1. Rank relevant files for a task
contextbudget plan "add caching to search API" --repo .

# 2. Pack context under a token budget
contextbudget pack "add caching to search API" --repo . --max-tokens 30000

# 3. Summarize the generated run artifact
contextbudget report run.json

Extended Workflow

# Compare two run artifacts
contextbudget diff old-run.json new-run.json

# Compare packing strategies side-by-side
contextbudget benchmark "add rate limiting to auth API" --repo .

# Analyze token savings by compression stage
contextbudget profile run.json

# Detect duplicate or unnecessary file reads
contextbudget read-profiler run.json

Multi-step Agent Planning

# Plan context usage across a multi-step agent workflow
contextbudget plan-agent "refactor auth middleware" --repo .

Workspace (Multi-repo)

Create a workspace.toml:

name = "backend-services"

[scan]
include_globs = ["**/*.py"]

[budget]
max_tokens = 28000
top_files = 24

[[repos]]
label = "auth-service"
path = "../auth-service"

[[repos]]
label = "billing-service"
path = "../billing-service"

Then run across all repos:

contextbudget pack "add caching" --workspace workspace.toml

Generated Artifacts

Every pack run writes:

  • run.json — machine-readable artifact with ranked files, compressed context, budget stats, cache info
  • run.md — human-readable Markdown summary

Python API Quickstart

from contextbudget import BudgetGuard

guard = BudgetGuard(max_tokens=30000)
result = guard.pack_context(task="add caching", repo=".")

budget = result["budget"]
print(f"tokens: {budget['estimated_input_tokens']} / {guard.max_tokens}")
print(f"saved:  {budget['estimated_saved_tokens']}")
print(f"risk:   {budget['quality_risk_estimate']}")

# Build a prompt from the compressed context
prompt = "\n".join(f["text"] for f in result["compressed_context"])

See Python API for the full reference.

Next Steps

Clone this wiki locally