skill

opencode-api

A Dart package that wraps the opencode.ai API using retrofit for type-safe HTTP requests.

cdavis-code/opencode_apicommunitylistedunreviewed

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/cdavis-code/opencode_api itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 26, 2026

opencode_api

A Dart package that wraps the opencode.ai API using retrofit for type-safe HTTP requests.

Quick Start
Features
Configuration
API Services
Migration from OpencodeClient
Documentation
Error Handling
Running the Generator
Contributors
Support
License

Quick Start

import 'package:opencode_api/opencode_api.dart';

void main() async {
  // Connect to the opencode server
  final opencode = await Opencode.connect(
    username: 'opencode',
    password: 'your-password',
    baseUrl: 'http://localhost:4096'
  );

  // Use service groups to access API endpoints
  final health = await opencode.global.getHealth();
  print('Server healthy: ${health.healthy}');
  
  // List sessions
  final sessions = await opencode.session.getSessions();
  print('Found ${sessions.length} sessions');
}

Features

Type-safe API client - Uses retrofit for compile-time API contracts
Service-oriented architecture - Organized API endpoints into logical service groups
Comprehensive endpoints - Covers all opencode.ai API endpoints
Secure error handling - Custom exceptions with user-friendly messages, no implementation leaks
Built-in logging - Uses logger package with platform-aware conditional imports
Easy authentication - HTTP Basic Auth support

Configuration

Variable	Description	Default
`baseUrl`	Server URL	`http://localhost:4096`
`username`	Auth username	`opencode`
`password`	Auth password	(required)

API Services

The Opencode object provides access to the following service groups:

Global

Method	Description	Response
`getHealth()`	Get server health and version	`HealthResponse`
`getGlobalEvents()`	Get global events (SSE stream)	`Stream<String>`

Project

Method	Description	Response
`getProjects()`	List all projects	`List<Project>`
`getCurrentProject()`	Get the current project	`Project`

Path & VCS

Method	Description	Response
`getPath()`	Get the current path	`PathResponse`
`getVcs()`	Get VCS info for the current project	`VcsResponse`

Instance

Method	Description	Response
`disposeInstance()`	Dispose the current instance	`bool`

Config

Method	Description	Response
`getConfig()`	Get config info	`ConfigResponse`
`updateConfig(body)`	Update config	`ConfigResponse`
`getConfigProviders()`	List providers and default models	`ConfigProvidersResponse`

Provider

Method	Description	Response
`getProviders()`	List all providers	`ProviderListResponse`
`getProviderAuth()`	Get provider authentication methods	`ProviderAuthMethodsResponse`
`authorizeProvider(id, body)`	Authorize a provider using OAuth	`ProviderAuthAuthorization`
`providerOAuthCallback(id, body)`	Handle OAuth callback for a provider	`bool`

Session

Method	Description	Response
`getSessions()`	List all sessions	`List<Session>`
`createSession(body)`	Create a new session	`Session`
`getSessionStatus()`	Get session status for all sessions	`Map<String, SessionStatus>`
`getSession(id)`	Get session details	`Session`
`deleteSession(id)`	Delete a session and all its data	`bool`
`updateSession(id, body)`	Update session properties	`Session`
`getSessionChildren(id)`	Get a session's child sessions	`List<Session>`
`getSessionTodo(id)`	Get the todo list for a session	`List<Todo>`
`initSession(id, body)`	Analyze app and create AGENTS.md	`bool`
`forkSession(id, body)`	Fork an existing session at a message	`Session`
`abortSession(id)`	Abort a running session	`bool`
`shareSession(id)`	Share a session	`Session`
`unshareSession(id)`	Unshare a session	`Session`
`getSessionDiff(id, messageID?)`	Get the diff for this session	`List<FileDiff>`
`summarizeSession(id, body)`	Summarize the session	`bool`
`revertMessage(id, body)`	Revert a message	`bool`
`unrevertMessages(id)`	Restore all reverted messages	`bool`
`respondToPermissionRequest(id, permissionID, body)`	Respond to a permission request	`bool`

Messages (via Session Service)

Method	Description	Response
`getMessages(id, limit?)`	List messages in a session	`List<MessageWithParts>`
`sendMessage(id, body)`	Send a message and wait for response	`MessageWithParts`
`getMessage(id, messageID)`	Get message details	`MessageWithParts`
`sendMessageAsync(id, body)`	Send a message asynchronously (no wait)	`void`
`executeCommand(id, body)`	Execute a slash command	`MessageWithParts`
`runShell(id, body)`	Run a shell command	`MessageWithParts`

Commands

Method	Description	Response
`getCommands()`	List all commands	`List<Command>`

Files

Method	Description	Response
`findInFiles(pattern)`	Search for text in files	`List<FindResult>`
`findFiles(query)`	Find files and directories by name	`List<String>`
`findSymbols(query)`	Find workspace symbols	`List<Symbol>`
`listFiles(path?)`	List files and directories	`List<FileNodeResponse>`
`getFileContent(path)`	Read a file	`FileContentResponse`
`getFileStatus()`	Get status for tracked files	`List<FileStatus>`

Tools (Experimental)

Method	Description	Response
`getToolIds()`	List all tool IDs	`ToolIDs`
`getTools(provider?, model?)`	List tools with JSON schemas for a model	`ToolList`

LSP, Formatters & MCP

Method	Description	Response
`getLspStatus()`	Get LSP server status	`List<LSPStatus>`
`getFormatterStatus()`	Get formatter status	`List<FormatterStatus>`
`getMcpStatus()`	Get MCP server status	`Map<String, MCPStatus>`
`addMcpServer(body)`	Add MCP server dynamically	`MCPStatus`

Agents

Method	Description	Response
`getAgents()`	List all available agents	`List<Agent>`

Logging

Method	Description	Response
`writeLog(body)`	Write log entry	`bool`

TUI

Method	Description	Response
`tuiAppendPrompt(body)`	Append text to the prompt	`bool`
`tuiOpenHelp()`	Open the help dialog	`bool`
`tuiOpenSessions()`	Open the session selector	`bool`
`tuiOpenThemes()`	Open the theme selector	`bool`
`tuiOpenModels()`	Open the model selector	`bool`
`tuiSubmitPrompt()`	Submit the current prompt	`bool`
`tuiClearPrompt()`	Clear the prompt	`bool`
`tuiExecuteCommand(body)`	Execute a command	`bool`
`tuiShowToast(body)`	Show toast	`bool`
`tuiControlNext()`	Wait for the next control request	`ControlRequest`
`tuiControlResponse(body)`	Respond to a control request	`bool`

Auth

Method	Description	Response
`setAuth(id, body)`	Set authentication credentials	`bool`

Events

Method	Description	Response
`getEvents()`	Get events (SSE stream)	`Stream<String>`

Migration from OpencodeClient

The old OpencodeClient is deprecated but still available for backward compatibility. Here's how to migrate:

Old API (Deprecated)

final dio = OpencodeClient.createDio(username: 'user', password: 'pass');
final client = OpencodeClient(dio);
final health = await client.getHealth();

New API (Recommended)

final opencode = await Opencode.connect(
  username: 'user', 
  password: 'pass'
);
final health = await opencode.global.getHealth();

Documentation

Error Handling

The package provides user-friendly error messages without exposing implementation details:

try {
  final sessions = await opencode.session.getSessions();
} catch (e) {
  if (e is OpencodeException) {
    print(e.userMessage); // Safe for users
  }
}

Running the Generator

After changes to API definitions:

dart run build_runner build --delete-conflicting-outputs

Contributors

Thanks to all the contributors who have helped make this package better!

cdavis-code - Author and maintainer

Support

If you find this package helpful, consider supporting its development:

License

MIT - See LICENSE