https://github.com/nycksw/opencode-manager
Python classes for orchestrating opencode server
https://github.com/nycksw/opencode-manager
ai opencode python
Last synced: about 2 months ago
JSON representation
Python classes for orchestrating opencode server
- Host: GitHub
- URL: https://github.com/nycksw/opencode-manager
- Owner: nycksw
- License: mit
- Created: 2025-09-03T00:04:52.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-11-21T12:32:17.000Z (about 2 months ago)
- Last Synced: 2025-11-21T14:30:29.624Z (about 2 months ago)
- Topics: ai, opencode, python
- Language: Python
- Homepage:
- Size: 109 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# opencode-manager
> **EXPERIMENTAL!**! This was proof of concept code for an alpha version of opencode's SDK/API. Don't use this for anything real. This uses a Python SDK generated with [openapi-python-client](https://github.com/openapi-generators/openapi-python-client) with some minor bug-fixes. The [Stainless SDK](https://github.com/sst/opencode-sdk-python) is probably much cleaner now.
**opencode-manager** is designed to help orchestrate multiple AI agents working in parallel to solve complex tasks. The system manages 5-10 concurrent opencode sessions within the same headless server, each running an independent agent that can be monitored and controlled by an external coordination system. This project provides the classes for such a system.
**Complete XDG/Config/Data Isolation:** Server instances run in fully isolated environments, never touching your personal files or directories. [Learn more →](ISOLATION.md)
## Version Compatibility
The system automatically manages opencode versions for compatibility:
| Component | Version | Notes |
|-----------|---------|-------|
| opencode-ai SDK | 0.1.0a36 | Latest available SDK |
| opencode binary | v0.5.28 | Automatically downloaded via `make setup` |
| Python | 3.9+ | Type hints require 3.9+ |
**Important:** opencode v0.6.0+ has breaking API changes incompatible with the current SDK. See [API_CHANGES.md](API_CHANGES.md) for details.
## Prerequisites
- [`uv`](https://github.com/astral-sh/uv) for Python package management
- Python 3.9 or higher
- Node.js/npm (for development tools like pyright)
```shell
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
```
## Quick Start
```shell
# Clone and setup
git clone
cd opencode-manager
# Install dependencies and setup everything (opencode binary + test resources)
make install
make setup
# Run tests
make test
# Run example
make example
```
## Installation
```shell
# Clone the repository
git clone
cd opencode-manager
# Install all dependencies (Python + dev tools)
make install
# Setup everything (download opencode binary + configure test resources)
make setup
# Or setup components individually:
make setup-bin # Download compatible opencode binary to ./bin
make setup-test # Setup test resources in ./test_resources
# Or manually:
uv sync # Python dependencies
npm install # Dev tools (pyright)
python scripts/download_opencode.py # Download recommended version
```
## Usage
See [`examples/basic_usage.py`](examples/basic_usage.py) for a complete working example that demonstrates:
- Server initialization with isolated environment
- Session creation and management
- Sending messages and receiving responses
- Proper resource cleanup
Run the example with:
```shell
make example
# Or directly:
uv run python examples/basic_usage.py
```
## Running Tests
### Unit Tests
```shell
# Run unit tests (no API calls, no costs)
make test
# Or explicitly:
make test-unit
```
### Integration Tests
**[!] Warning:** Integration tests make REAL API calls and will incur costs!
Integration tests use real opencode server instances and show detailed progress.
They will consume API credits from your configured provider (OpenAI, Anthropic, etc.).
First, ensure test resources are setup (automatically done by `make setup`):
```shell
make setup-test # Only needed if you haven't run `make setup`
```
Then run tests:
```shell
# Run integration tests (shows test names and detailed operation progress)
make test-integration
# Or run directly with less output (hide operation details)
uv run python -m pytest tests/test_integration.py --capture=sys
```
### Run All Tests
```shell
# Run all tests
make test-all
# Run all tests except integration (using Python module syntax)
uv run python -m pytest -m "not integration"
```
## Development
```shell
# Install development dependencies
make install
# Format code
make format
# Lint
make lint
# Type check
make typecheck
```
## Running Examples
```shell
# Run the basic usage example
make example
# Or run directly
uv run python examples/basic_usage.py
```
## API Specification
The project tracks the OpenAPI specification and version of the opencode binary:
```shell
# Update API spec and version (runs integration test)
make update-api-spec
# Check if API spec has changed (useful in CI)
make check-api-spec
```
The system automatically uses the compatible opencode version from `./bin/opencode` with full isolation.
## Features
- **Complete isolation** - Server NEVER touches your real home or XDG directories
- Isolated XDG-compliant environments for each server instance
- Full server lifecycle management (start/stop/health checks)
- Session management (create/list/delete/abort)
- Message tracking with read cursors
- Automatic port discovery
- Comprehensive logging
- Automatic selection of cheapest models for testing (Haiku, GPT-4o-mini, Gemini Flash)
- Comprehensive isolation testing and verification
## Requirements
- Python 3.9+
- `opencode-ai` SDK (automatically installed)
- `opencode` binary (must be available)
- `uv` package manager