Local Data & Database
Relevant source files
The following files were used as context for generating this wiki page:
OpenWork employs a filesystem-centric approach to data management, relying heavily on the underlying OpenCode engine's storage primitives. The system is designed to be "local-first," where configuration, session history, and extension logic (skills and plugins) are stored primarily within the user's authorized workspace folders or global configuration directories.
The architecture prioritizes transparency and portability, ensuring that data such as audit logs, plans, and tool execution steps are visible to the user and stored in reconstructable formats like JSON and Markdown.
Sources: PRINCIPLES.md, ARCHITECTURE.md, PRODUCT.md:31-38
Data Storage Architecture
OpenWork data is categorized into three main layers: Project-specific data, Global configuration, and the OpenCode Engine database.
1. Project-Specific Data (.opencode/)
Every workspace contains an .opencode/ hidden directory which serves as the primary local data store for that project.
| Component | Storage Location | Description |
|---|---|---|
| Config | opencode.json | Project-level settings and plugin list. |
| Skills | .opencode/skills/ | Markdown files (SKILL.md) defining specialized behaviors. |
| Commands | .opencode/commands/ | Reusable Markdown-based workflows. |
| Audit Logs | .opencode/audit/ | Exportable logs of prompts, plans, and tool calls. |
Sources: ARCHITECTURE.md, packages/server/src/server.ts:213-220, README.md
2. Global Configuration
Global settings that span multiple workspaces are stored in the user's home directory, following OS-specific standards (e.g., XDG config dirs).
- Path:
~/.config/opencode/or~/.config/openwork/ - Contents: Global
opencode.json, global skills, and the OpenWork server configuration (server.json).
Sources: packages/server/README.md:14-16, packages/desktop/src-tauri/src/commands/skills.rs:56-65
3. OpenCode Engine Database
While OpenWork manages its own metadata via JSON and Markdown files, the underlying OpenCode engine utilizes a SQLite database for session and message persistence.
- Database File:
.opencode/opencode.db - Managed Services: Session history, chat messages, and tool call logs.
Sources: AGENTS.md:62-65
Data Flow and Integration
The following diagram illustrates how OpenWork UI interacts with local data through the OpenWork Server and the OpenCode Engine.
The diagram shows the dual-path integration where the UI manages configurations through a filesystem-backed server while the engine handles session data via a database.
Sources: ARCHITECTURE.md, packages/server/README.md
Database & Filesystem Services
Session & Message Persistence
OpenWork maps "Task Runs" to OpenCode sessions. These are stored in the engine's database and accessed via the SDK.
- Session Data: Includes session ID, title, and status.
- Message Data: Includes chat bubbles, tool calls, and event streams.
Sources: ARCHITECTURE.md, AGENTS.md:67-73
Filesystem Metadata Extraction
Because many "data points" are stored as Markdown files (skills and commands), the server performs runtime extraction of metadata from frontmatter and file bodies.
// Example of metadata extraction from Markdown files
fn extract_description(raw: &str) -> Option<String> {
let mut in_frontmatter = false;
for line in raw.lines() {
let trimmed = line.trim();
if trimmed == "---" { in_frontmatter = !in_frontmatter; continue; }
if in_frontmatter || trimmed.starts_with('#') { continue; }
// Extracts first non-empty line as description
return Some(trimmed.to_string());
}
None
}
Sources: packages/desktop/src-tauri/src/commands/skills.rs:188-215, packages/server/src/skills.ts:31-59
Audit Logging
The system maintains an audit trail for security and transparency.
- Audit Entry Fields:
id,workspaceId,actor(host/remote),action,target,summary, andtimestamp. - Storage: Items are recorded to the workspace audit log during configuration mutations (e.g., updating plugins, upserting skills).
Sources: packages/server/src/server.ts:182-192, PRODUCT.md:52-58
Configuration Management
The OpenWork Server handles the synchronization of local JSON configuration files.
| API Endpoint | Method | Description |
|---|---|---|
/workspace/:id/config | GET | Reads opencode.json and openwork.json from the filesystem. |
/workspace/:id/config | PATCH | Patches top-level keys in JSONC configuration files. |
/workspace/:id/export | GET | Packages config, skills, and commands into a single JSON payload. |
/workspace/:id/import | POST | Writes imported data to the filesystem, optionally replacing existing files. |
Sources: packages/server/src/server.ts:205-235, packages/server/README.md:36-55
Summary
Local data in OpenWork is primarily decentralized across the filesystem to ensure portability and user ownership. While SQLite is used by the engine for high-frequency message and session storage, the application layer favors Markdown and JSON for extension logic (skills/commands) and audit logging. This hybrid approach allows for easy inspection while maintaining the performance required for real-time agentic workflows.