Database & Storage

Relevant source files

The following files were used as context for generating this wiki page:

• src-tauri/src/commands/agents.rs
• src/lib/api.ts
• web_server.design.md
• README.md
• src/i18n/locales/en.json
• cc_agents/unit-tests-bot.opcode.json

Introduction

The Database & Storage system in Opcode is responsible for persisting agent configurations, execution history, application settings, and session-specific metadata. It utilizes a hybrid approach, combining a structured relational database (SQLite) for application state with filesystem-based storage for large-scale session logs (JSONL).

This module ensures that users can resume coding sessions, track Claude API usage costs, and manage a library of custom AI agents. All data is stored locally on the user's machine to prioritize privacy and security.

Sources: README.md:118-125, src-tauri/src/commands/agents.rs:163-228

Relational Database Architecture

Opcode uses SQLite (via the rusqlite crate) to manage structured data. The database, typically named agents.db, is stored in the platform-specific application data directory. It consists of three primary tables: agents, agent_runs, and app_settings.

Entity Relationship Diagram

The following diagram illustrates the relationships between the core database entities.

Data Models

Table	Field	Type	Description
agents	id	INTEGER	Primary key, auto-incremented.
	system_prompt	TEXT	The instructions defining the agent's behavior.
	model	TEXT	Target AI model (e.g., 'sonnet', 'opus'). Defaults to 'sonnet'.
agent_runs	session_id	TEXT	UUID session ID generated by Claude Code. Links to JSONL files.
	status	TEXT	Lifecycle state: 'pending', 'running', 'completed', 'failed', 'cancelled'.
app_settings	key	TEXT	Setting identifier (e.g., claude_binary_path).

Sources: src-tauri/src/commands/agents.rs:166-228, src/lib/api.ts:89-130

Filesystem Storage & JSONL Logs

While metadata is stored in SQLite, the full content of chat transcripts and tool execution logs is stored in the filesystem.

Session History

Claude Code generates .jsonl (JSON Lines) files within the ~/.claude/projects/ directory. Opcode encodes project paths (replacing / with -) to locate these directories and read session data for real-time metrics calculation and history display.

Agent Exports

Agents can be exported to and imported from .opcode.json files. These files contain a versioned wrapper around the agent's configuration.

{
  "version": 1,
  "exported_at": "2025-06-23T14:29:51.009370+00:00",
  "agent": {
    "name": "Unit Tests Bot",
    "model": "opus",
    "system_prompt": "..."
  }
}

Sources: src-tauri/src/commands/agents.rs:114-161, cc_agents/unit-tests-bot.opcode.json:1-11

Data Flow: Agent Execution & Persistence

The system coordinates between the process registry, the SQLite database, and the filesystem logs during agent execution.

1. Initialization: execute_agent creates a "pending" record in agent_runs.
2. Tracking: As the Claude process starts, the session_id is extracted from the stdout stream and updated in the database.
3. Completion: Upon process termination, the status is updated to "completed" or "failed," and metrics (tokens, cost) are derived by parsing the corresponding .jsonl file.

Sources: src-tauri/src/commands/agents.rs:567-660, web_server.design.md:104-120

Storage Management API

The api object in the frontend provides methods for direct database manipulation, often used for debugging or advanced configuration via the Database Storage settings page.

Function	Endpoint/Command	Description
storageListTables	storage_list_tables	Returns all tables in the SQLite database.
storageExecuteSql	storage_execute_sql	Executes raw SQL queries (used in SQL Editor).
storageResetDatabase	storage_reset_database	Deletes all data and restores default table structures.
getSetting	storage_read_table	Retrieves values from the app_settings table.

Sources: src/lib/api.ts:980-1070, src/i18n/locales/en.json:528-568

Summary

The Database & Storage module provides a robust foundation for Opcode by separating lightweight application state (SQLite) from heavy session logs (Filesystem). This hybrid architecture allows for efficient querying of history and settings while maintaining compatibility with the underlying Claude Code CLI's log formats. All operations are local, ensuring user privacy and data ownership.