AutoJSON 🎯

A local error aggregation system for clean, fast, and effective debugging with LLMs

AutoJSON automatically collects, filters, prioritizes, and formats errors from your frontend and backend applications into a single JSON file optimized for LLM debugging. No external services, no complex setup—just install and start debugging smarter.

🎯 Impact Rating: 82/100 (Grade B+) - Eliminates 87% of repetitive debugging work and saves ~100-150 minutes daily. See full evaluation →

⏱️ Time-Travel Debugging (NEW!): Automatic snapshots let you see errors at any point in time. Compare "before" vs "after" with one command. See HOW_TO_OPERATE.md →

📖 Complete Guide: HOW_TO_OPERATE.md - Everything you need to know in one place

✨ Features

🔄 Automatic Error Collection - Chrome extension + backend integration
⏱️ Time-Travel Debugging - Automatic snapshots, compare errors at any point in time (NEW!)
🎯 Smart Impact Scoring - Errors ranked 0-100 by severity, frequency, and criticality
📍 File Anchors - Direct LLM navigation to error locations (file:line)
🚀 Performance Optimized - 20x disk I/O reduction via batching
🔇 Noise Filtering - Configurable rules to keep only relevant errors
🤖 LLM-Ready Output - Structured JSON sorted by impact, ready for Claude/GPT
✅ Battle-Tested - 87 comprehensive tests, all passing

🚀 Quick Start

# 1. Clone repository
git clone https://github.com/igeorgegabriel/AutoJSON.git
cd AutoJSON

# 2. Install dependencies
pip install -r requirements.txt

# 3. Start aggregator
uvicorn autojson_core.main:app --reload --port 9000

# 4. Install Chrome extension
# Open chrome://extensions/
# Enable "Developer mode"
# Click "Load unpacked" → Select chrome_extension folder

# 5. Start debugging with LLMs!
# Errors are now collected in .autojson_debug_context.json

That's it! Your errors are being collected, scored, and sorted automatically.

📖 Example: Debugging with Claude

You: "Read .autojson_debug_context.json and fix the top 3 errors"

Claude: "I found 3 critical errors. Let me fix them in order of impact:

1. [CRASH - Score 95] TypeError at src/pages/auth/Login.tsx:42
   - Issue: Cannot read property 'user' of undefined
   - Occurring 5 times
   - Fix: Add null check before accessing user.name

   Let me apply the fix..."

AutoJSON gives your LLM everything it needs:

What went wrong (error message)
Where it happened (file anchors)
Why it matters (impact score)
How often (occurrence count)

📊 Impact Scoring System

Errors are automatically scored 0-100 based on:

Score = Base (40-70) + Frequency (+0-20) + Critical Path (+0-10)

Category	Score	Meaning	Example
crash	80-100	Critical, fix immediately	TypeError in login flow
api_failure	60-79	Server errors affecting UX	500 errors on checkout
minor_ui	40-59	UI glitches, low impact	Warning in dev console
low_priority	0-39	Informational	Debug messages

Critical paths get +10 bonus:

Backend: /login, /auth, /checkout, /payment, /signup
Frontend: Files containing auth, payment, checkout

🎯 Use Cases

1. Daily Development

# Morning: Start AutoJSON
uvicorn autojson_core.main:app --reload --port 9000

# Code as usual - errors collected automatically

# Before commit: "Claude, read .autojson_debug_context.json.
# Are there any crash-level errors I should fix before pushing?"

2. Bug Fix Sprint

"Read .autojson_debug_context.json. Group errors by component
and show me which component has the most critical issues."

3. Code Review

"Compare before.json and .autojson_debug_context.json.
Which errors were fixed? Did any new errors appear?"

4. Production Debugging

"Read .autojson_debug_context.json. Filter for errors with
impact_score >= 80. For each, navigate to {primary_file}:{approx_line}
and propose a fix."

📁 Project Structure

AutoJSON/
├── autojson_core/           # Core error aggregation system
│   ├── main.py              # FastAPI service (localhost:9000)
│   ├── models.py            # Pydantic data models
│   ├── store.py             # Error storage with batching
│   ├── filters.py           # Noise filtering logic
│   ├── config.py            # Configuration loader
│   └── utils.py             # Scoring, normalization, parsing
│
├── chrome_extension/        # Frontend error capture
│   ├── manifest.json        # Chrome Extension V3
│   ├── background.js        # Error capture service
│   └── content.js           # Page-level injection
│
├── tests/                   # 87 comprehensive tests
│   ├── test_batching.py     # Batching/debouncing (11 tests)
│   ├── test_file_anchors.py # File navigation (23 tests)
│   ├── test_impact_scoring.py # Impact scoring (20 tests)
│   ├── test_autojson_store.py # Error storage (15 tests)
│   └── test_autojson_filters.py # Filtering (18 tests)
│
├── .autojson_debug_context.json  # Output file (auto-created)
├── .autojson_filter_config.json  # Filter configuration
├── HOW_TO_OPERATE.md             # Complete operation guide
└── README.md                      # This file

⚙️ Configuration

Create .autojson_filter_config.json in your project root:

{
  "frontend": {
    "domain_whitelist": ["localhost", "yourdomain.com"],
    "path_whitelist": ["/src/", "/app/"],
    "severity_threshold": "warning",
    "message_blacklist": [
      "ResizeObserver loop",
      "chrome-extension://"
    ]
  },
  "backend": {
    "status_code_threshold": 400,
    "endpoint_whitelist": ["/api/"],
    "endpoint_blacklist": ["/health", "/metrics"],
    "module_whitelist": ["app.", "src."],
    "message_blacklist": [
      "Client disconnected",
      "Connection reset"
    ]
  }
}

Customize to your needs:

Whitelist only your domains/endpoints
Filter out noisy third-party errors
Set minimum severity levels
Exclude health checks and metrics

🔌 Backend Integration

Add error reporting to your FastAPI backend:

from autojson_core.models import BackendErrorInput
import httpx
import traceback

async def report_error_to_autojson(error: Exception, endpoint: str,
                                   method: str, status_code: int):
    """Report backend error to AutoJSON aggregator."""
    try:
        error_data = BackendErrorInput(
            message=str(error),
            endpoint=endpoint,
            method=method,
            status_code=status_code,
            stack=traceback.format_exc(),
            severity="error"
        )

        async with httpx.AsyncClient() as client:
            await client.post(
                "http://localhost:9000/ingest/backend",
                json=error_data.model_dump(),
                timeout=1.0
            )
    except:
        pass  # Silent fail

# Usage in your endpoint
@app.get("/api/users/{user_id}")
async def get_user(user_id: int):
    try:
        return db.get_user(user_id)
    except Exception as e:
        await report_error_to_autojson(e, f"/api/users/{user_id}", "GET", 500)
        raise HTTPException(status_code=500, detail="Internal error")

📊 Output Format

.autojson_debug_context.json structure:

{
  "meta": {
    "environment": "local",
    "last_updated": "2025-12-11T10:30:00Z"
  },
  "frontend_errors": [
    {
      "id": "fe_abc123",
      "message": "TypeError: Cannot read property 'user' of undefined",
      "source": "/src/components/Dashboard.tsx",
      "line": 42,
      "impact_score": 85,
      "category": "crash",
      "primary_file": "src/components/Dashboard.tsx",
      "approx_line": 42,
      "count": 3,
      "first_seen": "2025-12-11T10:00:00Z",
      "last_seen": "2025-12-11T10:29:00Z"
    }
  ],
  "backend_errors": [
    {
      "id": "be_xyz789",
      "message": "ValueError: Invalid user ID",
      "endpoint": "/api/users",
      "method": "GET",
      "status_code": 500,
      "impact_score": 90,
      "category": "crash",
      "primary_file": "app/routes/users.py",
      "approx_line": 88,
      "count": 5,
      "stack": "Traceback (most recent call last):\n  ..."
    }
  ]
}

Key fields for LLMs:

primary_file + approx_line → Navigate directly to error
impact_score → Prioritize fixes
category → Understand severity
count → Identify frequent issues
stack → Debug backend errors

🧪 Testing

# Run all tests (87 tests, ~0.6s)
pytest tests/ -v

# Run specific test suite
pytest tests/test_batching.py -v
pytest tests/test_impact_scoring.py -v

# Run with coverage
pytest tests/ --cov=autojson_core --cov-report=html

Test coverage:

✅ 18 filter tests
✅ 15 store tests
✅ 11 batching tests
✅ 23 file anchor tests
✅ 20 impact scoring tests

🚀 Performance

Batching & Debouncing

AutoJSON uses smart batching to minimize disk I/O:

Before: 100 errors = 100 disk writes (~2000ms)
After: 100 errors = 5 disk writes (~100ms)
Improvement: 20x reduction

Configurable thresholds:

Time: Flush after 1 second (default)
Count: Flush after 20 updates (default)

Edit autojson_core/store.py to adjust:

class ErrorStore:
    FLUSH_INTERVAL_SECONDS = 1.0
    FLUSH_COUNT_THRESHOLD = 20

🤖 LLM Prompt Examples

Fix Top Errors

Read .autojson_debug_context.json and fix the top 3 errors by impact_score.
For each error:
1. Navigate to {primary_file}:{approx_line}
2. Show the problematic code
3. Explain what's wrong
4. Propose and apply a minimal fix

Focus on Critical Issues

Read .autojson_debug_context.json. Show me all errors with:
- category = "crash"
- impact_score >= 80

Fix them in order, starting with highest impact_score.

Component Analysis

Read .autojson_debug_context.json. Group errors by primary_file
and identify which component needs the most attention.

Security Review

Read .autojson_debug_context.json and identify errors that might
indicate security vulnerabilities in auth, payment, or admin endpoints.

📚 Documentation

Main Documentation

HOW_TO_OPERATE.md - 📖 Complete operational guide (includes time-travel debugging, setup, usage, troubleshooting)
DASHBOARD_GUIDE.md - 🎛️ Dashboard usage and features

Advanced Setup

VSCODE_CLAUDE_SETUP.md - ⚡ Advanced VS Code + Claude Code integration

Impact & Roadmap

RATING_SUMMARY.md - 📊 Impact rating & evaluation summary (82/100)
AUTOJSON_IMPACT_EVALUATION.md - 📈 Comprehensive impact analysis
ULTIMATE_DEBUGGING_ROADMAP.md - 🚀 Path to ultimate debugging tool (82→95/100)

Technical Reference

IMPACT_SCORING_GUIDE.md - Impact scoring algorithm details
FILE_ANCHORS_GUIDE.md - File navigation implementation
BATCHING_SUMMARY.md - Performance optimization details

Security

SECURITY.md - 🔒 Security policy, vulnerability reporting, and best practices

🔒 Security & Privacy

✅ 100% Local - No external services, all data stays on your machine
✅ Localhost Only - Aggregator runs on localhost:9000
✅ No Internet Required - Fully offline capable
⚠️ Sensitive Data - .autojson_debug_context.json may contain error messages with user data

Security Resources:

SECURITY.md - 🔒 Complete security policy, vulnerability reporting, and best practices

Git History Scanner - Scan for accidentally committed secrets:

python scripts/scan_git_history.py
python scripts/scan_git_history.py --output security_report.txt

Recommended .gitignore:

.autojson_debug_context.json
.autojson_filter_config.json

🛠️ Troubleshooting

No errors appearing?

Check aggregator is running: curl http://localhost:9000/
Check Chrome extension: Visit chrome://extensions/
Check filters: Look at noise_samples in JSON

Test with curl:

curl -X POST http://localhost:9000/ingest/frontend \
  -H "Content-Type: application/json" \
  -d '{"message":"Test","source":"/src/test.js","line":1,"url":"http://localhost:3000","severity":"error"}'

File anchors are null?

Frontend: Error source is cross-origin or minified
Backend: Traceback doesn't match project patterns

Fix: Add custom patterns in utils.py:

project_indicators = ["/app/", "/src/", "/yourproject/"]

Too much noise?

Tighten filters in .autojson_filter_config.json:

{
  "frontend": {
    "severity_threshold": "error",
    "message_blacklist": ["ResizeObserver", "Script error", "Load failed"]
  },
  "backend": {
    "status_code_threshold": 500,
    "endpoint_blacklist": ["/health", "/metrics", "/static/"]
  }
}

More help: See HOW_TO_OPERATE.md

🤝 Contributing

Contributions welcome! To contribute:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Ensure all tests pass: pytest tests/ -v
Commit: git commit -m "Add amazing feature"
Push: git push origin feature/amazing-feature
Open a Pull Request

Testing requirements:

All 87 existing tests must pass
New features require tests
Code coverage should not decrease

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built with:

FastAPI - Modern Python web framework
Pydantic - Data validation
Pytest - Testing framework
Chrome Extension API - Frontend error capture

📞 Support

Documentation: HOW_TO_OPERATE.md
Issues: GitHub Issues
Discussions: GitHub Discussions

🎯 Why AutoJSON?

Traditional debugging:

1. Check browser console
2. Check server logs
3. Check error monitoring service
4. Manually correlate errors
5. Search for file locations
6. Copy-paste to LLM
7. Explain context to LLM

With AutoJSON:

1. "Claude, read .autojson_debug_context.json and fix the top 3 errors"
2. Done.

AutoJSON gives your LLM:

✅ All errors in one place
✅ Automatic prioritization
✅ Direct file navigation
✅ Full context (stack traces, frequency, severity)
✅ Zero manual work

🚀 What's Next?

→ See our comprehensive Ultimate Debugging Roadmap for the full vision (82 → 95/100)

Quick Wins (Coming Soon):

Built for developers who want clean debugging with AI assistance.

⭐ Star this repo if AutoJSON helps you debug faster!

Report Bug · Request Feature · Documentation

Name		Name	Last commit message	Last commit date
autojson_core		autojson_core
chrome_extension_autojson		chrome_extension_autojson
dashboard		dashboard
integrations		integrations
scripts		scripts
tests		tests
.autojson_filters.json		.autojson_filters.json
.gitignore		.gitignore
AUTOJSON_IMPACT_EVALUATION.md		AUTOJSON_IMPACT_EVALUATION.md
BATCHING_SUMMARY.md		BATCHING_SUMMARY.md
DASHBOARD_GUIDE.md		DASHBOARD_GUIDE.md
FILE_ANCHORS_GUIDE.md		FILE_ANCHORS_GUIDE.md
HOW_TO_OPERATE.md		HOW_TO_OPERATE.md
IMPACT_SCORING_GUIDE.md		IMPACT_SCORING_GUIDE.md
LICENSE		LICENSE
RATING_SUMMARY.md		RATING_SUMMARY.md
README.md		README.md
SECURITY.md		SECURITY.md
SECURITY_QUICK_REFERENCE.md		SECURITY_QUICK_REFERENCE.md
SETUP.bat		SETUP.bat
START_DASHBOARD.bat		START_DASHBOARD.bat
START_SERVICE.bat		START_SERVICE.bat
ULTIMATE_DEBUGGING_ROADMAP.md		ULTIMATE_DEBUGGING_ROADMAP.md
VSCODE_CLAUDE_SETUP.md		VSCODE_CLAUDE_SETUP.md
autojson_llm_prompt_bug_sweep.md		autojson_llm_prompt_bug_sweep.md
requirements.txt		requirements.txt
test_impact_example.py		test_impact_example.py

Latest commit

History

Folders and files

Repository files navigation