AGENTS.md · hyperdxio/hyperdx

Sections

1. What is HyperDX?
2. Architecture (WHAT)
3. Development Setup (HOW)
4. Working on the Codebase (HOW)
5. Key Principles
6. Communication style
7. Running Tests
8. Important Context
9. PR Hygiene for Agent-Generated Code
10. Responding to review feedback
11. GitHub Action Workflow (when invoked via @claude)
12. Git Commits
13. Merge Conflict Resolution
14. Cursor Cloud specific instructions

First lines (shown under the repo's MIT license)

# HyperDX Development Guide

## What is HyperDX?

HyperDX is an observability platform that helps engineers search, visualize, and
monitor logs, metrics, traces, and session replays. It's built on ClickHouse for
blazing-fast queries and supports OpenTelemetry natively.

**Core value**: Unified observability with ClickHouse performance,
schema-agnostic design, and correlation across all telemetry types in one place.

## Architecture (WHAT)

This is a **monorepo** with six packages:

- `packages/app` - Next.js frontend (TypeScript, Mantine UI, TanStack Query)
- `packages/api` - Express backend (Node.js 22+, MongoDB for metadata,
  ClickHouse for telemetry). Also hosts the **MCP server**, **External API v2**,
  and **OpAMP server** as sub-applications.
- `packages/common-utils` - Shared TypeScript utilities for query parsing and
  validation
- `packages/cli` - Terminal CLI and interactive TUI (`hdx`) for searching,
  tailing, and inspecting logs and traces (Ink/React). Has its own
  [`AGENTS.md`](packages/cli/AGENTS.md) with detailed architecture and
  keybindings.
- `packages/otel-collector` - Custom-built OpenTelemetry Collector (Go, OCB).
  See its [`README.md`](packages/otel-collector/README.md) for architecture,
  included components, and upgrade procedures.
- `packages/hdx-eval` - AI eval framework for benchmarking MCP servers against
  observability scenarios. Generates deterministic synthetic telemetry, spawns
  agents, and grades with programmatic checks + LLM-as-judge. See its
  [`README.md`](packages/hdx-eval/README.md) for setup and usage, and
  [`agent_docs/evals.md`](agent_docs/evals.md) for the dual-slot A/B
  comparison workflow.

**Data flow**: Apps → OpenTelemetry Collector → ClickHouse (telemetry data) /
MongoDB (configuration/metadata)

## Development Setup (HOW)

```bash
yarn setup          # Install dependencies
yarn dev            # Start full stack with worktree-isolated ports
```

The project uses **Yarn 4.13.0** workspaces. Docker Compose manages ClickHouse,
MongoDB, and the OTel Collector.

**This repo is multi-agent friendly.** `yarn dev`, `make dev-int`, and
`make dev-e2e` all use slot-based port isolation so multiple worktrees can run
dev servers, integration tests, and E2E tests simultaneously without conflicts.
A dev portal at http://localhost:9900 auto-starts and shows all running stacks.
See [`agent_docs/development.md`](agent_docs/development.md) for the full
multi-worktree setup, port allocation tables, and available commands.

## Working on the Codebase (HOW)

**Before starting a task**, read relevant documentation from the `agent_docs/`
directory:

- `agent_docs/architecture.md` - Detailed architecture patterns and data models
- `agent_docs/tech_stack.md` - Technology stack details and component patterns
- `agent_docs/development.md` - Development workflows, testing, and common tasks
- `agent_docs/code_style.md` - Code patterns and best practices. **Read this
  before writing or planning any `packages/app` UI change, and before adding a
  type, Zod schema, helper, or component in any package**, not just while
  typing code. It carries required patterns that are invisible from the
  surrounding file (sentence-case UI text, mandated Button/ActionIcon variants,
  `useConfirm` for confirmation dialogs, `EmptyState`, and where shared code
  already lives), so copying the conventions of the component you are editing is
  not sufficient.
- `agent_docs/naming_objects.md` - How users name and rename objects
  (`InlineNameInput`). Read before adding or changing any name field
- `agent_docs/observability.md` - Instrumentation standards (tracing, metrics,
  context) and the shared helpers (read when adding or changing a feature)

**Package-specific guides** (read when working on that package):

- `packages/cli/AGENTS.md` - CLI/TUI architecture, keybindings, web frontend
  alignment, key patterns
- `packages/otel-collector/README.md` - Collector build process, included
  components, upgrade procedures, adding custom components
- `MCP.md` - MCP server setup and available tools (user-facing)

**After finishing all code edits**, run `yarn lint:fix` to auto-fix formatting
and lint issues across all packages. Pre-commit hooks handle this when
committing, but if you finish edits without committing, run `yarn lint:fix`
before stopping.

## Key Principles

1. **Multi-tenancy**: All data is scoped to `Team` - ensure proper filtering
2. **Type safety**: Use TypeScript strictly; Zod schemas for validation
3. **Existing patterns**: Follow established patterns in the codebase - explore
   similar files before implementing. **Before you define a type, Zod schema,
   helper, or component, grep for one that already exists.** Search for the
   operation it performs (`bucket`, `valid.*url`, `split.*trim`) - not the name
   you were about to give it, because names differ. Look in
   `packages/common-utils/src/` first, then the package you are editing. If you
   find it, import or alias it; do not add a second definition. See
   `agent_docs/code_style.md` → "Before you add a type, schema, or helper"
4. **Component size**: Keep files under 300 lines; break down large components
5. **UI Components**: Use custom Button/ActionIcon variants (`primary`,
   `secondary`, `danger`), `useConfirm` for "are you sure?" dialogs rather than
   a hand-rolled `Modal`, and sentence case for all user-facing text - see
   `agent_docs/code_style.md` for required patterns
6. **Testing**: Tests live in `__tests__/` directories; use Jest for
   unit/integration tests
7. **Observability**: This is an observability product - instrument new code as
   you write it. Every team-scoped operation must carry team/user context
   (`setBusinessContext`), and countable log events should also emit a metric.
   For our own instrumentation we favor wide events — enrich the unit-of-work
   span with rich, high-cardinality attributes and keep only span _names_ and
   _metric_ attributes low-cardinality — while metrics stay first-class
   (counters/histograms feed alerts and SLOs, and many deployments rely on
   them). Use the shared helpers in
   `packages/api/src/utils/instrumentation.ts`. See
   [`agent_docs/observability.md`](agent_docs/observability.md).
8. **Communication**: Be concise and straightforward - in chat, in code
   comments, in commits, and in PR descriptions. See
   [Communication style](#communication-style) below.

## Communication style

Write plainly. This applies to everything you produce: chat replies, code
comments, commit messages, PR descriptions, and docs.

- **Lead with the answer.** State the result first, then the detail that
  supports it. No preamble, no restating the request back at the reader.
- **Cut filler.** Drop hedges ("it seems like", "essentially", "basically"),
  intensifiers ("very", "extremely", "quite"), and throat-clearing ("in order
  to" → "to"). Prefer short concrete words over long abstract ones.
- **Keep summaries short.** A handful of bullets or a short paragraph. Don't
  recap what the diff already shows, and don't restate one point in three
  different phrasings.
- **No self-narration.** Skip the play-by-play of your own process, the options
  you rejected, and the victory lap ("Perfect!", "All done!"). Report what
  changed and what is still broken.
- **Comments explain _why_, not _what_.** The code already says what it does.
  Omit the comment when the line is self-evident; write one when a choice needs
  justification — a workaround, a non-obvious constraint, a ClickHouse quirk. No
  banner comments, no ASCII section dividers, and no `// increment the counter`
  restatements. This applies to test bodies too: don't narrate each step of a
  test that already reads top-to-bottom.
- **Say it straight.** If something is broken, unverified, or skipped, say so in
  one sentence. Don't soften bad news and don't oversell partial work.

## Running Tests

Each package has different test commands available:

**packages/app** (unit tests only):

```bash
cd packages/app
yarn ci:unit           # Run unit tests
yarn dev:unit          # Watch mode for unit tests
```

**packages/api** (unit and integration tests):