errd

Debug with less context.

errd is a local-first Python CLI that analyzes tracebacks, finds the code most relevant to a failure, and generates a focused debugging context for AI coding assistants.

Instead of giving an AI your entire repository, errd extracts the code most relevant to the error.

pip install errd
errd analyze error.log

No LLM. No API key. No cloud. Your code stays local during analysis.

---

Installation

Requires Python 3.11+.

pip install errd

Verify:

errd --version

---

The Problem

When an error occurs in a large codebase, developers often give an AI coding assistant a large portion of the repository to provide enough context.

This creates two problems:

• Unnecessary context — most of the repository is unrelated to the failure.
• Context cost — larger prompts consume more tokens and can make debugging harder by introducing irrelevant information.

The challenge isn't simply giving an AI more code.

It's giving it the right code.

---

What errd Does

Python traceback
       │
       ▼
     errd
       │
       ├── Parse traceback
       ├── Find repository
       ├── Locate failing source
       ├── Analyze Python code
       ├── Follow import dependencies
       ├── Rank relevant symbols
       ├── Apply token budget
       └── Redact obvious secrets
       │
       ▼
errd-context.md
       │
       ▼
Claude / GPT / Gemini / Cursor

errd does not try to fix the bug itself.

It prepares the smallest useful debugging context for the AI tool you already use.

---

Example

Suppose your repository contains roughly 48,000 tokens of Python source.

A traceback points to:

app/database/repository.py:63

Instead of manually finding the relevant files, errd can produce a focused context such as:

errd analysis complete

Error              UniqueViolationError
Crash site         app/database/repository.py:63

Relevant symbols   7
Selected context   3,184 tokens
Repository source  47,821 tokens
Reduction           93.3%

Output             errd-context.md

The numbers above are illustrative output from the included example fixture, not benchmark results.

The generated errd-context.md can then be provided to Claude, GPT, Gemini, Cursor, or another coding assistant.

---

How It Works

Stage 1 — Local Analysis

No AI or API key is required.

1. Parse the traceback

Extracts:

• exception type
• exception message
• traceback frames
• source paths
• line numbers
• function names when available

Supports chained exceptions and noisy log output.

2. Discover the repository

errd attempts to locate the project automatically.

You can also explicitly specify it:

errd analyze error.log --repo /path/to/project

3. Analyze Python source

errd uses Tree-sitter to locate:

• functions
• methods
• classes
• imports
• relevant source ranges

Tree-sitter is fault-tolerant, allowing analysis of files that may contain syntax errors.

4. Build an import dependency graph

errd follows Python module-level import relationships to find code connected to the failing location.

V0.1 does not attempt complete dynamic or inter-procedural call-graph analysis.

5. Rank relevant code

Symbols are scored using deterministic signals including:

• traceback proximity
• dependency distance
• source location
• user-code relevance
• Git modification signals

Recently modified files can receive an additional relevance boost.

6. Apply a token budget

errd analyze error.log --budget 4000

errd selects the highest-value context that fits the requested budget.

Large symbols can be structurally reduced when necessary.

7. Redact obvious secrets

Before generating the final context, errd attempts to redact common secrets such as:

• API keys
• AWS credentials
• JWTs
• Bearer tokens
• database credentials
• passwords
• private keys

---

Stage 2 — AI Debugging

The output is a Markdown file:

errd-context.md

Give that context to your preferred AI coding assistant:

Claude
GPT
Gemini
Cursor

The AI performs the actual debugging.

errd simply makes sure it receives focused context first.

---

Usage

Analyze a traceback

errd analyze error.log

Set a custom token budget

errd analyze error.log --budget 8000

Specify an output file

errd analyze error.log --output debug-context.md

Specify the repository explicitly

errd analyze error.log --repo /path/to/my-project

Show help

errd --help

---

Output

The generated Markdown contains:

Error
Traceback
Repository information
Relevant source files
Relevant code snippets
Relevance information
Debugging task

The goal is to produce something you can directly give to an AI coding assistant.

---

Tech Stack

Component	Technology
Language	Python 3.11+
CLI	Typer + Rich
Python parsing	Tree-sitter + tree-sitter-python
Dependency analysis	Python standard library + BFS
Token counting	tiktoken
Git signals	Git CLI
Secret redaction	Regex-based patterns
Testing	pytest
Linting	Ruff
Type checking	mypy

No LLM is required.

No API key is required.

The analysis runs locally.

---

Why Tree-sitter?

Why not Python's built-in ast module?

Debugging often involves code that is incomplete or syntactically broken.

ast.parse() raises a SyntaxError when it cannot parse the file.

Tree-sitter is fault-tolerant and can produce a partial syntax tree, allowing errd to extract useful structural information even from imperfect source files.

---

Security

errd includes a lightweight, best-effort secret redaction layer.

It detects common patterns such as:

• AWS access keys
• API keys
• Bearer tokens
• JWTs
• database URLs containing credentials
• password configuration values
• private key blocks

Detected values are replaced with:

[REDACTED]

Important

This is not a complete secret scanner.

It uses pattern-based detection and cannot guarantee that every secret will be detected.

Always review generated context before sharing it with an external AI service.

---

Privacy

errd performs its analysis locally.

V0.1 does not send your source code, traceback, or repository to an errd server.

There is no required cloud service or LLM API.

You choose if and where the generated context is subsequently shared.

---

Limitations — V0.1

errd is intentionally narrow.

Python only

V0.1 supports Python projects.

JavaScript, TypeScript, Go, Rust, Java, and other languages are not currently supported.

Import-level dependencies

V0.1 analyzes module-level import relationships.

It does not provide complete inter-procedural call-graph analysis and cannot perfectly understand dynamic Python behavior such as:

• dynamic imports
• monkey patching
• runtime-generated attributes
• complex dependency injection
• dynamic dispatch

Heuristic relevance

The relevance scorer is deterministic and heuristic-based.

It does not use embeddings or machine learning.

Token estimates

V0.1 uses tiktoken for token estimation.

Token counts can differ from the tokenizer used by Claude, Gemini, or other models.

Best-effort redaction

Secret detection is pattern-based and is not a security guarantee.

Git is optional

Git information can improve relevance scoring, but errd can operate without Git.

---

Development

Clone the repository:

git clone https://github.com/Das-R10/errd.git
cd errd

Install in development mode:

pip install -e ".[dev]"

Run tests:

pytest

Run linting:

ruff check .

Run formatting check:

ruff format --check .

Run type checking:

mypy --strict

---

Architecture

The V0.1 pipeline is:

Traceback
    ↓
Traceback Parser
    ↓
Repository Discovery
    ↓
Tree-sitter Analysis
    ↓
Dependency Analysis
    ↓
Relevance Scoring
    ↓
Token Budgeting
    ↓
Secret Redaction
    ↓
Markdown Context

See docs/ARCHITECTURE.md for details.

---

Testing

The current V0.1 implementation includes:

• 143 tests
• 91% code coverage
• Ruff linting
• strict mypy type checking
• CLI smoke tests
• end-to-end fixtures

Run the full suite with:

pytest

---

Benchmarking

A benchmark framework is included for evaluating errd on real-world debugging tasks.

The planned evaluation measures:

• repository source baseline
• selected context size
• token reduction
• selected file count
• fix-file recall
• fix-function recall
• relevant-line/context recall
• runtime

The full SWE-bench evaluation has not yet been completed.

Benchmark results will be added once the evaluation has been run.

---

Roadmap

V0.1 — Current

• Python traceback analysis
• Repository discovery
• Tree-sitter source analysis
• Import-level dependency analysis
• Deterministic relevance scoring
• Token-aware context selection
• Git relevance signals
• Secret redaction
• Markdown debugging context
• CLI
• Benchmark framework

V0.2 — Planned

Potential improvements based on V0.1 benchmark results:

• improved graph-based relevance ranking
• Personalized PageRank evaluation
• better context selection
• --explain scoring output
• additional input formats
• improved Git intelligence

V0.2 features will be driven by benchmark results rather than added solely for feature breadth.

Later

• additional language support
• editor integrations
• deeper debugging workflows

---

Contributing

Contributions are welcome.

If you find a bug, have an idea, or want to improve the analysis pipeline, open an issue or pull request.

Please keep contributions focused on errd's core goal:

Find the smallest useful debugging context for an error.

---

License

Apache License 2.0.