Architecture Overview

OpenBug CLI exposes two main categories of tools that the backend can call:

Code tools (require code_available: true in openbug.yaml)
- read_file: Read code around a specific line.
- grep_search: Search the codebase for patterns, error strings, or function names.
Log tools (require logs_available: true in openbug.yaml)
- read_logs: Page through logs in 50-line chunks.
- tail_logs: Get the last N lines of logs.
- grep_logs: Find patterns in logs with before/after context.
- get_recent_errors: Extract error-like lines using a comprehensive error regex.

The backend graph chains these tools as needed—for example:

Inspect logs → identify error signature → read the relevant file → search related code → refine diagnosis → propose fix.

Each service has an openbug.yaml with:
- id: project ID used to group services into a cluster.
- window_id: unique per-service identifier used for routing.
- logs_available / code_available: per-service access flags.

Starts a local WebSocket server (default ws://127.0.0.1:4466) in the background.
Accepts register requests from each CLI instance and maintains:
- id (project ID),
- path,
- description, name,
- window_id,
- logs_available, code_available.
Responds to fetch_projects requests from the CLI so it can build an architecture description across all services.
Starts the AI Chat interface, where users can interact.

When you ask a question, the CLI:
- Loads the current service’s openbug.yaml.
- Fetches all services for the same id from the cluster server (if running).
- Generates an architecture string listing each service and what data is available.
The backend receives this architecture and can:
- Choose which service’s logs to analyse.
- Decide which service’s code to inspect.
- Correlate problems across multiple services in the same app.

Documentation Index