# What Database Does Omarchy Use?

> Omarchy uses a local SQLite database named opencode.db for AI agent data. Learn where Oarchy stores its persistent data and understand its simple database setup.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-19

---

**Omarchy uses a local SQLite database named `opencode.db` stored in the XDG data directory to persist AI agent usage data.**

Omarchy, the AI development framework from Basecamp, relies on a lightweight file-based storage system rather than a traditional client-server database. If you are investigating what database Omarchy uses, the answer lies in its direct integration with SQLite through the `opencode.db` file. This local database handles message storage and usage analytics across AI providers without requiring external database servers or network connections.

## Where Omarchy Stores Its Data

Omarchy follows the XDG Base Directory Specification for data storage. The database file resides at:

```

$XDG_DATA_HOME/opencode/opencode.db

```

When `XDG_DATA_HOME` is unset, the path falls back to the standard Linux default:

```

~/.local/share/opencode/opencode.db

```

This location ensures user-specific data isolation and proper cleanup when uninstalling the application. According to the basecamp/omarchy source code, this path is constructed dynamically across all components that interact with the persistence layer.

## How Omarchy Accesses the Database

The Omarchy codebase accesses the SQLite database through standard `sqlite3` interfaces in both Python helper scripts and shell utilities. The database is typically opened in read-only mode for usage reporting to prevent accidental data corruption during analysis.

### Agent Usage Scripts

The primary interfaces for querying AI usage statistics are the agent-specific helper scripts located in the `bin/` directory. Both `bin/omarchy-agent-usage-codex` and `bin/omarchy-agent-usage-claude` implement the same database resolution logic:

- **`bin/omarchy-agent-usage-codex`** – Constructs the database path using XDG environment variables and opens the SQLite connection for Codex usage analytics.
- **`bin/omarchy-agent-usage-claude`** – Uses identical path resolution to query usage data specifically for the Claude provider.

These scripts demonstrate the canonical method for locating `opencode.db` across the Omarchy ecosystem.

### Test Suite Integration

The test suite validates database interactions directly through shell scripts that import `sqlite3`. Key test files include:

- **[`test/shell.d/agent-usage-codex-scanner-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/agent-usage-codex-scanner-test.sh)** – Imports `sqlite3` and executes queries against `opencode.db` to verify Codex usage tracking.
- **[`test/shell.d/agent-usage-claude-scanner-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/agent-usage-claude-scanner-test.sh)** – Performs similar validation for Claude provider data integrity.

## Code Examples for Querying opencode.db

You can inspect Omarchy's usage data using either the command-line interface or programmatic access via Python.

**Querying via Bash and sqlite3 CLI**

```bash
#!/usr/bin/env bash

# Resolve the Omarchy database path

DB_PATH="${XDG_DATA_HOME:-$HOME/.local/share}/opencode/opencode.db"

# Count total messages stored

sqlite3 "$DB_PATH" "SELECT COUNT(*) FROM message;"

```

**Querying via Python with URI Mode**

```python
#!/usr/bin/env python3
import sqlite3
from pathlib import Path
import os

# Build the path to opencode.db

db_path = Path(os.getenv("XDG_DATA_HOME") or Path.home() / ".local" / "share") / "opencode" / "opencode.db"

# Open read-only to avoid locking issues

with sqlite3.connect(f"file:{db_path}?mode=ro", uri=True) as conn:
    cur = conn.cursor()
    cur.execute("""
        SELECT provider, COUNT(*) AS msgs
        FROM message
        GROUP BY provider
        ORDER BY msgs DESC;
    """)
    for provider, msgs in cur.fetchall():
        print(f"{provider}: {msgs} messages")

```

These patterns mirror the implementation found in `bin/omarchy-agent-usage-codex` and the associated test suites, allowing you to build custom analytics on top of Omarchy's stored metrics.

## Summary

- **Omarchy uses SQLite** via the `opencode.db` file for local persistence of AI agent interactions.
- **Database location** resolves to `$XDG_DATA_HOME/opencode/opencode.db` or falls back to `~/.local/share/opencode/opencode.db`.
- **Access methods** include standard `sqlite3` Python modules and CLI tools, with read-only connections preferred for reporting.
- **Key source files** referencing this database include `bin/omarchy-agent-usage-codex`, `bin/omarchy-agent-usage-claude`, and the test scanners in `test/shell.d/`.

## Frequently Asked Questions

### What type of database does Omarchy use?

Omarchy uses **SQLite**, a serverless, file-based relational database engine. This choice eliminates configuration overhead and allows Omarchy to store AI usage metrics locally without requiring a separate database server installation.

### Where is the Omarchy SQLite database located?

The database file `opencode.db` resides in the `opencode` subdirectory of your XDG data directory. The exact path is `$XDG_DATA_HOME/opencode/opencode.db`, which typically resolves to `~/.local/share/opencode/opencode.db` on standard Linux systems.

### Can I query the Omarchy database directly?

Yes, you can query the database using the standard `sqlite3` command-line tool or any SQLite-compatible library. The file uses standard SQLite schema conventions, and you can open it in read-only mode using URI syntax (e.g., `file:opencode.db?mode=ro`) to avoid locking conflicts with running Omarchy processes.

### Does Omarchy use database migrations for schema changes?

No, Omarchy does not use traditional database migration frameworks. According to the source architecture, schema management and changes are handled through shell scripts rather than SQL migration files, keeping the database layer lightweight and version-agnostic.