Skip to content
Blopblop docs

Introduction

Blop is a local-first OpenTelemetry observability layer that coding agents can call while they work: observe the software you are changing, investigate runtime evidence, and verify a fix.

The local collector is a tool, not another agent. Your coding agent stays in control and invokes blop as a normal command-line tool. It has no chat, model loop, or autonomous action. When a concrete user journey needs active verification, the supported browser runner uses a bounded model loop and explicit Browser Harness tools.

Terminal window
$ blop monitor start                 # terminal 1: receive OTLP traces + logs
$ OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:27686 pnpm test   # terminal 2
$ blop status --json                 # cheap, deterministic health check
$ blop audit --since 15m --json      # findings with trace IDs attached

Highlights

Section titled “Highlights”
  • OpenTelemetry in, useful evidence out. Standard OTLP/HTTP traces and logs, JSON or protobuf. No Blop-specific application SDK.
  • Local first. One process, a SQLite store under your platform data directory, and no account. Point any existing OTel exporter at 127.0.0.1 and query.
  • Machine-readable by contract. Every query has stable --json output (schema blop.cli/v1), bounded result sizes, documented exit codes, and no interactive prompts.
  • Progressive disclosure. Start with a compact summary, then drill into one service, trace, span, or log set. Nothing dumps an entire telemetry database into your prompt.
  • Evidence over opinion. Audits cite trace IDs, span IDs, timestamps, durations, status, and attributes. Blop distinguishes observed facts from derived findings and never claims causality from correlation alone.
  • Safe in a coding loop. Queries are read-only. The collector binds to loopback by default, caps request bodies and result sizes, and never executes application code.
  • Active evidence when needed. Authored .blop.ts checks verify important browser flows locally, in CI, against staging, or against a deliberately selected production target.

Installation

Section titled “Installation”

Install blop into your project (or globally):

Terminal window
$ npm install @blopai/cli
# or
$ pnpm add @blopai/cli
# or
$ bun add @blopai/cli

No API keys, no account, and no browsers to provision for the monitoring workflow. Then start with first steps to collect your first trace.

Observe → investigate → verify

Section titled “Observe → investigate → verify”
observe                              investigate                         verify
   |                                     |                                  |
OTLP -> local SQLite -> status/traces/logs/audit -> reproduce with OTLP again
   |                                     |                                  |
   +-- authored browser check -> run/failure/artifact evidence -> rerun flow
                                 (separate control-plane store)
  1. blop monitor start runs the collector in the foreground and prints its OTLP endpoints and database path.
  2. Run the instrumented app or test suite with OTEL_EXPORTER_OTLP_ENDPOINT pointing at the collector.
  3. Ask for a bounded snapshot: blop status, blop services, blop traces, blop trace <id>, blop logs.
  4. Run blop audit for deterministic findings with evidence attached.
  5. Make the change, reproduce, and re-run blop audit --fail-on regression before declaring success.
  6. When the user flow itself needs proof, run an authored check explicitly: blop test tests/checkout.blop.ts --base-url <target>.

Local telemetry and browser-run evidence complement each other, but they do not share storage. Traces, spans, logs, and services remain in local SQLite. Runs, failures, projects, and insights are ingested separately into the control plane’s Postgres store. See the full workflow guide.

JSON output contract

Section titled “JSON output contract”

--json writes exactly one JSON document to stdout; diagnostics go to stderr. All commands share this envelope:

{
  "schema_version": "blop.cli/v1",
  "command": "traces",
  "generated_at": "2026-08-29T12:00:00.000Z",
  "data": [],
  "page": { "limit": 20, "next_cursor": null },
  "warnings": []
}

Rules: snake_case keys, ISO 8601 UTC timestamps, deterministic ordering, absent optional values are null, and breaking changes require a new schema_version. See the CLI reference for every command, flag, and exit code.

Exit codes

Section titled “Exit codes”
Code Meaning
0 Command completed; audit found nothing at or above the configured failure threshold.
1 Audit findings met --fail-on, or an active browser check failed.
2 Invalid arguments or configuration.
3 Collector unavailable.
4 Store/query failure.
5 Timeout.

Configuration

Section titled “Configuration”

Monitoring settings currently resolve in this order: CLI flag, environment variable, built-in default. The initial environment variables are BLOP_MONITOR_HOST, BLOP_MONITOR_PORT, BLOP_MONITOR_DB_PATH, BLOP_MONITOR_RETENTION_HOURS, and BLOP_MONITOR_RETENTION_INTERVAL_SECONDS. Project and user configuration layers are planned but are not loaded by the monitor yet. See the environment reference for the full list.

Active browser checks

Section titled “Active browser checks”

The intent-based runner (blop test, run, watch, list, init, skills) is the active verification path. Checks are code in your repository; Blop does not silently create a suite. The default quickstart remains monitoring-first because passive local evidence is the lowest-friction starting point.

Use local, preview, or staging targets by default. A production target is supported only when selected deliberately, with synthetic identities, least privilege, reversible actions, cleanup, rate limits, and artifact review. Read Production-target browser checks before enabling one.

Learn more

Section titled “Learn more”