~/docs/sessions

Sessions

Conversations with OpenCode for building and iterating on services.

A session is a conversation with the OpenCode agent, scoped to one service directory. Sessions retain full context from earlier messages, making them ideal for iterative development on the same feature.

When to Create vs. Reuse

Default to a fresh session for a clean context. Only reuse when the work is a direct continuation — same feature, bug fix, or iteration.

✅ Create fresh — New feature, new service, unrelated change

🔄 Reuse — Bug fix, tweaking the same feature, code review follow-up

Writing Session Messages

Session messages are engineering briefs. They must be precise and complete. Every message should include:

  • What to build and how it works
  • All endpoints to register (method + path)
  • Exact request/response JSON shapes
  • Every secret the service needs
  • UI details if applicable (Fresh framework, deno:sqlite)

Example Session Message

A complete session message for a SQLite-backed API service:

text
Build a Deno HTTP service backed by SQLite:
- POST /query — accepts { sql: string, params?: unknown[] }, executes query, returns { rows: unknown[], duration_ms: number }
- GET /tables — returns { tables: string[] }
- Database file: ./data.db (create if not exists, use deno:sqlite)
- Handle SQL errors gracefully: return { error: string } with status 400
- Register POST /query and GET /tables as service endpoints

Session Lifecycle

1Orchestrator calls manage_opencode_sessions to create or find a session
2The session is linked to a specific service directory
3Messages are sent via manage_opencode_messages
4OpenCode writes code and registers endpoints/secrets
5When the session goes idle, the service auto-deploys

Proxy-Aware Code

OpenCode is trained to write code that works through the Next.js proxy. It handles server-side routing with endsWith instead of exact path matching, client-side URL construction with<base> tags, and HTTP short polling instead of WebSocket.

That covers all the core concepts. Head back to the overview to explore more.

← Back to overview