home folder opencode requirements

Surfacing opencode project history out of an isolated container

Status: research / needs follow-up (one real ambiguity not resolved on this pass) Date: 2026-07-03 Companions: home-folder-claude-requirements.md, home-folder-omp-requirements.md, home-folder-codex-requirements.md Governing principle: containerize the configuration, not the storage — same as the companion docs. Decision (partial): opencode's active session/message storage is relational (opencode.db, SQLite, WAL, session.project_id indexed FK to project) — not the per-project file tree it also has on disk. Export-at-teardown by project_id/directory, don't bind-mount the DB. The per-project snapshot/ses_<id>/ git dirs (rewind data) mount whole, same as Claude's file-history pattern. Open question: whether the per-project project/<slug>/storage/session/ file tree is legacy (superseded by the DB) or still actively written alongside it — not resolved this pass, see Risks.

Two storage shapes coexist — genuinely ambiguous which is authoritative

Unlike Claude/omp/codex (each had one clear answer), opencode's data directory shows two different storage models for the same data, both with real content on this host:

1. A per-project file tree: project/<path-slug>/storage/session/{info,message,part}/
2. A relational DB: opencode.db's project/session/message/part/session_message tables — confirmed 8 projects, 53 sessions, real data, WAL-mode (-shm/-wal present)

Both exist with non-trivial content. This reads like an in-progress migration to the DB-backed model (common evolution for tools that started file-based) — but this pass didn't verify which one opencode's current running version actually reads from, only that both are populated. Treat the DB as authoritative for the design below (its schema is richer and clearly relational — session has an indexed project_id FK), but confirm against your installed opencode version before building the export logic.

Layout of ~/.local/share/opencode (skimmed 2026-07-03)

Path	Kind	Keyed by	Surface?
opencode.db (+-shm/-wal) project/session/message/part/session_message tables	History — sessions + messages, relational	session.project_id (indexed FK) → project table, which carries worktree path	Export-at-teardown by project, not mount (WAL, shared, same hazard class as omp/codex)
project/<path-slug>/snapshot/ses_<id>/	History — a git repository per session (rewind/diff data: HEAD, objects/, refs/, logs/)	session ID	Yes — mount whole, collision-free (new sessions = new dirs)
project/<path-slug>/storage/session/{info,message,part}/	Ambiguous — file-based session/message storage, possibly superseded by opencode.db	project path slug (absolute path, /→-, matches Claude's scheme — not $HOME-relative like omp)	Unresolved — see Risks. If still live, same treatment as Claude's projects/<slug>/
storage/project/<hash>.json	Project registry — {id, worktree, vcs, sandboxes, time}	content-hash id	Config-ish — unverified whether the DB's project table has fully superseded this
auth.json	Auth secret — dedicated file, mode 0600, plaintext (no OS-keychain support as of this research — confirmed via OpenCode's own GitHub issue tracker)	—	ro-mount candidate, same shape as Claude/codex
repos/, sandbox/, tool-output/, log/	Cache / runtime	—	No

Why path-mirroring still applies

The file-tree slug (project/home-mcrowe-Programming-1TouchPoint-sob_external_integrations/) is built from the absolute path with / replaced by - — the same scheme Claude uses, not omp's $HOME-relative stripping. The DB's project.worktree column stores the full absolute path directly (confirmed: "worktree": "/data/mcrowe/Programming/Personal/get-shit-done"). Either way, running the container at the identical host absolute path keeps both the legacy slug and the DB row consistent — same decision as the other three harnesses, for the same reason.

Implementation guidance

1. Path mirroring, same as Claude/omp/codex.
2. Mount project/<slug>/snapshot/ whole, rw — session-ID-keyed, collision-free, no ambiguity here regardless of which storage model wins.
3. opencode.db → guarded teardown export by project_id (join session→project on worktree matching the container's project path), parallel to omp's history.db export and codex's threads export. Do not bind-mount — WAL, shared, same corruption hazard as the other two SQLite stores.
4. Do not build anything against the project/<slug>/storage/session/ file tree until the ambiguity above is resolved — building an export path against a possibly-dead storage format wastes the effort and risks silently missing the real (DB-backed) data.
5. auth.json → ro-mount, same pattern as Claude/codex.

Risks / open questions

• The core ambiguity: is project/<slug>/storage/session/ still written by the currently installed opencode version, or is it dead weight from a prior version's format? Resolve by either (a) checking opencode's own changelog/release notes for a storage-migration entry, or (b) starting a fresh session and observing whether new files land in the file tree, the DB, or both. This blocks finalizing the export design — do this before implementing, not during.
• storage/project/<hash>.json vs. the DB's project table — likely the same migration question. If the JSON registry is legacy, ignore it; if it's still consulted, it needs the same export treatment as the DB.
• Unlike codex's threads table (clearly load-bearing, 3 real rows tied to actual resume), this research didn't confirm whether opencode's DB-based session data is required for resume specifically, or just for the TUI's session list — affects how urgently the export needs to ship before regular usage should be considered "for real."

Verification done

• fd skim of ~/.local/share/opencode to depth 3 (excluding bin/).
• Confirmed project/<slug>/ file-tree layout: app.json, snapshot/ses_<id>/ (a real git repo per session — HEAD, objects/, refs/, logs/, config, description, index), and storage/session/{info,message,part}/.
• Confirmed opencode.db schema: project, session (with project_id FK, directory/path columns, indexed), message, part, session_message, todo, event, account, workspace.
• Confirmed non-trivial row counts: 8 projects, 53 sessions in opencode.db.
• Confirmed storage/project/<hash>.json registry shape: {id, worktree, vcs, sandboxes, time}.
• Confirmed auth.json is a small dedicated file (per OpenCode's own docs and GitHub issue tracker: plaintext, mode 0600, no OS-keychain support shipped as of this research).
• Not verified: which storage model (file tree vs. DB) opencode's currently running version actually writes to for new sessions — the actual gap this doc flags for follow-up.