OpenCode

Overview

OpenCode is an open source AI coding agent that runs in your terminal, IDE, or desktop. It provides a server mode that exposes an OpenAPI specification, allowing developers to build custom clients and integrations.

Using OpenCode

For general information about OpenCode features, privacy, and ecosystem, see references/overview.md.

Building Client Applications

To build a client application that interacts with OpenCode, you should communicate with the OpenCode HTTP server.

Quick Start

See scripts/simple_client.py for a complete Python example of connecting, creating a session, and sending a message.

Client Development Guide

For detailed patterns on session management, messaging loops, and event streaming, see references/client_guide.md.

Server Connection

The server typically runs on http://127.0.0.1:4096. You can start it with opencode serve.

API Reference

For a complete list of available endpoints, see references/api.md.

The API covers:

• Sessions: Create, manage, and interact with coding sessions.
• Messages: Send prompts and receive responses.
• Files: Read and search files in the workspace.
• Projects: Manage projects.
• TUI Control: Control the Terminal UI programmatically.

Common Workflows

1. Connecting to a Session

To interact with an existing session or create a new one:

• List sessions: GET /session
• Create session: POST /session

2. Sending a Message

To send a prompt to the agent:

• POST /session/:id/message with the prompt content.

3. Reading Files

To read file content:

• GET /file/content?path=<path>

Resources

scripts/

• simple_client.py: A Python script demonstrating basic client interactions (connect, create session, send message).

references/

• overview.md: General overview of OpenCode features and ecosystem.
• api.md: Detailed API reference for the OpenCode HTTP server.
• client_guide.md: Best practices and patterns for building OpenCode clients.