opencode-server-api skill
✓ VerifiedPerform read-only queries against the OpenCode 2.x server to inspect sessions, message history, MCP status, skills, and agents.
- GitHub stars
- 13
- Files
- 1
- Last commit
- Oct 30, 2026
- License
- MIT
- Allowed tools
- —
What does the opencode-server-api skill do?
opencode-server-api is an agent skill. Perform read-only queries against the OpenCode 2.x server to inspect sessions, message history, MCP status, skills, and agents.
Summary generated from the skill's SKILL.md.
About the opencode-server-api skill
Inspecting your OpenCode 2.x server state and history is what this skill enables for developers and AI agents. It provides a read-only interface to query server information, active sessions, message histories, and the status of connected MCP servers. An agent should load this tool when a user asks about their current session, available skills, connected tools, or pending permission requests.
Users interact with the server via GET requests using HTTP basic authentication with a password stored in the OPENCODE_SERVER_PASSWORD environment variable. The skill relies on fetching a live OpenAPI spec from the server to ensure all route and parameter calls are accurate. It can retrieve specific details such as session outcomes, message types, and even a todo list by parsing the input from the most recent todowrite tool call in the message history. It is strictly limited to read-only operations and cannot be used to change server state, answer forms, or access raw configuration files.
What an agent can do with it
- 1Retrieve active todo listsFind the current list of pending tasks by inspecting the latest todowrite tool call.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the opencode-server-api skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the opencode-server-api skill in Claude Code
~/.claude/skills/opencode-server-api/SKILL.md
$ npx degit kevinlin/cowork-z/src-tauri/resources/skills/opencode-server-api ~/.claude/skills/opencode-server-apiInstall the opencode-server-api skill in Claude Code (project)
.claude/skills/opencode-server-api/SKILL.md
$ npx degit kevinlin/cowork-z/src-tauri/resources/skills/opencode-server-api .claude/skills/opencode-server-apiInstall the opencode-server-api skill in Codex
~/.agents/skills/opencode-server-api/SKILL.md
$ npx degit kevinlin/cowork-z/src-tauri/resources/skills/opencode-server-api ~/.agents/skills/opencode-server-apiInstall the opencode-server-api skill in Gemini CLI
~/.gemini/skills/opencode-server-api/SKILL.md
$ npx degit kevinlin/cowork-z/src-tauri/resources/skills/opencode-server-api ~/.gemini/skills/opencode-server-apiInstall the opencode-server-api skill in Claude.ai
npx degit kevinlin/cowork-z/src-tauri/resources/skills/opencode-server-api opencode-server-api && zip -r opencode-server-api.zip opencode-server-api # claude.ai → Customize → Skills → + → Create skill → Upload a skill → opencode-server-api.zip
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablekevinlin/cowork-z/src-tauri/resources/skills/opencode-server-api is public and reachablegithub.com/kevinlin/cowork-z/tree/HEAD/src-tauri/resources/s ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-30github.com/kevinlin/cowork-z/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/kevinlin/cowork-z/blob/HEAD/src-tauri/resources/s ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/kevinlin/cowork-z/blob/HEAD/src-tauri/resources/s ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 91 linesgithub.com/kevinlin/cowork-z/blob/HEAD/src-tauri/resources/s ↗Pass
SKILL.md
View on GitHubOpenCode Server API
This skill lets you inspect the OpenCode server you run on — server info, sessions, message history (including your todo lists), pending permission and question requests, MCP status, skills and agents. It is read-only: use GET requests only.
Authentication
The server port is in your system prompt, inside the <server-access> block. The basic-auth password is already in your shell environment as OPENCODE_SERVER_PASSWORD; your shell expands it locally. Every request needs HTTP basic auth:
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/<endpoint>
Replace $PORT with the port from your system prompt. Use $OPENCODE_SERVER_PASSWORD exactly as written (PowerShell: $env:OPENCODE_SERVER_PASSWORD).
NEVER print, echo, log, or write the password's value anywhere — not to the chat, not to files, not to command output. Only reference it as a shell variable inside commands.
IMPORTANT: Fetch the API Spec First
Before calling ANY endpoint, fetch the live OpenAPI spec. It is the source of truth for routes, parameters and response shapes, and it may be newer than this skill.
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/openapi.json
Do not guess from the examples below; verify against the spec first.
Conventions
- All API routes live under
/api/. Answers are wrapped:{"data": ...}, plus"location"on location-scoped routes. - Location-scoped routes (
/api/mcp,/api/skill,/api/agent) take the workspace folder as alocation[directory]query parameter. The brackets break plain curl URLs, so pass it with-G --data-urlencode:
curl -s -G -u "opencode:$OPENCODE_SERVER_PASSWORD" \
--data-urlencode "location[directory]=<workspace path>" \
http://localhost:$PORT/api/mcp
The workspace path is given in your system prompt (<workspace-conventions>). Session routes need no location.
Endpoints (all GET)
| Route | Returns |
|---|---|
/api/info |
Server version, pid, urls. Use it as the health check. |
/api/session |
{data: [session]} — your sessions. Optional directory, limit, search. |
/api/session/{id} |
{data: session} — id, model, outcome, time, location, permissions. |
/api/session/{id}/message |
{data: [message], cursor} — history. Pass order=desc for newest first, order=asc for oldest first. |
/api/session/{id}/permission |
{data: [request]} — permission requests waiting for an answer. |
/api/session/{id}/form |
{data: [form]} — questions waiting for an answer. |
/api/mcp |
{data: [{name, status: {status, error?}}]} — MCP servers. |
/api/skill |
{data: [{id, name, path, content}]} — available skills. |
/api/agent |
{data: [agent]} — available agents and their models. |
Find your own session in /api/session (filter with directory=<workspace path>).
/api/session/{id}/message
Messages have a type (user, assistant, idle, …). An assistant message has a content array of text, reasoning and tool items. A tool item is {type: "tool", name, state: {status, input, content}}.
Your todo list is the input.todos of your newest todowrite call: read the history newest first (order=desc), find the first tool item named todowrite and take state.input.todos ([{content, status}], status pending, in_progress or completed). There is no todo route.
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" "http://localhost:$PORT/api/session/ses_abc123/message?order=desc"
/api/mcp
status.status is one of connected, pending (still connecting), disabled, failed or needs_auth; error is set on the last two. The list also includes servers from the user's global OpenCode config.
/api/session/{id}/permission and /form
Pending permission request: {id, action, resources, metadata, message?}. Pending form: {id, title, fields: [{key, type, options?}]}. Both are empty when nothing is waiting.
Out of scope
Do not call routes that change state (creating or deleting sessions, prompting, interrupting, answering permissions or forms, editing config or MCP servers). The user decides those in the app. Do not call any route that handles credentials or provider sign-in either; they are not part of this skill. Do not call /api/config: it returns the user's raw config files, which can hold API keys.
Usage Guidance
- Check health (
/api/info) before other calls when the server seems unresponsive. - Review your own work (
/api/session/{id}/message) to see what you have said and done. - Check todos by reading your newest
todowritecall from the message history. - List skills (
/api/skill) when asked about your capabilities. - Check MCP status (
/api/mcp) when asked about connected tools or servers. - List agents (
/api/agent) to understand your current setup.
Files in this skill
1opencode-server-api skill questions
How do I install the opencode-server-api skill in Claude Code?
Run npx degit kevinlin/cowork-z/src-tauri/resources/skills/opencode-server-api ~/.claude/skills/opencode-server-api. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the opencode-server-api skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How can I check the health of the OpenCode server?
You can use the /api/info endpoint to retrieve the server version, PID, and URLs, which serves as a health check.
How do I access my todo list via the API?
There is no dedicated todo route; instead, you must read the message history in descending order, find the first 'todowrite' tool item, and extract the 'state.input.todos' field.
What should I do before calling any API endpoint?
You should always fetch the live OpenAPI spec first to ensure you have the correct routes, parameters, and response shapes.