Documentation

Overview

Oculo is a local-first, high-performance observability platform designed specifically for AI agent workflows. It captures structured traces, memory mutations, and token usage data in real-time.

Unlike cloud-based alternatives, Oculo runs entirely on your machine. Data never leaves your environment unless you choose to export it.

Installation

Install the Python SDK via pip:

pip install oculo

Or install the Go daemon directly:

curl -fsSL https://raw.githubusercontent.com/Mr-Dark-debug/Oculo/main/install.sh | bash

Quick Start

Instrumenting your agent takes less than five lines of code:

from oculo import OculoTracer

tracer = OculoTracer(agent_name="my-agent")

with tracer.trace() as t:
    with t.span("llm_call") as s:
        s.set_prompt("What is AI?")
        response = call_llm("What is AI?")
        s.set_completion(response)

Traces & Spans

A trace represents one complete execution of your agent. Within a trace, you create spans that represent individual operations (LLM calls, tool invocations, memory reads/writes).

Spans form a tree structure, giving you a hierarchical view of your agent's execution path.

Memory Tracking

Oculo tracks the state of your agent's memory at each span boundary. It produces Git-like diffs showing exactly what changed between steps.

# Track memory state within a span
with t.span("planning") as s:
    s.set_memory_before(agent.memory)
    agent.plan()
    s.set_memory_after(agent.memory)
# Oculo computes the diff automatically

Token Analysis

Each span automatically collects prompt_tokens, completion_tokens, and total_tokens. Oculo provides per-model cost attribution and Z-score-based anomaly detection for identifying token hotspots.

Python SDK

OculoTracer

The main entry point. Create one per agent.

tracer = OculoTracer(
    agent_name="my-agent",
    host="127.0.0.1",    # Daemon address
    port=7600             # Daemon port
)

Trace Context

Use tracer.trace() as a context manager. Spans are created inside traces.

CLI Commands

oculo start          # Start the daemon
oculo stop           # Stop the daemon
oculo status         # Check daemon health
oculo tui            # Launch the TUI visualizer
oculo export [id]    # Export a trace as JSON

TUI Visualizer

The TUI provides a real-time, terminal-based interface for exploring traces. Navigate through spans with keyboard shortcuts, inspect memory diffs side-by-side, and analyze token usage with visual bar charts.

Configuration

Oculo reads from ~/.oculo/config.toml:

[daemon]
port = 7600
data_dir = "~/.oculo/data"
batch_size = 100
flush_interval = "500ms"

[analysis]
anomaly_threshold = 2.0
memory_growth_window = 50