error-trace-debugger

CLI agent that ingests logs/stack traces, investigates a codebase, and outputs a report with a suggested fix and (when possible) a unified patch.

Keywords

cli, logs, stack-trace, error-analysis, debugging, nodejs, javascript, jest, typescript, patch, diff, git, testing, langchain, langgraph, openai, llm, developer-tools, static-analysis, code-search

Install

npm install -g error-trace-debugger

Or run without installing:

npx error-trace-debugger analyze --help

Usage

Analyze a logs file

error-trace-debugger analyze --logs ./error.log

Analyze an inline stack trace

error-trace-debugger analyze --stack "TypeError: boom\n    at run (/repo/src/index.js:10:5)"

Pipe logs over stdin

cat ./error.log | error-trace-debugger analyze --stdin

Target a specific repo

error-trace-debugger analyze --logs ./error.log --repo ../my-repo

Scope (single repo)

error-trace-debugger analyzes one repo/workspace at a time. By default it uses the current working directory; you can override with --repo <path>.

Output formats

error-trace-debugger analyze --logs ./error.log --format md
error-trace-debugger analyze --logs ./error.log --format text
error-trace-debugger analyze --logs ./error.log --format json

If you keep the default --format md and do not pass --out, the CLI writes the full Markdown report to error-trace-debugger-report.md in the target repo root, and the terminal shows only a short “check out the file” message.

Write report + patch to files

error-trace-debugger analyze --logs ./error.log --out ./report.md --patch-out ./fix.diff
git apply ./fix.diff

Run tests (optional)

error-trace-debugger analyze --logs ./error.log --run-tests
error-trace-debugger analyze --logs ./error.log --run-tests --test-command "npm test"

Engine: v1 (default) vs v2 (LangGraph)

• v1 (default): heuristic loop (parse → search → diff → optional tests). No LLM.
• v2: LangGraph state machine with LLM-backed patch proposal.

For v2, run these in order:

1. Set your OpenAI API key in the shell:

export OPENAI_API_KEY="your_openai_api_key"

2. Run the v2 command:

error-trace-debugger analyze --engine v2 --logs ./error.log --repo .

Optional v2 flags: --provider openai, --model <name>, --api-key-env <ENV_VAR>, --max-tool-calls, --max-files-read, --max-bytes-read.

What it does (v1)

• Log analyzer: parses common Node/Jest stack traces into structured frames.
• Code search: uses ripgrep if available (otherwise scans within safe budgets).
• Diff generator: emits a unified patch when it has concrete edits to apply. If no edits are produced, the Patch section may be empty.
• Test runner: runs tests (optional) and summarizes failing output.

The orchestrator iteratively: logs → hypothesis → code search → patch proposal → (optional) tests.

Notes

• v1 focuses on investigation + reporting. Patch generation is supported when concrete edits are produced.
• PR creation is intentionally out of scope for v1.