CLI client for OpenCode plugins and tools
npm install @promethean-os/opencode-clientTypeScript client for OpenCode with comprehensive session management, event processing, and context indexing capabilities.
``bash`
pnpm add @promethean-os/opencode-client
`typescript
import { spawnSession, listSessions, sendPrompt, listEvents } from '@promethean-os/opencode-client';
// Create a new session
const session = await spawnSession.execute({
title: 'Development Session',
message: 'Start working on TypeScript project',
});
const { session: sessionData } = JSON.parse(session);
console.log('Session created:', sessionData.id);
// Send a message to the session
const message = await sendPrompt.execute({
sessionId: sessionData.id,
content: 'Analyze the codebase for performance issues',
type: 'instruction',
});
console.log('Message sent:', JSON.parse(message));
// List all active sessions
const sessions = await listSessions.execute({ limit: 10 });
console.log('Active sessions:', JSON.parse(sessions));
`
- Create, list, and manage OpenCode sessions
- Real-time session status tracking
- Interactive messaging within sessions
- Session lifecycle management
- Comprehensive event tracking and querying
- Real-time event streaming
- Event filtering and aggregation
- Historical event analysis
- Full-text search across sessions, events, and messages
- Semantic search capabilities
- Context compilation for analysis
- Intelligent result ranking
- Full type safety with comprehensive type definitions
- Proper error handling and validation
- Modern ES6+ patterns and practices
- Extensible architecture for custom functionality
- Built-in plugins for common operations
- Tool registration and execution
- Cross-plugin communication
| Tool | Purpose | Example |
| ---------------- | ----------------------------- | -------------------------------------------------------- |
| spawnSession | Create new session | spawnSession.execute({title, message}) |listSessions
| | List sessions | listSessions.execute({limit: 20}) |sendPrompt
| | Send message to session | sendPrompt.execute({sessionId, content}) |listMessages
| | Get session messages | listMessages.execute({sessionId, limit: 50}) |closeSession
| | Close session | closeSession.execute({sessionId}) |listEvents
| | List system events | listEvents.execute({limit: 100}) |searchContext
| | Search across content | searchContext.execute({query, limit: 20}) |compileContext
| | Compile comprehensive context | compileContext.execute({query, includeSessions: true}) |
- API Reference - Complete API documentation for all functions and tools
- Development Guide - Setup, development workflows, and contribution guidelines
- Usage Examples - Comprehensive examples and workflows
- Troubleshooting Guide - Common issues and solutions
- OpenCode Client Integration - Comprehensive guide to OpenCode client integration
- TypeScript Compilation Fixes - Recent TypeScript fixes and type safety improvements
- Spawn Command - Quick session creation with spawn message
- Integration Guide - Integration patterns and best practices
- Indexer Service Guide - Search and context compilation documentation
- Plugin System Guide - Plugin development and management
- Unified Agent Management - High-level agent session management
- Node.js 18+ and TypeScript 5+
- OpenCode server running locally or accessible via network
- pnpm package manager
`typescript
// Configure OpenCode server URL (optional, defaults to localhost:4096)
process.env.OPENCODE_SERVER_URL = 'http://localhost:4096';
// Enable debug logging (optional)
process.env.DEBUG = 'opencode-client:*';
// Set authentication token (if required)
process.env.OPENCODE_AUTH_TOKEN = 'your-auth-token';
`
`typescript
async function manageSessions() {
// Create multiple sessions
const sessions = await Promise.all([
spawnSession.execute({
title: 'Code Review',
message: 'Review authentication module',
}),
spawnSession.execute({
title: 'Documentation',
message: 'Update API documentation',
}),
]);
// List all active sessions
const activeSessions = await listSessions.execute({ limit: 20 });
console.log('Active sessions:', JSON.parse(activeSessions));
}
`
`typescript
async function processEvents() {
// Get recent events
const events = await listEvents.execute({
limit: 100,
eventType: 'session.created',
});
const eventData = JSON.parse(events);
eventData.events.forEach((event) => {
console.log(Event: ${event.type} at ${new Date(event.timestamp)});`
});
}
`typescript
async function searchAndAnalyze() {
// Search for specific content
const searchResults = await searchContext.execute({
query: 'TypeScript compilation errors',
limit: 20,
includeMessages: true,
includeSessions: true,
});
// Compile comprehensive context
const context = await compileContext.execute({
query: 'security vulnerabilities',
includeSessions: true,
includeEvents: true,
includeMessages: true,
limit: 500,
});
return {
search: JSON.parse(searchResults),
context: JSON.parse(context),
};
}
`
`bashClone repository
git clone https://github.com/riatzukiza/promethean.git
cd promethean/packages/opencode-client
$3
`bash
Run all tests
pnpm testRun with coverage
pnpm test --coverageWatch mode
pnpm test --watch
`$3
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Ensure build passes
6. Submit a pull request
For detailed development guidelines, see the Development Guide.
Support and Troubleshooting
$3
1. TypeScript Compilation Errors: See TypeScript Compilation Fixes
2. Connection Issues: Ensure OpenCode server is running on port 4096
3. Session Not Found: Verify session ID is correct and session hasn't expired
4. Search Returns No Results: Check query syntax and available content
$3
- Check the Troubleshooting Guide for common issues
- Review the API Reference for detailed usage
- Enable debug logging:
process.env.DEBUG = 'opencode-client:*'
- Create an issue with detailed error information$3
`typescript
import { listSessions, listEvents } from '@promethean-os/opencode-client';async function healthCheck() {
try {
// Check session connectivity
const sessions = await listSessions.execute({ limit: 1 });
console.log('Sessions API healthy:', JSON.parse(sessions));
// Check event connectivity
const events = await listEvents.execute({ limit: 1 });
console.log('Events API healthy:', JSON.parse(events));
console.log('β
All systems operational');
} catch (error) {
console.error('β Health check failed:', error.message);
}
}
healthCheck();
`Architecture Overview
`
βββββββββββββββββββ ββββββββββββββββββββ βββββββββββββββββββ
β CLI Client βββββΆβ OpenCode API βββββΆβ Session Store β
β β β β β β
β β’ sessions β β β’ Sessions β β β’ Session Data β
β β’ events β β β’ Events β β β’ Event History β
β β’ messages β β β’ Messages β β β’ Message Log β
β β’ indexer β β β’ Indexer β β β’ Search Index β
βββββββββββββββββββ ββββββββββββββββββββ βββββββββββββββββββ
β β β
β ββββββββββββββββββββ β
ββββββββββββββββΆβ Plugin System ββββββββββββββ
β β
β β’ Agent Mgmt β
β β’ Cache β
β β’ Events β
β β’ Custom β
ββββββββββββββββββββ
``This project is licensed under GPL-3.0 License. See LICENSE file for details.
- @promethean-os/persistence: Data persistence layer
- @opencode-ai/plugin: OpenCode plugin framework
- @opencode-ai/sdk: OpenCode SDK
- @promethean-os/kanban: Task management and workflow integration