code-yeongyu/oh-my-openagent / .agents/skills/opencode-qa
opencode-qa
VerifiedQA opencode itself, per case: verify the CLI/terminal (opencode run, db, serve, export), prove a specific plugin hook/action/event fired via the SSE event stream, smoke-test the TUI under tmux, and investigate sessions in opencode's SQLite DB by id, title/name, or message text. Ships tested helper scripts (each with a --self-test) plus per-domain references. Use whenever someone wants to QA, smoke-test, verify, or debug opencode's CLI, HTTP server, plugin hooks/events, or TUI, or to find/inspect opencode sessions in the database. Triggers: opencode qa, qa opencode, test opencode, verify opencode hook, opencode session db, find opencode session by id/name/text, opencode tui test, opencode server health, opencode event stream.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.3 KB |
| references/cli-commands.md | markdown | 3.8 KB |
| references/db-investigation.md | markdown | 5.8 KB |
| references/docker-qa.md | markdown | 3.2 KB |
| references/events-hooks.md | markdown | 4.5 KB |
| references/sdk.md | markdown | 4.1 KB |
| references/server-api.md | markdown | 6.5 KB |
| references/testing-harness.md | markdown | 6.2 KB |
| references/tui-tmux.md | markdown | 4.0 KB |
| scripts/db-session-by-id.shexecutable | script | 1.7 KB |
| scripts/db-session-by-name.shexecutable | script | 1.9 KB |
| scripts/db-session-by-text.shexecutable | script | 6.6 KB |
| scripts/export-roundtrip.shexecutable | script | 2.8 KB |
| scripts/lib/common.shexecutable | script | 9.5 KB |
| scripts/lib/fake-openai-branches.mjs | script | 1.2 KB |
| scripts/lib/fake-openai-events.mjs | script | 2.3 KB |
| scripts/lib/fake-openai-server.mjsexecutable | script | 3.7 KB |
| scripts/lsp-e2e.shexecutable | script | 134.1 KB |
| scripts/serve-wake-split-probe.shexecutable | script | 38.2 KB |
| scripts/server-smoke.shexecutable | script | 2.1 KB |
| scripts/sse-hook-probe.shexecutable | script | 4.4 KB |
| scripts/tui-smoke.shexecutable | script | 3.6 KB |
references/sdk.md
View on GitHub# opencode SDK (@opencode-ai/sdk) - reference only
A TypeScript/Bun way to drive opencode for QA. Prefer the tested CLI/curl scripts for portability; reach for the SDK when you want typed access from a Bun script.
> IMPORTANT: method signatures differ between SDK versions and between the published docs and the generated client. ALWAYS check the installed version's types (node_modules/@opencode-ai/sdk) before relying on a signature, and verify against `GET /doc` (the OpenAPI spec the SDK is generated from).
## Entry points and exports
Package `@opencode-ai/sdk` subpath exports:
- `.` (src/index.ts)
- `./client`
- `./server`
- `./v2` (src/v2/index.ts)
- `./v2/client`
- `./v2/server`
- `./v2/gen/client`
Root and v2 entries export `createOpencode()`, `createOpencodeClient(...)`, `createOpencodeServer(...)`.
`createOpencodeServer()` spawns `opencode serve ...` and waits for the startup line. `createOpencodeClient({ baseUrl })` wraps the generated client, rewrites directory/workspace headers, installs error interception.
## Two ways to connect
```ts
import { createOpencodeClient, createOpencodeServer } from "@opencode-ai/sdk/v2"
// A) embedded server (spawns opencode serve)
const server = await createOpencodeServer()
const client = createOpencodeClient({ baseUrl: server.url })
// ... use client ...
server.close()
// B) connect to an already-running server
const client2 = createOpencodeClient({ baseUrl: "http://127.0.0.1:4096" })
```
## Client namespaces
Top-level on OpencodeClient:
auth, app, global, event, config, experimental, tool, worktree, find, file, instance, path, vcs, command, lsp, formatter, mcp, project, pty, question, permission, provider, session, part, sync, v2, tui.
## Useful methods (shapes vary by version)
- `client.global.health()`, `client.global.event()`
- `client.app.log(...)`, `client.app.agents(...)`, `client.app.skills(...)`
- `client.config.get()`, `client.config.providers()`
- `client.event.subscribe()` - SSE on /event; iterate `for await (const event of events.stream) { event.type, event.properties }`
- `client.session` (legacy surface): list, create, status, get, update, delete, children, todo, diff, messages, message, deleteMessage, prompt, promptAsync, command, shell, fork, abort, init, share, unshare, summarize, revert, unrevert
- `client.v2.session` (newer read/stream surface): list, prompt, compact, wait, context, messages
- `client.part.delete(...)`, `client.part.update(...)`
## Minimal QA snippet
Arg shapes may differ by version. Treat this as a starting point, not a contract.
```ts
import { createOpencodeClient, createOpencodeServer } from "@opencode-ai/sdk/v2"
const server = await createOpencodeServer()
const client = createOpencodeClient({ baseUrl: server.url })
try {
const session = await client.session.create({ title: "QA session" })
await client.session.promptAsync({
sessionID: session.id,
parts: [{ type: "text", text: "Say hello in one line." }],
})
const sessions = await client.session.list({ limit: 10 })
console.log(sessions[0]?.title)
const messages = await client.v2.session.messages({
sessionID: session.id,
limit: 20,
})
console.log(messages.items.length)
} finally {
server.close()
}
```
## Key types
- Legacy Session: id, slug, projectID, directory, title, version, time.created/updated, optional workspaceID, path, parentID, summary, cost, tokens, share, agent, model, metadata, permission, revert.
- Message = UserMessage | AssistantMessage (role "user" | "assistant"; assistant adds time.completed?, modelID, providerID, agent, tokens, finish?, error?).
- Part union: TextPart, ReasoningPart, FilePart, ToolPart, StepStartPart, StepFinishPart, SnapshotPart, PatchPart, AgentPart, RetryPart, CompactionPart, SubtaskPart.
## How it is generated
`packages/sdk/js/script/build.ts` runs `bun dev generate > openapi.json` from the opencode repo, feeds it to `@hey-api/openapi-ts.createClient`, writes output to `packages/sdk/js/src/v2/gen`, patches an SSE generic, prettifies and typechecks. Regenerate with `./packages/sdk/js/script/build.ts`.
---
For version-stable QA, prefer the curl/CLI scripts in this skill; cross-check any SDK call against `GET /doc`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |