Data & Storage section in General Settings

[jeonghun-jj-lee]

Data & Storage section in General Settings

Important

Problem

Amicode users have no visibility into where their session database and configuration files live, and no way to override these locations without setting XDG environment variables system-wide. Power users who want to sync sessions across machines, isolate test data, or point at a shared config directory must know the internal env var names (OPENCODE_DB, OPENCODE_CONFIG_DIR) and manually inject them.

Approach

Add a Data & Storage section in the General tab of the settings dialog. Two path fields — session database and configuration directory — show the resolved defaults as placeholder text and allow overrides. Changes take effect on server restart (kill + respawn with the corresponding env vars injected).

Approaches Considered

Approach	Verdict
A: Standalone section + controller	Chosen — clean separation from Developer Tools; "Data & Storage" is a user-facing concern, not dev-only
B: Sub-group inside Developer Tools	Rejected — misframes the audience (these aren't developer-only paths)
C: VS Code native settings only	Rejected — inconsistent with the custom settings dialog direction; no placeholder showing resolved defaults

Scope

• UI: one new section in the General tab (2 path fields with placeholder defaults + inline validation)
• Bridge: two new message kinds ("data-storage-query" for defaults, "data-storage-update" for changes)
• Extension host: handler that validates paths, writes VS Code settings, injects env vars, restarts server
• Spawn modification: read stored overrides and inject OPENCODE_DB / OPENCODE_CONFIG_DIR on cold start

Assumptions

• Opencode already respects OPENCODE_DB (absolute path or :memory:) and OPENCODE_CONFIG_DIR env vars — no opencode changes needed
• No data migration on path change — user manages moving/copying their data
• Server restart is acceptable (same cost as the Developer Tools opencode hot-swap)
• The section is always visible and always editable (no toggle gate)

---

Acceptance Criteria

1. A "Data & Storage" section renders in the General tab (between Display and Advanced)
2. Session database field: a text input whose placeholder shows the resolved default path (e.g. ~/.local/share/opencode/opencode.db)
3. Configuration directory field: a text input whose placeholder shows the resolved default path (e.g. ~/.config/opencode)
4. Both fields are always editable (no toggle gate)
5. On blur, each field validates: session database — parent directory exists; config directory — directory exists. Inline error shown if invalid
6. On valid change, the opencode server process is killed and respawned with the new OPENCODE_DB / OPENCODE_CONFIG_DIR env vars within 2 seconds
7. When the field is cleared (empty string), the override is removed and opencode falls back to its XDG defaults on next restart
8. Overrides persist across sessions (survive window reload and VS Code restart)
9. On mount, the resolved default paths are fetched from the extension host and displayed as placeholder text (accounting for any system-level XDG overrides)

Key Decisions

Separate section from Developer Tools

Session database and config directory paths are user-facing concerns (syncing, isolation, shared config), not developer-only. Placing them in their own "Data & Storage" section makes them discoverable without implying they're advanced/developer features.

Placeholder shows resolved default

Rather than an empty field with no indication of where data lives, the placeholder displays the actual resolved path. This gives immediate visibility ("oh, my sessions are at...") even without overriding — addressing the discoverability problem without requiring a change.

Server restart (not immediate)

The SQLite WAL connection and config file watchers cannot be swapped mid-process. A server restart is the simplest correct mechanism, and it's the same cost as the Developer Tools opencode hot-swap.

No migration

Changing the database path does not copy/move existing data. This avoids: partial-copy corruption, permission issues on the destination, ambiguity about "move" vs "copy" semantics. The user can cp or mv their .db file manually.

Env var injection at spawn

The extension injects OPENCODE_DB and OPENCODE_CONFIG_DIR into the spawned opencode process's environment. This leverages opencode's existing override mechanism with zero changes to the opencode codebase.

Data Contracts

Settings store addition (Settings interface)

storage: {
 databasePath: string // override for session DB; default: ""
 configDir: string // override for config directory; default: ""
}

Bridge: query defaults (app → extension host, on mount)

{ source: "amicode", kind: "data-storage-query" }

Bridge: defaults reply (extension host → app)

{
 source: "amicode",
 kind: "data-storage-defaults",
 databasePath: string, // resolved default (e.g. "/Users/x/.local/share/opencode/opencode.db")
 configDir: string // resolved default (e.g. "/Users/x/.config/opencode")
}

Bridge: update (app → extension host, on blur)

{
 source: "amicode",
 kind: "data-storage-update",
 databasePath: string, // "" = use default
 configDir: string // "" = use default
}

Bridge: status reply (extension host → app)

{
 source: "amicode",
 kind: "data-storage-status",
 databaseValid: boolean,
 databaseError?: string,
 configValid: boolean,
 configError?: string,
 serverRestarted: boolean
}

VS Code settings written by the handler

Setting	Value when overridden	Value when default
amicode.sessionDatabase	the user's absolute path	""
amicode.configDir	the user's absolute directory path	""

Env vars injected at opencode spawn

Setting non-empty?	Env var injected
amicode.sessionDatabase	OPENCODE_DB=<value>
amicode.configDir	OPENCODE_CONFIG_DIR=<value>

Constraints & Invariants

• Empty field = no override = opencode uses its XDG defaults
• Only absolute paths are accepted (relative paths are rejected at validation)
• The session database path must point to a file whose parent directory exists (the file itself may not exist yet — opencode creates it)
• The config directory must exist as a directory
• The relay allowlist in chat_panel.ts must include both "data-storage-query" and "data-storage-update"
• On cold start (extension activation), the extension reads the stored VS Code settings and injects env vars BEFORE spawning opencode — the override is not lost on restart

Prior Art

• OPENCODE_DB env var — opencode's existing database path override (packages/core/src/database/database.ts)
• OPENCODE_CONFIG_DIR env var — opencode's existing config directory override (packages/core/src/flag/flag.ts)
• Developer Tools section (Developer Tools section in General Settings #377) — same factored-component + controller pattern, same bridge/restart mechanism
• Font settings in General tab — same TextInputV2 with placeholder pattern

Implementation Plan

Files to create (SolidJS app)

File	Purpose
packages/app/src/components/settings-v2/data-storage.tsx	UI component (section with 2 path fields + validation)
packages/app/src/components/settings-v2/data-storage-controller.ts	Controller (default query, settings read/write, postMessage dispatch)

Files to modify (SolidJS app)

File	Change
packages/app/src/components/settings-v2/general.tsx	Import + render <DataStorageSection /> between Display and Advanced
packages/app/src/context/settings.tsx	Add storage to Settings interface + defaultSettings
packages/app/src/i18n/en.ts	Add i18n keys for section/row titles, descriptions, errors

Files to modify (Extension host)

File	Change
packages/extension/src/chat_bridge.ts	Add "data-storage-query" + "data-storage-update" handlers
packages/extension/src/chat_panel.ts	Add both kinds to relay allowlist
packages/extension/src/extension.ts or server_auth.ts	Read VS Code settings → inject OPENCODE_DB / OPENCODE_CONFIG_DIR env vars at spawn
packages/extension/package.json	Add amicode.sessionDatabase and amicode.configDir configuration properties

Source

Design session — brainstorming interview resolved: separate section (not inside Developer Tools), two fields (database + config dir), placeholder shows resolved defaults, editable always, server restart on change, env var injection, no migration.