# Opencode Server Api

> A Claude skill from kevinlin/cowork-z.

- **Type:** Skill
- **Install:** `agentstack add skill-kevinlin-cowork-z-opencode-server-api`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kevinlin](https://agentstack.voostack.com/s/kevinlin)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kevinlin](https://github.com/kevinlin)
- **Source:** https://github.com/kevinlin/cowork-z/tree/main/src-tauri/resources/skills/opencode-server-api

## Install

```sh
agentstack add skill-kevinlin-cowork-z-opencode-server-api
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# OpenCode Server API

This skill gives you access to the OpenCode server REST API for self-introspection — checking your own health, session state, message history, todos, configuration, skills, MCP status, and performing lightweight config updates.

## Authentication

The server port is provided in your system prompt inside the `` block. The basic-auth password is already present in your shell environment as `OPENCODE_SERVER_PASSWORD` — your shell expands it locally when you run a command. All requests require HTTP basic auth:

```bash
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/
```

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 specific endpoint, you MUST first fetch and parse the live OpenAPI specification.** The spec is the source of truth for all available endpoints, request/response schemas, and query parameters. The endpoint summaries in this skill are a convenient reference, but the server's own spec may be newer or more complete.

```bash
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/doc
```

This returns the full OpenAPI JSON spec. Parse it to understand the exact request format, required parameters, and response shapes before invoking any endpoint. **Do not guess or rely solely on the examples below — always verify against `/doc` first.**

---

## Endpoint Reference

### GET /global/health

Check server health and get the OpenCode version.

```bash
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/global/health
```

**Response:**
```json
{ "healthy": true, "version": "1.1.48" }
```

---

### GET /config

Read the current server configuration (model, agents, permissions, MCP servers, etc.).

**Query parameters:**
- `directory` (optional) — project directory to scope the config

```bash
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/config
```

**Response:** Full config object including `model`, `default_agent`, `enabled_providers`, `permission`, `agent`, `mcp`, etc.

---

### PATCH /config

Update configuration at runtime (e.g., switch model, update permissions, modify MCP servers).

**Query parameters:**
- `directory` (optional) — project directory to scope the config

**Body:** Partial config object — only include fields you want to change.

```bash
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-20250514"}' \
  http://localhost:$PORT/config
```

**Response:** Updated full config object.

**Note:** PATCH /config may cause the server to dispose and recreate its instance. This is normal and the server will recover automatically.

---

### GET /session

List all sessions.

**Query parameters:**
- `directory` (optional) — filter by project directory
- `roots` (optional) — if `true`, only return root sessions
- `limit` (optional) — max number of sessions to return

```bash
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/session
```

**Response:**
```json
[
  {
    "id": "ses_abc123",
    "slug": "my-session",
    "projectID": "proj_1",
    "directory": "/path/to/project",
    "title": "Session title",
    "version": "1",
    "time": { "created": 1700000000, "updated": 1700000100 }
  }
]
```

---

### GET /session/{id}

Get details of a specific session.

**Query parameters:**
- `directory` (optional) — project directory

```bash
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/session/ses_abc123
```

**Response:** Single session object (same shape as list items above).

---

### GET /session/{id}/message

Read back message history for a session.

**Query parameters:**
- `directory` (optional) — project directory
- `limit` (optional) — max number of messages to return

```bash
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/session/ses_abc123/message
```

**Response:**
```json
[
  {
    "info": { "id": "msg_1", "role": "assistant", "sessionID": "ses_abc123" },
    "parts": [{ "type": "text", "text": "Here is my response..." }]
  }
]
```

---

### GET /session/{id}/todo

Get todo items for a session.

```bash
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/session/ses_abc123/todo
```

**Response:**
```json
[
  { "id": "todo_1", "content": "Implement feature X", "status": "in_progress", "priority": "high" },
  { "id": "todo_2", "content": "Write tests", "status": "pending", "priority": "medium" }
]
```

Todo statuses: `pending`, `in_progress`, `completed`, `cancelled`
Todo priorities: `high`, `medium`, `low`

---

### GET /skill

List available skills.

```bash
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/skill
```

**Response:** Array of skill objects, each with `name`, `description`, `location`, and `content` fields.

---

### GET /mcp

Check MCP server connection status.

```bash
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/mcp
```

**Response:** Map of MCP server names to their connection status:
```json
{ "my-mcp-server": { "status": "connected" } }
```

---

### GET /permission

List pending permission requests.

```bash
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/permission
```

**Response:**
```json
[
  {
    "id": "per_abc",
    "sessionID": "ses_abc123",
    "permission": "bash",
    "patterns": ["ls -la"],
    "metadata": { "command": "ls -la" },
    "always": []
  }
]
```

---

### GET /question

List pending question requests.

```bash
curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/question
```

**Response:**
```json
[
  {
    "id": "que_abc",
    "sessionID": "ses_abc123",
    "questions": [
      { "question": "Which option?", "options": [{ "label": "A" }, { "label": "B" }] }
    ]
  }
]
```

---

## Usage Guidance

- **Check health** (`GET /global/health`) to verify the server is responsive before making other calls.
- **Inspect your own session** (`GET /session/{id}`, `GET /session/{id}/message`) to review what you've said and done so far.
- **Check todos** (`GET /session/{id}/todo`) to see your current task progress.
- **List skills** (`GET /skill`) when the user asks about your capabilities or available skills.
- **Check MCP status** (`GET /mcp`) when the user asks about connected tools or MCP servers.
- **Switch model** (`PATCH /config` with `{"model": "..."}`) if the user asks you to change the AI model.
- **Read config** (`GET /config`) to understand your current setup (active model, permissions, agents).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kevinlin](https://github.com/kevinlin)
- **Source:** [kevinlin/cowork-z](https://github.com/kevinlin/cowork-z)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kevinlin-cowork-z-opencode-server-api
- Seller: https://agentstack.voostack.com/s/kevinlin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.