bughq

bughq is open source error tracking focused on the loop that matters: capture production errors, group duplicate events into issues, understand their impact, and get the right person working on a fix.

Website | Documentation | Issues

• Captures browser and server errors through a public, revocable project ingest key.
• Groups related events with stable fingerprints that ignore volatile message and stack data.
• Tracks occurrence counts, affected users, environments, releases, and issue status.
• Provides project dashboards, issue detail pages, search, filters, and triage controls.
• Alerts on new issues and regressions by email, Slack, and Discord.
• Supports project members, invitations, key rotation, archiving, and deletion.
• Can connect an issue to a GitHub repository and prepare a guarded AI Autofix pull request.
• Runs as a hosted service or on infrastructure you control.

flowchart LR
  A["Application or browser"] -->|"POST /errors"| B["Ingest authentication and rate limits"]
  B --> C["Fingerprinting"]
  C --> D["Issue and event storage"]
  D --> E["Dashboard and triage"]
  D --> F["Email, Slack, and Discord alerts"]
  E --> G["Optional GitHub Autofix PR"]

Each event belongs to a project. The ingest path validates the project's public key, applies payload and rate limits, computes a fingerprint, and either creates a new issue or adds the event to an existing one. Alerts are delivered outside the critical ingest path so a slow notification provider does not delay error collection.

• Bun 1.3 or newer
• SQLite 3.47.2 or newer for local development
• PostgreSQL for the production configuration

git clone https://github.com/stacksjs/bughq.git
cd bughq
bun install
cp .env.example .env
./buddy key:generate
./buddy migrate
bun run dev

Open http://localhost:3100. The local development command starts the stx views server on port 3100 and the API server on port 3108.

Create an account, add a project, and copy its ingest key from project settings. Local mail uses the configured development mail driver, so invitation and alert output may be written to the application log.

The built-in browser loader captures uncaught errors and unhandled promise rejections:

<script
  src="http://localhost:3108/sdk.js"
  data-key="bughq_your_project_key"
  data-release="checkout@2.14.0"
  data-environment="development"
></script>

You can also capture an error explicitly:

<script>
  bughq.capture(new Error('Checkout failed'), { cartId: 'cart_123' })
</script>

The ingest API accepts JSON at POST /errors and reads the project key from X-BugHQ-Key. See routes/errors.ts for the current payload handling and limits.

Start with .env.example. These are the settings most installations need to review:

Do not commit plaintext environment secrets. The deployment workflow reconstructs .env.keys from GitHub environment secrets and uses the committed encrypted environment files.

Tests live in tests/ and use Bun's test runner. The focused unit suite covers fingerprint stability, ingest authorization, and Autofix output guards.

bughq is built with Stacks, a full-stack TypeScript framework running on Bun. Templates use stx, data access uses the Stacks ORM and query builder, and production data is stored in PostgreSQL.

GitHub Actions provides push-to-deploy with one branch per environment:

The workflow installs locked dependencies, provisions the encrypted environment keys, runs buddy deploy, updates the current release, and applies additive migrations. Deployment configuration is in .github/workflows/deploy.yml and config/cloud.ts.

Issues and focused pull requests are welcome. Before opening a pull request:

bunx --bun pickier .
bun run typecheck
./buddy test

Use conventional commit messages such as fix: guard oversized ingest payloads or feat: add webhook alert channel.

bughq is available under the MIT License.