agent-observability

Open source agent observability — see what your agents did, why they failed, and what it cost. Runs locally. No cloud required.

Quick Start

One command. No manual config. No copy-paste.

npx agent-obs@latest setup

This auto-detects your AI agent (opencode, Claude Code, Cursor) and configures everything:

• Adds agent-obs to your MCP config
• Adds the self-reporting instruction
• Tells you what to do next

Then restart your agent. Every action will now self-report.

agent-obs dashboard    # http://localhost:9400 — see your sessions appear

What you'll see

After running a task in your agent, the dashboard shows:

• Every tool call with duration and status
• A-F session grade (how efficient was your agent?)
• Cost per session in tokens and dollars
• Full audit trail of what was read, edited, and executed

Manual setup (if setup can't detect your agent)

opencode: Add to opencode.json:

{
  "mcp": {
    "agent-obs": {
      "command": "npx",
      "args": ["-y", "agent-obs@latest", "server"],
      "enabled": true
    }
  }
}

Claude Code: Create .mcp.json:

{
  "mcpServers": {
    "agent-obs": {
      "command": "npx",
      "args": ["-y", "agent-obs@latest", "server"]
    }
  }
}

Cursor: Add to Cursor Settings > MCP:

{
  "mcpServers": {
    "agent-obs": {
      "command": "npx",
      "args": ["-y", "agent-obs@latest", "server"]
    }
  }
}

See Agent-Specific Setup below for detailed per-platform instructions including self-reporting directives.

Note: All data is written to a local SQLite database in ~/.agent-observability/. No data leaves your machine.

Proxy mode (fallback)

For agents that can't self-report, wrap any MCP server and every tool invocation gets traced automatically:

agent-obs proxy --desc "fix login bug" -- npx @modelcontextprotocol/server-filesystem /tmp

Proxy mode captures only MCP tool calls (~30% of typical agent actions). Prefer the setup / MCP server approach above.

Agent-Specific Setup

Claude Code

1. MCP Config — Create .mcp.json in your project root:

{
  "mcpServers": {
    "agent-obs": {
      "command": "npx",
      "args": ["-y", "agent-obs@latest", "server"]
    }
  }
}

2. Self-reporting instruction — Create .claude/instructions.md (or reference the existing SKILL.md under .claude/skills/agent-obs/SKILL.md):

After every tool call, report to agent-obs's log_tool_call.
Start each task with start_session. End with end_session.

3. Verify — Run agent-obs dashboard, open http://localhost:9400, and look for your session after the agent completes a task.

Cursor

1. MCP Config — Add to Cursor's MCP settings (~/.cursor/mcp.json, or Settings → MCP → Add new global MCP server):

{
  "mcpServers": {
    "agent-obs": {
      "command": "npx",
      "args": ["-y", "agent-obs@latest", "server"]
    }
  }
}

2. Self-reporting instruction — Create .cursorrules (or .cursor/rules/agent-obs.md):

After every tool call, you MUST call the agent-obs MCP server's log_tool_call tool.
Include toolName, status (success/error), outputSummary, and durationMs.
Start each session with start_session and end with end_session.

3. Verify — Run agent-obs dashboard, open http://localhost:9400, and look for your session after the agent completes a task.

Architecture

                   ┌──────────────────────────┐
                   │   agent-obs server       │
                   │    (self-reporting)      │
                   │          

... [View full README on GitHub](https://github.com/kryptosai/agent-observability#readme)