Skip to content

AGENTS.md

Latest commit

 

History

History
38 lines (33 loc) · 1.96 KB

AGENTS.md

File metadata and controls

38 lines (33 loc) · 1.96 KB
Raw

AGENTS.md

What this is

Standalone Bash CLI (opencode-relocate) that edits OpenCode's local SQLite database to move/relink projects and sessions. No LLM, no Bun, no build step. The entire tool is the single file opencode-relocate (~2300 lines).

Working on the tool

  • All logic lives in ./opencode-relocate. Edit that file directly; there is no build, compile, package manager, or test suite.
  • Run it directly: ./opencode-relocate <command> [args]. Commands: relocate, move-sessions, split-project, relink (4 total — the script's own header comment at the top is stale and only lists 3).
  • Uses set -euo pipefail. Conventions live at the top of the file: path constants (OPENCODE_DB, OPENCODE_PROJECTS_DIR, OPENCODE_SESSIONS_DIR), color codes, and logging helpers info/warn/ok/err. Use sql_query (soft) and sql_query_strict (fails on error) rather than calling sqlite3 directly.
  • Requirements: sqlite3, git (for split-project/relink), optional jq (falls back to sed for JSON edits).

Critical: this mutates real user data

  • Every command operates on the live DB at ~/.local/share/opencode/opencode.db and ~/.local/share/opencode/storage/. Running a command for real edits the developer's own OpenCode state — do not run destructive commands casually.
  • Each command auto-backs up the DB (+WAL/SHM) to a timestamped .bak before writing. Use --dry-run (where supported, e.g. relink) to preview.

Domain model

  • OpenCode identifies a project by the hash of its first root commit (git rev-list --max-parents=0 HEAD). Recreating that commit changes the ID and orphans sessions — this is what relink fixes.
  • Non-git directories live under the global project; sessions are filtered by directory prefix. global can only be a source, never a target.

Repo notes

  • .opencode/ is OpenCode's own agent config (plugin dependency), not part of the CLI's code.
  • README.md is the authoritative usage doc.