opencode-cli-mcp

Overview Schema Source Related Servers Discussions Admin

OpenCode Session Depot

opencode_depot

Destructive

Session depot: list, inspect, archive/unarchive, rename, delete, search transcripts, semantic RAG search, code-recall search, or stats.

Instructions

Session depot: list, inspect, archive/unarchive, rename, delete, search transcripts, semantic RAG search, code-recall search, or stats.

Reads opencode's SQLite depot directly - works without opencode serve. Archive/unarchive/rename are reversible; delete is permanent (FK cascade). search = exact/full-text wayback find; rag = semantic similarity over indexed transcripts; code = when an agent touched a file (patch paths + edit tool inputs), by path or by content. rag/code need uv sync --extra rag and an index pass (rag_index indexes both).

Return Format

{"success": bool, "message": str, "data": dict}

Examples

opencode_depot(action="list", status="archived", limit=20) opencode_depot(action="unarchive", session_id="sess_01") opencode_depot(action="search", query="power limit") opencode_depot(action="search", query="vienna", project="chitchat", timeframe_days=7) opencode_depot(action="rag", query="what did we decide about the power limit") opencode_depot(action="code", path_filter="auth_utils.py") opencode_depot(action="code", query="extracted the auth module", path_filter="src") opencode_depot(action="rag_index") opencode_depot(action="stats") opencode_depot(action="star", session_id="sess_01") opencode_depot(action="tag_add", session_id="sess_01", tags="neuro, vienna") opencode_depot(action="list", starred=True, sort="starred") opencode_depot(action="export", session_id="sess_01", format="docx") opencode_depot(action="memops", session_id="sess_01", tags="neuro")

Input Schema

Name	Required	Description	Default
`tag`	No	List/search: only sessions carrying this tag
`sort`	No	Sort order (list); 'starred' puts favourites first	updated
`tags`	No	tag_add/tag_remove: comma-separated tags, e.g. 'neuro, vienna'
`agent`	No	Agent name filter (list)
`limit`	No	Page size (list/search/rag/code)
`query`	No	Search text (search/rag/code)
`title`	No	New title (rename)
`action`	Yes	list: sessions with filters. get: one session with counts. archive: hide from active list. unarchive: restore (missing in opencode UI). rename: set title. delete: permanently remove (cascades messages). search: full-text across transcripts and titles (wayback find). search filters: query + optional timeframe_days (last N days), project (directory/project_id substring), include_archived, starred (true = only favourites), tag. star / unstar: toggle a favourite (sidecar db, never touches opencode.db). tag_add / tag_remove: attach/detach tags (tags param, comma-separated). tags: list every tag with usage counts. export: write md/html/docx to out_path (docx needs LibreOffice). memops: drop a frontmatter note into the advanced-memory inbox. rag: semantic search over indexed transcripts (needs rag extras). rag_index: index new sessions for semantic search (text + code). rag_status: index state + availability. code: find WHEN an agent touched a file - by path (path_filter only) or by content (query): patch paths + edit tool inputs from every session. code_index: rebuild the code table from all sessions (code-only backfill). code_status: code index state. stats: aggregate cost/tokens by agent/project.
`format`	No	export: output format (docx requires LibreOffice installed)	md
`offset`	No	Page offset (list)
`search`	No	Title substring filter (list)
`status`	No	Status filter (list): all, active, or archived	all
`date_to`	No	Search/list: explicit range end YYYY-MM-DD (takes precedence over timeframe_days)
`project`	No	Project/directory substring filter (list)
`starred`	No	List/search: true = only favourites, false = only unstarred, null = no constraint
`out_path`	No	export: destination file (default ~/Downloads)
`date_from`	No	Search/list: explicit range start YYYY-MM-DD (takes precedence over timeframe_days)
`session_id`	No	Session ID (required for get/archive/unarchive/rename/delete)
`path_filter`	No	File path substring (code): only rows whose path contains this
`timeframe_days`	No	Search/list: parts/sessions from the last N days (e.g. 7 = last week)
`include_archived`	No	Search: include archived sessions

Output Schema

Name	Required	Description	Default
`data`	Yes
`message`	Yes
`success`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedv0.2.11Oct 21, 2026

changedInput schema / properties / action / description

Previous value: -"list: sessions with filters. get: one session with counts. archive: hide from active list. unarchive: restore (missing in opencode UI). rename: set title. delete: permanently remove (cascades messages). search: full-text across transcripts and titles (wayback find). rag: semantic search over indexed transcripts (needs rag extras). rag_index: index new sessions for semantic search (text + code). rag_status: index state + availability. code: find WHEN an agent touched a file - by path (path_filter only) or by content (query): patch paths + edit tool inputs from every session. code_index: rebuild the code table from all sessions (code-only backfill). code_status: code index state. stats: aggregate cost/tokens by agent/project."New value: +"list: sessions with filters. get: one session with counts. archive: hide from active list. unarchive: restore (missing in opencode UI). rename: set title. delete: permanently remove (cascades messages). search: full-text across transcripts and titles (wayback find). search filters: query + optional timeframe_days (last N days), project (directory/project_id substring), include_archived, starred (true = only favourites), tag. star / unstar: toggle a favourite (sidecar db, never touches opencode.db). tag_add / tag_remove: attach/detach tags (tags param, comma-separated). tags: list every tag with usage counts. export: write md/html/docx to out_path (docx needs LibreOffice). memops: drop a frontmatter note into the advanced-memory inbox. rag: semantic search over indexed transcripts (needs rag extras). rag_index: index new sessions for semantic search (text + code). rag_status: index state + availability. code: find WHEN an agent touched a file - by path (path_filter only) or by content (query): patch paths + edit tool inputs from every session. code_index: rebuild the code table from all sessions (code-only backfill). code_status: code index state. stats: aggregate cost/tokens by agent/project."

changedInput schema / properties / action / enum

Previous value: -[
-  "list",
-  "get",
-  "archive",
-  "unarchive",
-  "rename",
-  "delete",
-  "search",
-  "stats",
-  "rag",
-  "rag_index",
-  "rag_status",
-  "code",
-  "code_index",
-  "code_status"
-]New value: +[
+  "list",
+  "get",
+  "archive",
+  "unarchive",
+  "rename",
+  "delete",
+  "search",
+  "stats",
+  "star",
+  "unstar",
+  "tag_add",
+  "tag_remove",
+  "tags",
+  "export",
+  "memops",
+  "rag",
+  "rag_index",
+  "rag_status",
+  "code",
+  "code_index",
+  "code_status"
+]

addedInput schema / properties / date_from

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Search/list: explicit range start YYYY-MM-DD (takes precedence over timeframe_days)"
+}

addedInput schema / properties / date_to

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Search/list: explicit range end YYYY-MM-DD (takes precedence over timeframe_days)"
+}

addedInput schema / properties / format

Added value: +{
+  "default": "md",
+  "description": "export: output format (docx requires LibreOffice installed)",
+  "enum": [
+    "md",
+    "html",
+    "docx"
+  ],
+  "type": "string"
+}

addedInput schema / properties / include_archived

Added value: +{
+  "default": true,
+  "description": "Search: include archived sessions",
+  "type": "boolean"
+}

addedInput schema / properties / out_path

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "export: destination file (default ~/Downloads)"
+}

changedInput schema / properties / sort / description

Previous value: -"Sort order (list)"New value: +"Sort order (list); 'starred' puts favourites first"

changedInput schema / properties / sort / enum

Previous value: -[
-  "updated",
-  "created",
-  "archived",
-  "cost",
-  "tokens",
-  "title"
-]New value: +[
+  "updated",
+  "created",
+  "archived",
+  "cost",
+  "tokens",
+  "title",
+  "starred"
+]

addedInput schema / properties / starred

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "List/search: true = only favourites, false = only unstarred, null = no constraint"
+}

addedInput schema / properties / tag

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "List/search: only sessions carrying this tag"
+}

addedInput schema / properties / tags

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "tag_add/tag_remove: comma-separated tags, e.g. 'neuro, vienna'"
+}

addedInput schema / properties / timeframe_days

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 1,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Search/list: parts/sessions from the last N days (e.g. 7 = last week)"
+}

removedOutput schema / additionalProperties
```
Removed value: -true
```

addedOutput schema / properties

Added value: +{
+  "data": {
+    "type": "object"
+  },
+  "message": {
+    "type": "string"
+  },
+  "success": {
+    "type": "boolean"
+  }
+}

addedOutput schema / required

Added value: +[
+  "success",
+  "message",
+  "data"
+]

First observedv0.2.3Aug 5, 2026

TDQS

A4.2/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses exactly what the coarse destructiveHint=true annotation cannot: archive/unarchive/rename are reversible, delete is permanent with FK cascade into messages, star writes to a sidecar db and never touches opencode.db. It also notes the tool reads SQLite directly and works without `opencode serve`, and names the rag/code dependency and index requirement. That is meaningful per-action behavioral nuance layered on top of the annotations rather than repetition.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence front-loads purpose and the reversibility line is placed immediately after, so the highest-value information is early. The mechanism/rag-code paragraph and return-format block are tight. The 14-line examples block is somewhat heavy for the space available and partly duplicates the action enum's own descriptions, but it does earn its place for a 21-action tool by showing valid combinations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 21-action, 21-param tool this description covers purpose, action semantics, reversibility/destructiveness, prerequisites and return shape, and an output schema already exists so return values need not be detailed. It leaves some per-action return differences and edge cases (e.g. export out_path defaults, code_index rebuild scope) to the schema, which is acceptable but not fully rounded out.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, including a long per-action description in the action enum, so the baseline is 3. The description adds value by grouping which filters apply to which action (e.g. 'search filters: query + optional timeframe_days, project, include_archived, starred, tag') and by flagging comma-separated tag syntax, plus examples that show valid parameter pairings. It does not fully document date_from/date_to precedence or offset behavior beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a concrete resource (opencode's SQLite session depot) and enumerates the operations it exposes: list, inspect, archive, rename, delete, search, rag, code, stats. It also distinguishes search (exact/full-text) from rag (semantic) and code (file-touch recall), which an agent cannot infer from the names alone. It stops short of naming overlapping siblings such as opencode_list_sessions or opencode_get_session, so sibling differentiation is incomplete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives real when-to-use guidance: 'search = exact/full-text wayback find; rag = semantic similarity; code = when an agent touched a file', and states the prerequisite that rag/code need `uv sync --extra rag` plus an index pass. The 14 examples demonstrate action/param combinations concretely. It never says when to use this instead of the sibling session tools (opencode_list_sessions, opencode_get_session), so there are no explicit alternatives/exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.