DevTools Dashboard

Debug and trace your agents in real time

A local HTTP + WebSocket dashboard that shows every tool call, LLM token, agent decision, and latency — live, in your browser. No external service, no config files. Three lines to start.

Live Tracing

Every tool call, token, and agent step visible in real time

Session Grouping

Group related runs into sessions for full conversation context

ReplayDebugger

Replay past runs with modified inputs and diff the output

Remote Mode

View production traces from your local machine

Multiple APIs

withTrace(), @Trace() decorator, manual trace.start/end

Nesting

Workflows → agents → tools, all rendered as a tree

Installation

npm install @orka-js/devtools

Start in 3 lines

The browser opens automatically. The dashboard is ready. Start tracing.

server.ts

import { devtools } from '@orka-js/devtools'
 
await devtools({ port: 3001 })
// Dashboard opens at http://localhost:3001

Wrap your agent

withTrace wraps any function. Every call to tracedRun() appears in the dashboard.

agent.ts

import { devtools, withTrace } from '@orka-js/devtools'
import { ReActAgent } from '@orka-js/agent'
import { OpenAIAdapter } from '@orka-js/openai'
 
await devtools({ port: 3001 })
 
const agent = new ReActAgent({
  goal: 'Help customers with their orders',
  tools: [getOrder, cancelOrder, refundOrder],
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
})
 
const tracedRun = withTrace(agent.run.bind(agent), {
  name: 'customer-support',
  type: 'agent',
})
 
// Every call appears in the dashboard
await tracedRun('What is the status of order #1234?')

Inline tracing with trace.wrap

agent.ts

import { trace } from '@orka-js/devtools'
 
const result = await trace.wrap('agent', 'customer-support', () =>
  agent.run('Cancel my order #1234')
)

Class decorator

agent.ts

import { Trace } from '@orka-js/devtools'
import { ReActAgent } from '@orka-js/agent'
 
class CustomerSupportAgent extends ReActAgent {
  @Trace({ type: 'agent', name: 'customer-support' })
  async run(input: string) {
    return super.run(input)
  }
}

Sessions

Group related runs — e.g. all turns in a single user conversation.

conversation.ts

import { trace } from '@orka-js/devtools'
 
const sessionId = trace.session('conversation-user-42')
 
await trace.wrap('agent', 'turn-1', () => agent.run('Hello'))
await trace.wrap('agent', 'turn-2', () => agent.run('Cancel my order #1234'))
await trace.wrap('agent', 'turn-3', () => agent.run('What is my refund status?'))
 
trace.endSession(sessionId)
// All 3 runs are grouped under "conversation-user-42" in the dashboard

ReplayDebugger

Replay a past run with a modified prompt and compare the output diff. No need to re-run the whole system.

replay.ts

import { devtools, createReplayDebugger } from '@orka-js/devtools'
 
const { tracer } = await devtools({ port: 3001 })
const debugger = createReplayDebugger(tracer)
 
// Replay a past run with a modified prompt
const comparison = await debugger.replayRun({
  runId: 'run-abc123',
  sessionId: 'session-xyz',
  modifyInput: (input) => ({
    ...input,
    prompt: 'Updated: always verify order exists before cancellation.',
  }),
})
 
console.log(comparison.diff)
// { original: '...', replayed: '...', changed: true }

Remote Mode (Production)

Send traces from your production agent to a collector, then view them on your local machine.

devtools.ts

// ── Production agent: send traces to collector ──
await devtools({
  source: 'remote',
  mode: 'agent',
  remote: {
    endpoint: 'https://traces.mycompany.com',
    apiKey: process.env.COLLECTOR_API_KEY,
    projectId: 'my-ai-app',
    environment: 'production',
    sampling: 0.1, // trace 10% of requests
  },
})
 
// ── Your machine: view production traces locally ──
await devtools({
  source: 'remote',
  mode: 'viewer',
  remote: {
    endpoint: 'https://traces.mycompany.com',
    apiKey: process.env.COLLECTOR_API_KEY,
    projectId: 'my-ai-app',
    filters: { environment: 'production', timeRange: 'last-1h' },
  },
  port: 3001,
})

Configuration

Option	Type	Default	Description
port	number	3001	Dashboard HTTP port
host	string	'localhost'	Bind address
open	boolean	true	Auto-open browser on start
maxTraces	number	1000	Max traces kept in memory
retentionMs	number	86400000	Trace retention (24h default)
source	'local' \| 'remote'	'local'	Local dashboard or remote collector
mode	'agent' \| 'viewer'	'agent'	Remote: send or receive traces
verbose	boolean	false	Log startup and errors