# Telebugs

> Use when calling Telebugs MCP tools — loading deferred tools via ToolSearch, URL patterns, parsing large JSON responses, and data fetching. Reference guide, not an investigation workflow.

- Skill: `zhuravel/telebugs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhuravel/telebugs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhuravel/telebugs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: zhuravel (https://skillmd.com/u/zhuravel)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zhuravel/telebugs

---


# Telebugs

Reference for working with Telebugs MCP tools. Tools are **deferred** and must be loaded before use.
Report responses are large and need structured extraction.

## Loading Tools

Tools are deferred MCP tools — load them via ToolSearch before calling:

```text
ToolSearch: "+telebugs get error report"
ToolSearch: "+telebugs list reports"
```

## URL Pattern

Telebugs URLs follow: `https://<your-telebugs-host>/errors/{group_id}/reports/latest`

- Extract `group_id` from the URL path
- There is no "latest report" API — fetch via `list_reports` with `group_id` and `limit: 1`

## Data Model

- **Error group**: deduplicated errors with occurrence count, notes, status. Small response (~5KB).
- **Report**: single error occurrence with full stack traces, breadcrumbs, context. Large response (30-50KB+).

## Fetching Data

Fetch error group and latest report list in parallel:

```text
mcp__telebugs__get_error_group(group_id)
mcp__telebugs__list_reports(group_id, limit: 1)
```

The error group response includes **notes** from team members — read these first for context.
Then get the full report using the report ID from the list:

```text
mcp__telebugs__get_report(report_id)
```

## Parsing Large Report Responses

The `get_report` response is saved to a file as: `[{type: "text", text: "<nested JSON>"}]`.

**Do NOT try to Read the file directly** — it exceeds token limits.
Use Bash with Python to extract each section separately:

**Error details** — what broke, when, how often:

```bash
cat RESULT_FILE | python3 -c "
import json, sys
data = json.load(sys.stdin)
report = json.loads(data[0]['text'])['report']
print(f\"Error: {report['error_type']}\")
print(f\"Message: {report['error_message'][:500]}\")
print(f\"Environment: {report['environment']}\")
print(f\"Occurred: {report['occurred_at']}\")
print(f\"Server: {report['server']}\")
print(f\"Release: {report['release']}\")
print(f\"Severity: {report['severity']}\")
print(f\"Handled: {report['handled']}\")
"
```

**Stack traces** — where it broke (all chained exceptions):

```bash
cat RESULT_FILE | python3 -c "
import json, sys
data = json.load(sys.stdin)
report = json.loads(data[0]['text'])['report']
for i, st in enumerate(report.get('stack_traces', [])):
    print(f'=== EXCEPTION {i}: {st.get(\"exception_type\")} ===')
    print(st.get('exception_value', '')[:500])
    for j, frame in enumerate(st.get('frames', [])):
        marker = ' *' if frame.get('in_app') else ''
        print(f'  {j}: {frame[\"file\"]}:{frame[\"line\"]} in {frame[\"function\"]}{marker}')
        if frame.get('context_line') and frame.get('in_app'):
            print(f'     > {frame[\"context_line\"].strip()}')
"
```

Focus on frames marked `*` — those are your code (`in_app: 1`), not gems/libraries.

**Breadcrumbs** — what happened right before the error:

```bash
cat RESULT_FILE | python3 -c "
import json, sys
data = json.load(sys.stdin)
report = json.loads(data[0]['text'])['report']
for b in report.get('breadcrumbs', []):
    cat = b.get('category', '')
    data_str = json.dumps(b.get('data', {}), default=str)[:200]
    print(f'[{b.get(\"timestamp\")}] {cat} {data_str}')
"
```

**Tags, context, request, user** — additional metadata:

```bash
cat RESULT_FILE | python3 -c "
import json, sys
data = json.load(sys.stdin)
report = json.loads(data[0]['text'])['report']
for key in ['tags', 'contexts', 'request', 'user']:
    val = report.get(key)
    if val:
        print(f'=== {key} ===')
        print(json.dumps(val, indent=2, default=str)[:1000])
"
```

## Quick Reference

| Tool | Purpose |
| ---- | ------- |
| `get_error_group(group_id)` | Group summary, notes, occurrence count |
| `list_reports(group_id, limit)` | Recent occurrences (compact) |
| `get_report(report_id)` | Full report with stack traces, breadcrumbs |
| `list_error_groups(project_id, status)` | Find related errors |
| `search_errors(query)` | Search by error message |
| `get_statistics(project_id, period)` | Error trends over time |
| `resolve_error_group(group_id)` | Mark as fixed |
| `add_note(group_id, content)` | Add investigation notes |

## Common Mistakes

| Mistake | Fix |
| ------- | --- |
| Trying to Read the result file | Always use Bash + Python to extract sections |
| Calling `get_report` without report ID | First use `list_reports(group_id, limit: 1)` to get the ID |
| Using `::` in search_errors queries | Use simpler keywords — `::` causes SQLite parse errors |
| Ignoring breadcrumb timing gaps | Large gaps (10-20s) between timestamps reveal blocking operations |