Automated Bug Reporting System
Relevant source files
The following files were used as context for generating this wiki page:
The Automated Bug Reporting System is a diagnostic and report generation utility designed to streamline the identification and documentation of issues within the claude-mem ecosystem. It automates the collection of system environment data, version information, and logs, combining this technical data with user-provided descriptions to create a formatted GitHub issue.
The system leverages the Claude Agent SDK to transform raw diagnostics and multi-language user input into professional, English-language bug reports. It ensures that critical debugging information—such as worker status, platform details, and recent logs—is consistently included in every report, reducing the back-and-forth between users and maintainers.
Sources: README.md:231-236, scripts/bug-report/cli.ts:74-85, scripts/bug-report/index.ts:153-176
System Architecture
The system is structured into three primary layers: the Command Line Interface (CLI) for user interaction, the Diagnostic Collector for system inspection, and the Generation Engine which utilizes AI for formatting.
The diagram above illustrates the data flow from initial user invocation to the final automated opening of a GitHub issue.
Sources: scripts/bug-report/cli.ts:108-208, scripts/bug-report/index.ts:25-60
Component Breakdown
1. CLI Interface (cli.ts)
The CLI manages the lifecycle of a bug report generation session. It parses arguments, displays system summaries, and conducts an interactive interview with the user.
- Key Functionality:
- Argument parsing for verbose mode and log exclusion.
- Interactive multi-line prompting for issue descriptions and reproduction steps.
- Automated opening of the generated report in the system's default browser.
| Option | Alias | Description |
|---|---|---|
--output | -o | Save report to a specific file (default: ~/bug-report-TIMESTAMP.md). |
--verbose | -v | Show all collected diagnostics in the terminal. |
--no-logs | N/A | Skip log collection for privacy. |
--help | -h | Display usage instructions. |
Sources: scripts/bug-report/cli.ts:18-63, scripts/bug-report/cli.ts:173-195
2. Generation Engine (index.ts)
The engine handles the core logic of constructing the bug report. It uses the Claude Agent SDK to query the sonnet model with a structured prompt containing system diagnostics.
- Logic Flow:
- Receives user input (description, expected behavior, steps).
- Invokes
collectDiagnosticsto gather environment data. - Constructs a system prompt for the AI to act as a "GitHub issue formatter."
- Streams the response from Claude, displaying a progress spinner to the user.
- Falls back to a template-based generator if the SDK query fails.
Sources: scripts/bug-report/index.ts:25-62, scripts/bug-report/index.ts:88-100
3. Diagnostic Collection
The system gathers specific technical metrics to assist in debugging. This is managed primarily via collector.ts (invoked by cli.ts and index.ts).
- Collected Data Points:
- Versions:
claude-memandClaude Codeversions. - Platform: OS version and architecture (e.g., darwin x64).
- Worker Status: Whether the
claude-memworker is running, its PID, and its port. - Logs: Recent lines from
workerLogandsilentLog.
- Versions:
Sources: scripts/bug-report/cli.ts:121-140, scripts/bug-report/index.ts:14-23
Workflow Sequence
The following sequence diagram details the interaction between the user's terminal and the backend services during report generation.
The diagram shows the synchronous collection of data followed by the asynchronous AI generation and final output to the user's local filesystem and browser.
Sources: scripts/bug-report/cli.ts:145-200, scripts/bug-report/index.ts:40-75
AI Prompt Engineering
The system uses a specific system prompt to ensure the AI generates useful, structured Markdown. It explicitly instructs the model to translate any non-English input to English to maintain repository standards.
// scripts/bug-report/index.ts:114-118
const systemPrompt = `You are a GitHub issue formatter. Format bug reports clearly and professionally.`;
// scripts/bug-report/index.ts:153-155
// The prompt includes specific requirements:
// 1. Descriptive title (max 80 chars)
// 2. Environment section from diagnostics
// 3. Translation of user description to English
Sources: scripts/bug-report/index.ts:50-52, scripts/bug-report/index.ts:153-176
Integration with Worker Service
The bug reporting system checks the status of the WorkerService. This service, managed by Bun, runs on port 37777 and handles AI processing for the main application. The bug report collector specifically verifies if this service is responsive via health checks.
Sources: src/services/worker-service.ts:255-275, scripts/bug-report/cli.ts:137-140
Conclusion
The Automated Bug Reporting System serves as a critical maintenance tool for claude-mem. By combining automated environment collection with AI-driven formatting, it ensures that every reported issue is technically grounded and easy for developers to triage. It effectively bridges the gap between user experience and technical debugging requirements.
Sources: README.md:231-236, CLAUDE.md:12-25