> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monocle.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Monocle Studio

> Local observability for development — traces, logs, exceptions, and queries in your browser

Monocle gives you full observability in production — traces, logs, exceptions, performance. But what about when you're developing locally?

**Monocle Studio** is a lightweight companion built for local development. One command, and you get a focused dashboard showing what's happening inside your app as you code. No setup, no external services — it just works.

<Frame>
  <img src="https://mintcdn.com/adonisjs/9WiU4HuoiNWPH7xk/devtools-screenshot.png?fit=max&auto=format&n=9WiU4HuoiNWPH7xk&q=85&s=e7178e76c3d5c24c664be0f6668d0c4f" alt="Monocle Studio" width="1620" height="1080" data-path="devtools-screenshot.png" />
</Frame>

Think of it as browser DevTools, but for your backend. Every HTTP request, every database query, every log — visible in real-time as you develop.

* See the full trace waterfall for every request
* Track outgoing HTTP calls to external APIs
* Spot slow queries before they become production issues
* Browse structured logs with stack traces and JSON attributes
* Catch exceptions before they ever reach your users
* Connect your AI coding assistant via MCP to query your traces

## How it works

Your app uses the same Monocle agent as in production. In development, the agent automatically sends telemetry to Monocle Studio instead of the cloud. Studio receives it, stores it locally, and serves a dashboard — all on a single port (`localhost:4200`). Data persists between restarts so you can review past sessions.

## Features

<CardGroup cols={2}>
  <Card title="Traces & Requests" icon="route" horizontal>
    HTTP requests with full span waterfall, timing, and attributes
  </Card>

  <Card title="Logs" icon="scroll" horizontal>
    Structured logs with severity filtering, JSON viewer, and stack traces
  </Card>

  <Card title="Exceptions" icon="bug" horizontal>
    Exceptions with stack traces, grouped by type
  </Card>

  <Card title="Database Queries" icon="database" horizontal>
    SQL queries with duration and statement preview
  </Card>

  <Card title="External Calls" icon="globe" horizontal>
    Outgoing HTTP calls to external APIs with domain, status, and duration
  </Card>

  <Card title="Background Jobs" icon="list-check" horizontal>
    Job execution, queue name, duration, and success/failure tracking
  </Card>

  <Card title="CLI Commands" icon="terminal" horizontal>
    Traces for CLI scripts and scheduled tasks with custom spans
  </Card>

  <Card title="MCP Server" icon="robot" horizontal>
    Let Claude Code or Cursor query your local traces and logs
  </Card>

  <Card title="Real-time" icon="bolt" horizontal>
    New data appears instantly — no manual refresh needed
  </Card>
</CardGroup>

## Quick start

<Steps>
  <Step title="Install">
    ```bash theme={"theme":"vesper"}
    npm install -D @monocle.sh/studio @monocle.sh/cli
    ```
  </Step>

  <Step title="That's it">
    Dev mode activates automatically when `NODE_ENV=development` (the default in AdonisJS during `node ace serve`). No extra config needed — the agent detects it and sends data to Monocle Studio instead of the cloud.
  </Step>

  <Step title="Install agent instructions">
    ```bash theme={"theme":"vesper"}
    monocle studio install-agents
    ```

    This appends a managed Monocle Studio block to `AGENTS.md` or `CLAUDE.md` so your agents know about Monocle Studio and how to use it.
  </Step>

  <Step title="Start Monocle Studio">
    ```bash theme={"theme":"vesper"}
    monocle studio dev
    ```

    This starts the Studio server on `http://localhost:4200`.
  </Step>

  <Step title="Start your app">
    ```bash theme={"theme":"vesper"}
    node ace serve --hmr
    ```

    Make some requests, then open `http://localhost:4200` to see your traces, logs, and exceptions.
  </Step>
</Steps>

## CLI options

```bash theme={"theme":"vesper"}
monocle studio dev                     # Start on default port 4200
monocle studio dev --port 3000         # Custom port
monocle studio dev --host localhost    # Bind to localhost only
monocle studio dev --open              # Open browser automatically
monocle studio dev --clean             # Clear all stored data before starting
monocle studio dev --db-path ./my.db   # Custom database path
```

## CLI commands

You can also query Studio data directly from your terminal without opening the browser. Fetch traces, logs, and errors with `monocle studio traces`, `monocle studio logs`, and `monocle studio errors`. See the [CLI reference](/studio/cli) for all options.

## Desktop app

Prefer a native app over a terminal command? Monocle Studio is also available as a [standalone desktop application](/studio/desktop-app) for macOS, Linux, and Windows — with system tray support and auto-updates.

## Data storage

Monocle Studio stores data locally at `~/.config/monocle/studio.db`. Data persists between restarts. Use `monocle studio dev --clean` to start fresh.