GitHub - flashus/detrix: Observe any line of running code — no restarts, no code changes, production-safe

Give your AI agent eyes inside any running program. Watch any variable at any line — agent sets an observation point in seconds, zero code changes during debugging Local or cloud — same workflow for Docker containers and remote hosts Python, Go, Rust — observation points capture values without pausing, without restarting Built for agents — observe, query, manage observations via natural language; Claude Code, Cursor, Windsurf

See It in Action

1-minute demo: A Go service in Docker starts reporting wrong numbers. Nothing in the client code changed. Claude watches it live and finds the cause.

Here's what the session looks like:

You:    "The order-service in Docker is reporting wildly inflated revenue.
         Daily total is in the thousands when transactions should be $20-200."

Agent:  → reads the source, spots dead unit-conversion code
        → wakes the service via Detrix
        → observes txn.Amount, txn.Unit, total
          (no line number — find_variable locates it in the running container)

        "Found it. The pricing API changed what it's returning.

        txn.Amount = 8957, txn.Unit = "cents" → should be $89.57, summed as $8957

        In calculateRevenue, the unit field is fetched and discarded:

        unit := txn.Unit
        _ = unit          // ← conversion was intended, never implemented
        total += amount   // ← adds cents as if they were dollars

        This didn't matter before. It matters now."

        → fixed the client code
        → reported the API contract change upstream

No code was modified to instrument. No restarts. The old workflow — add a log line, rebuild, redeploy, wait for the bug to reproduce — replaced by watching it live.

You don't need to know the line number either — describe the behavior and the agent finds where to look.

Why Detrix?

You hit a bug. The old workflow: add a print, restart, reproduce, remove the print, repeat. If it's in production, redeploy. If it's in a Docker container, get into the container. If it's intermittent, wait.

With Detrix, you just ask the agent. It finds the right line, plants an observation point, and tells you what it sees — live, nothing restarting.

That bug that cost you hours last week — redeploy after redeploy, still can't reproduce — your agent can investigate it in minutes, while your app keeps running.

¹ Embed detrix.init() once for zero restarts forever. Or restart once to attach the debugger (--debugpy, dlv, lldb-dap) — from that point on, the agent adds and removes observations without any further restarts.

Quick Start

Try it in 2 minutes. Your agent handles everything after step 3.

1. Install Detrix

macOS (Homebrew):

brew install flashus/tap/detrix

macOS / Linux (shell script):

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/flashus/detrix/releases/latest/download/detrix-installer.sh | sh

Windows (PowerShell):

irm https://github.com/flashus/detrix/releases/latest/download/detrix-installer.ps1 | iex

Docker (linux/amd64, linux/arm64):

docker pull ghcr.io/flashus/detrix:latest

Build from source:

cargo install --git https://github.com/flashus/detrix detrix

Then initialise (creates config and sets up local storage):

2. Add to your app

One line — the debugger sleeps until your agent needs it, zero overhead when idle:

import detrix
detrix.init(name="my-app")

Go and Rust work the same way — see App Integration.

3. Connect your agent

Claude Code:

claude mcp add --scope user detrix -- detrix mcp

Cursor / Windsurf — add to .mcp.json in your project root:

{
  "mcpServers": {
    "detrix": {
      "command": "detrix",
      "args": ["mcp"]
    }
  }
}

For cloud setup and other editors, see the setup guide.

That's it. Ask your agent to observe any line in your running app — no restarts, nothing ships to prod.

Alternative: connect without embedding

Don't want to add a dependency? Start your app directly under a debugger instead:

# Python
python -m debugpy --listen 127.0.0.1:5678 app.py

# Go
dlv debug --headless --listen=127.0.0.1:5678 --api-version=2 main.go

# Rust
lldb-dap --port 5678

Listens on 127.0.0.1 — local only. See the language setup guide for remote and Docker.

How It Works

Detrix is a daemon that runs locally or in the cloud and connects your AI agent to any running process via 29 MCP tools. Under the hood, it talks to your app's debugger via the Debug Adapter Protocol (DAP). It sets logpoints — breakpoints that evaluate an expression and log the result instead of pausing. Your application runs at full speed; Detrix captures the values.

  AI Agent                 Detrix Daemon              Debugger (DAP)         Your App
  (Claude Code, Cursor,    (local or Docker/cloud)    debugpy / dlv /        (Python/Go/Rust,
    Windsurf, local)                                  lldb-dap               local/cloud)
      │                         │                          │                      │
      │── "observe line 127" ──▶│                          │                      │
      │                         │── set logpoint ─────────▶│                      │
      │                         │                          │── captures value ───▶│
      │                         │◀────────────── captured values ─────────────────│
      │◀── structured events ───│                          │                      │
      │                         │                          │                      │
      │         App never pauses. No code changes. No restarts.                   │

The daemon runs locally or alongside your service in Docker — same protocol either way. In cloud mode, source files are fetched automatically so the agent can find the right lines without them on your machine. See the Installation Guide for cloud setup.

App Integration

import detrix
detrix.init(name="my-app")   # That's it. Agent controls the rest.

Production pattern: Build one service instance with debug symbols and a Detrix client. Route suspect traffic to it via Kafka, a sidecar, or your load balancer. The rest of your fleet runs unaffected — full-speed, no instrumentation overhead. You get deep observability on one instance without touching production.

See the Clients Manual for full documentation.

Features

No code changes. The agent instruments your running code via observation points — nothing gets committed, nothing ships to prod.

No pausing. Observation points evaluate expressions at full execution speed, with no breakpoint-style halting. For high-frequency code paths, use sample or throttle modes to control event volume.

No forgotten cleanup. Metrics expire automatically via TTL, or remove everything with one command.

Documentation

Contributing

cargo fmt --all && cargo clippy --all -- -D warnings && cargo test --all

1. Fork the repository
2. Create a feature branch
3. Run the checks above
4. Submit a Pull Request

License

MIT License — see LICENSE.

Found a bug? Open an issue. Found in minutes what took you days? Tell us in Discussions.