Reference
Open source tools
Libraries already wired into the product pipeline, including the in-repo Mastra-compatible runtime (src/lib/agents/mastra-runtime, package name @mastra/core). Agent.generate throws; model HTTP is the ChangeGraph provider router. This is not the GitHub / Sentry / Vercel catalog. Scores stay correlation on a 0–100 scale. Explain and investigate still require a configured LLM provider (not_configuredwhen unset). See Where the running app reads data.
| Tool | What we use it for | Upstream | Pipeline |
|---|---|---|---|
| Headroom | Optional post-pack compress after redaction. The packer works without it. If the proxy is down, ChangeGraph falls back to the packed prompt. | github.com/headroomlabs-ai/headroom | After redact + pack, before the model. HEADROOM_URL / HEADROOM_API_KEY / HEADROOM_TIMEOUT_MS. Packer + explain/investigate run without Headroom. |
| Mastra | In-repo Mastra-compatible runtime (workspace package @mastra/core at src/lib/agents/mastra-runtime). Workflows explain_incident and investigate_incident, plus gated propose_incident, critic_incident, and durable investigate resume. Agent.generate throws; model HTTP is the ChangeGraph provider router (src/lib/llm/providers.ts). AgentConfig.model is a string or function. Never mutates ranks. Provider required (not_configured when unset). | mastra.ai | After packed context, before UI/MCP. Not the npm @mastra/core package. |
| Drizzle | Typed ORM and migrations for the tenant-scoped change graph. | orm.drizzle.team | Schema and migrations (src/lib/db, drizzle/). pnpm db:push and pnpm seed write Postgres. |
| Zod | Runtime schemas for evidence, packed context, investigation results, and input. | zod.dev | Gates and adapters, including packedContextSchema. |
| Vitest | Unit tests and API-level e2e (pnpm test, pnpm test:e2e). | vitest.dev | CI quality gate. No Playwright in MVP. |
| Biome | Lint and format (pnpm lint, pnpm format). | biomejs.dev | Repo-wide check in pnpm ci. |
| GitHub Actions | Pull request and main CI: lint, typecheck, Vitest, security smoke, and e2e against a Postgres service container. | docs.github.com/actions | Quality gate before merge (.github/workflows/ci.yml). |
| Next.js | App Router for the product app and this docs site. | nextjs.org | Root src/app and apps/docs. |
| Tailwind CSS | Utility styling for product and docs (dark-first), with shadcn-style primitives (buttons, inputs, panels) and no shadcn package. | tailwindcss.com | Global CSS and component classes under src/components and apps/docs. |
| TypeScript | Strict typing across app, agents, and docs. | typescriptlang.org | Whole repo (pnpm typecheck). |
| React | UI for product and docs. | react.dev | src/app, src/components, apps/docs. |
| pnpm | Workspace package manager (pinned packageManager). | pnpm.io | Install, scripts, apps/* workspace. |
| postgres.js | Postgres driver used by Drizzle. | github.com/porsager/postgres | DATABASE_URL connections. |
| MCP TypeScript SDK | Read-only ChangeGraph MCP server (stdio). Gated MCP client (FEATURE_MCP_CLIENT, default off) is a read adapter and fails closed as not_configured without a registry. The full multi-server registry is deferred. | github.com/modelcontextprotocol/typescript-sdk | Server: src/mcp (pnpm mcp). Client: src/lib/mcp-client. |
Headroom
Headroom is an optional post-pack compressor. ChangeGraph redacts secrets, packs a budgeted compact digest with frozen ranks, then may POST that already-redacted text to a Headroom proxy. The packer, explain_incident, and investigate_incident all work without Headroom. Investigation still needs an LLM provider.
- HEADROOM_URL
- Proxy base URL (alias
HEADROOM_BASE_URL). Unset means packer only. - HEADROOM_API_KEY
- Optional bearer for the proxy.
- HEADROOM_TIMEOUT_MS
- Default 2500. On timeout or 5xx, fallback uses the packed prompt.
Upstream: headroomlabs-ai/headroom. Proxy notes: Headroom docs. Operators who want extra compression run headroom proxy and set HEADROOM_URL. Domain packages do not import Headroom.
Engineering SoT: docs/INTEGRATIONS_OSS.md · packing: Agent context.