OpenCode Console

OpenCode Console is a high-performance, web-based observability and management interface designed specifically for the OpenCode AI coding agent. It transforms the terminal-native experience into a rich visual dashboard, providing real-time monitoring of agent "thought" processes, interactive file diffing, deep inspection of MCP (Model Context Protocol) tool calls, and multi-session management.

Why OpenCode Console?

While OpenCode's terminal interface is powerful for developers comfortable with CLI tools, many scenarios benefit from a visual dashboard:

• Team Collaboration: Share agent activity with team members who aren't running OpenCode locally
• Debugging: Visual inspection of tool calls, payloads, and execution flow
• Auditing: Review historical sessions and understand what the agent did and why
• Control: Approve or reject agent actions through a user-friendly interface
• Monitoring: Watch multiple sessions or long-running autonomous tasks

Core Features

Real-Time Event Stream

Monitor agent activity as it happens with a categorized, searchable event log:

• Event Categories: User messages, Assistant responses, System events, Context updates, Tool calls
• Search & Filter: Find specific events across thousands of log entries
• Auto-Scroll: Automatic scrolling with manual override and "jump to bottom" functionality
• Timestamps: Precise timing for debugging performance issues

Hierarchical Step Drilling

Visualize the agent's reasoning process with expandable task hierarchies:

• Nested Views: See sub-agent tasks and their parent-child relationships
• Execution Timing: Understand how long each step takes
• Token Usage: Track token consumption per step for cost optimization
• Collapsible Nodes: Focus on relevant parts of complex workflows

Interactive Diff Viewer

Review code changes with powerful diff visualization:

• View Modes: Side-by-side and unified diff views
• Syntax Highlighting: Support for 50+ programming languages via Monaco or Shiki
• File Tree: Visual representation of modified files showing "Dirty" vs "Committed" states
• Inline Navigation: Click to jump to specific changes

MCP Tool Inspector

Debug and understand tool interactions with visual inspection:

• JSON Payloads: Formatted view of tool call parameters and results
• Status Indicators: Clear success, failure, or timeout states
• Linked Results: Direct connection from tool calls to resulting file changes or terminal output
• Timing Data: Execution duration for each tool call

Multi-Session Management

Organize and navigate between coding sessions:

• Session Sidebar: Quick switching between active and historical sessions
• Metadata Editing: Rename, tag, and archive sessions for organization
• Checkpoints: Visual markers for rolling back or branching session state
• Persistence: All sessions stored locally in SQLite

Action Approval Bridge

Maintain control over agent actions with approval workflows:

• Intercept Mode: UI buttons to "Approve", "Edit", or "Reject" agent proposals
• Feedback Loop: Provide natural language corrections directly to the agent
• Batch Approval: Review and approve multiple file changes at once
• Audit Trail: Record of all approval decisions

Model Configuration Dashboard

Fine-tune agent behavior without editing configuration files:

• Provider Switching: Real-time switching between OpenAI, Anthropic, Together AI, and more
• Parameter Tuning: Adjust temperature and other model parameters via sliders
• Cost Tracking: Monitor token usage and estimated costs per session
• Token Limits: Set alerts when approaching usage limits

Technology Stack

Frontend

Backend

Prerequisites

Before installing OpenCode Console, ensure you have:

• Bun runtime (v1.1 or higher) - Install Bun
• OpenCode installation - The console connects to a running OpenCode instance
• API Keys - OPENAI_API_KEY or relevant model provider keys
• Operating System - Linux or macOS (Windows via WSL is experimental)

Installation

Quick Start

The fastest way to get started is using the initialization script:

# Clone the repository
git clone https://github.com/NocturnLabs/opencode-console.git
cd opencode-console

# Run the initialization script
./init.sh

# Open in browser
open http://localhost:3000

The init script will:

1. Install all dependencies via Bun
2. Set up the SQLite database with Drizzle
3. Start the Next.js development server
4. Launch the OpenCode bridge (if configured)

Manual Installation

For more control over the installation process:

# Clone the repository
git clone https://github.com/NocturnLabs/opencode-console.git
cd opencode-console

# Navigate to the console app
cd apps/console

# Install dependencies
bun install

# Set up the database
bun run db:push

# Start the development server
bun run dev

Environment Configuration

Create a .env.local file in the apps/console directory:

# Database
DATABASE_URL="file:./sqlite.db"

# OpenCode Bridge
OPENCODE_BRIDGE_PORT=3001
OPENCODE_SOCKET_URL="ws://localhost:3001"

# Model Configuration (optional)
OPENAI_API_KEY="your-api-key"
ANTHROPIC_API_KEY="your-api-key"

Project Structure

opencode-console/
├── apps/
│   └── console/              # Next.js frontend application
│       ├── src/
│       │   ├── app/          # Next.js App Router pages
│       │   │   ├── globals.css
│       │   │   ├── layout.tsx
│       │   │   └── page.tsx
│       │   └── lib/          # Shared utilities
│       │       ├── db.ts     # Database connection
│       │       └── schema.ts # Drizzle ORM schema
│       ├── drizzle.config.ts # Drizzle configuration
│       ├── next.config.js    # Next.js configuration
│       ├── tailwind.config.js
│       └── package.json
├── packages/
│   └── bridge/               # OpenCode connector (planned)
├── scripts/
│   ├── run-autonomous.sh     # Autonomous mode launcher
│   └── security-allowlist.json
├── feature_list.json         # Feature tracking and test cases
├── app_spec.md               # Project specification
└── init.sh                   # Quick start script

Database Schema

OpenCode Console uses SQLite with Drizzle ORM for local persistence. The schema supports session tracking, event logging, and file change management.

Sessions Table

Stores coding session metadata:

export const sessions = sqliteTable('sessions', {
  id: text('id').primaryKey(),
  name: text('name').notNull(),
  status: text('status').notNull(), // 'active', 'completed', 'failed'
  createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
  modelConfig: text('model_config', { mode: 'json' }).$type<{
    provider: string;
    model: string;
    temperature: number;
  }>(),
});

Events Table

Logs all agent activity:

export const events = sqliteTable('events', {
  id: text('id').primaryKey(),
  sessionId: text('session_id').references(() => sessions.id).notNull(),
  type: text('type').notNull(), // 'user', 'assistant', 'system', 'context', 'tool'
  content: text('content').notNull(),
  payload: text('payload', { mode: 'json' }),
  timestamp: integer('timestamp', { mode: 'timestamp' }).notNull(),
});

File Changes Table

Tracks file modifications by the agent:

export const fileChanges = sqliteTable('file_changes', {
  id: text('id').primaryKey(),
  sessionId: text('session_id').references(() => sessions.id).notNull(),
  filePath: text('file_path').notNull(),
  diff: text('diff').notNull(),
  status: text('status').notNull(), // 'pending', 'applied', 'rejected'
});

MCP Calls Table

Records Model Context Protocol tool invocations:

export const mcpCalls = sqliteTable('mcp_calls', {
  id: text('id').primaryKey(),
  eventId: text('event_id').references(() => events.id).notNull(),
  serverName: text('server_name').notNull(),
  method: text('method').notNull(),
  params: text('params', { mode: 'json' }),
  result: text('result', { mode: 'json' }),
  durationMs: integer('duration_ms').notNull(),
});

API Endpoints

Session Management

Agent Control

Configuration

Development

Available Scripts

# Start development server with hot reload
bun run dev

# Build for production
bun run build

# Start production server
bun run start

# Run ESLint
bun run lint

# Database commands
bun run db:generate  # Generate migration files
bun run db:push      # Push schema changes to database
bun run db:migrate   # Run migrations
bun run db:studio    # Open Drizzle Studio GUI

Database Management

Drizzle Studio provides a visual interface for database inspection:

cd apps/console
bun run db:studio

This opens a browser-based GUI for viewing and editing database contents.

Adding New Components

The project uses Shadcn/UI for components. To add a new component:

# Install shadcn CLI (if not already installed)
bunx shadcn-ui@latest add button

# Or add multiple components
bunx shadcn-ui@latest add card dialog dropdown-menu

Performance Targets

OpenCode Console is designed for high-performance operation:

Integration with OpenCode

WebSocket Bridge

The console connects to OpenCode via a WebSocket bridge that:

1. Captures stdout/stderr from the OpenCode process
2. Parses and categorizes events
3. Streams events to connected Console clients
4. Relays user commands back to OpenCode

Event Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   OpenCode  │────▶│   Bridge    │────▶│   Console   │
│   (TUI)     │◀────│ (WebSocket) │◀────│   (Web)     │
└─────────────┘     └─────────────┘     └─────────────┘

Supported OpenCode Features

• Session start/stop events
• Message streaming (user/assistant)
• Tool call notifications
• File change events
• Error and warning logs
• Model switching commands

Troubleshooting

Console Not Connecting

1. Ensure the WebSocket bridge is running on the expected port
2. Check that OPENCODE_SOCKET_URL is correctly configured
3. Verify no firewall is blocking WebSocket connections

Database Errors

# Reset the database
rm apps/console/sqlite.db
bun run db:push

Build Failures

# Clear Next.js cache
rm -rf apps/console/.next

# Reinstall dependencies
rm -rf node_modules
bun install

Slow Performance

• Check event log size (consider archiving old sessions)
• Ensure SQLite database isn't corrupted
• Monitor WebSocket connection health

Roadmap

The following features are planned for future releases:

• Full bridge package implementation
• Session export/import functionality
• Collaborative viewing (multiple users)
• Plugin system for custom panels
• Mobile-responsive interface
• Keyboard shortcuts for power users

Contributing

This project follows autonomous development practices. All changes should be:

1. Tracked through feature_list.json
2. Committed with descriptive conventional commit messages
3. Reviewed for consistency with existing code style

Development Workflow

1. Create a feature branch
2. Make changes following the project's TypeScript/React conventions
3. Test locally with bun run dev
4. Submit a pull request with a clear description

License

See the LICENSE file in the repository for license information.