Store and retrieve arbitrary JSON metadata for OpenCode sessions.

Installation

Add to your opencode.json:

{
  "plugin": ["opencode-session-metadata"]
}

OpenCode will automatically install the plugin on startup.

Tools

getSessionData

Get current session information (id, title, directory, version, etc.)

setSessionData

Update session data. Currently supports setting title only.

Use setSessionData with title "New Session Title"

getMetadata

Get stored session metadata from external storage.

setMetadata

Store arbitrary JSON metadata for the current session.

Use setMetadata with metadata {"projectId": "proj-123", "status": "in-progress"}

Environment Injection

Automatically injects OPENCODE_SESSION_ID, OPENCODE_WORKSPACE_ROOT, and OPENCODE_SERVER environment variables into all shell commands. Unix-only (macOS/Linux); Windows is not supported.

How It Works

Metadata is stored as JSON files in ~/.local/share/opencode/storage/session-metadata/<project-id>/<session-id>.json. The plugin automatically:

• Creates the storage directory
• Adds sessionId and storedAt timestamps
• Preserves any custom fields you provide

Use Cases

Agent Hierarchies:

{
  "treeId": "pr6187-11021530",
  "parentId": "ses_parent456",
  "level": 1
}

Project Tracking:

{
  "projectId": "proj-123",
  "epic": "feature-x",
  "sprint": "sprint-24"
}

User Context:

{
  "userId": "user-789",
  "teamId": "team-alpha",
  "role": "developer"
}

Custom Tags:

{
  "tags": ["bug-fix", "urgent"],
  "category": "backend",
  "priority": "high"
}

Requirements

• OpenCode >= 0.15.18

Storage Location

Metadata files are stored in ~/.local/share/opencode/storage/session-metadata/<project-id>/, organized by project alongside OpenCode's session storage.

License

MIT