Skill: malek262/opencode-api-control-skill (version 1.1.0)

--- name: OpenCode-CLI-Controller description: A powerful skill to control Open Code CLI via a local web server API. Allows executing commands, managing sessions, and automating code generation remotely in the local network. version: 1.1.0 emoji: 🎛️ author: Malek-Rsh tags: - cli - api - automation - web-server - opencode metadata: openclaw: requires: bins: - curl - jq - bash install: | chmod +x scripts/*.sh if ! command -v jq &> /dev/null; then echo "Warning: jq is required but not installed." fi run: | echo "OpenCode Control Skill is ready for use." echo "Please ensure the OpenCode server is running on port 4099." --- # OpenCode CLI API Control > [!IMPORTANT] > **OPERATIONAL GUIDELINES**: > While you may use `ls` or basic file system checks to verify that files/directories exist, you are **EXPLICITLY PROHIBITED** from reading or modifying the project's source code files directly. > Your primary channel for task execution and progress monitoring is the **OpenCode API and the provided scripts**. ## Overview This skill provides a set of tools to programmatically interface with the Open Code CLI through its local web server API. It enables you to act as a **Supervisor/Orchestrator** who directs OpenCode to handle all coding, file operations, and quality checks. ## Core Mandate: Orchestrator vs. Executor - **You are NOT the Coder**: You do not write or verify code directly. OpenCode handles the implementation. - **You are the Orchestrator**: You send high-level instructions to OpenCode, monitor its progress, and report the outcome to the user. - **Trust the System**: OpenCode is responsible for its own file operations. Your job is to wait for it to finish and then check the *status* and *diff summary*, not the file contents. ## When to Use - User requests creating or managing projects through OpenCode - User asks for coding tasks, debugging, or code analysis via OpenCode - User wants AI-powered development with specific providers/models - User needs to manage multiple OpenCode sessions or monitor tasks ## Prerequisites 1. OpenCode server running (Preferred: `bash ./scripts/start_server.sh`) 2. Configuration file exists: `./config.json` 3. Required scripts in `./scripts/` directory ## Configuration Read settings from `./config.json`: ```bash BASE_URL=$(jq -r '.base_url' ./config.json) PROJECTS_DIR=$(jq -r '.projects_base_dir' ./config.json) ``` ## Important Agent Responsibilities ### Your Role as Orchestrator You are the **supervisor and communication bridge** between the user and OpenCode. **Operational Boundaries**: - ❌ **NEVER** read or edit the code files generated by OpenCode directly for development tasks. - ❌ **NEVER** try to fix or verify code logic by inspecting the project files yourself. - ✅ **MAY** use `ls` or simple directory checks only to confirm file existence if necessary. - ⚠️ **PREFER** using the provided scripts and API for all project-related information. **Required Workflow**: - ✅ **PRIMARY**: Use `monitor_session.sh` or `check_status.sh` to track progress. - ✅ **PRIMARY**: Use `get_diff.sh` to see a summary of what was changed. - ✅ **ALWAYS** report the results based on the API response or script output. - ✅ **TRUST** OpenCode's implementation of the requested features. ### Server Initialization Wait **CRITICAL**: After starting OpenCode web server, it takes **10-15 seconds** to fully initialize. You **MUST** verify server readiness before sending any requests. **Correct initialization sequence**: ```bash # Start server using the robust backgrounding script bash ./scripts/start_server.sh # 3. Now safe to proceed with operations bash ./scripts/update_providers.sh # ... continue workflow ``` **Never** send requests immediately after starting the server - always verify health first. ### Intelligent Task Monitoring For long-running tasks, use **smart monitoring** strategies: **Option 1: Event-based monitoring (Recommended)** ```bash # Start task bash ./scripts/send_message.sh "Complex task" & # Monitor events (blocks until completion) bash ./scripts/monitor_session.sh ``` **Option 2: Intelligent polling** ```bash # For environments where event streaming is unreliable bash ./scripts/send_message.sh "Build application" # Smart polling with exponential backoff SLEEP_TIME=2 MAX_SLEEP=30 while true; do STATUS=$(bash ./scripts/check_status.sh) if [ "$STATUS" = "idle" ]; then echo "✓ Task completed" break elif [ "$STATUS" = "busy" ]; then echo "⟳ Still working... (checking again in ${SLEEP_TIME}s)" sleep $SLEEP_TIME # Increase wait time (but cap at MAX_SLEEP) SLEEP_TIME=$((SLEEP_TIME < MAX_SLEEP ? SLEEP_TIME + 2 : MAX_SLEEP)) else echo "⚠ Unexpected status: $STATUS" break fi done ``` **Option 3: Timeout-based waiting** ```bash # For predictable task durations bash ./scripts/send_message.sh "Quick task" # Wait reasonable time before checking sleep 10 # Then check once if [ "$(bash ./scripts/check_status.sh)" = "idle" ]; then bash ./scripts/get_diff.sh fi ``` **Anti-patterns to AVOID**: - ❌ Checking status every 1-2 seconds (wastes resources) - ❌ Reading files repeatedly to see if task is done - ❌ Using `ls` or file system checks for progress - ❌ Making multiple API calls without waiting **Best practices**: - ✅ Use `monitor_session.sh` for real-time updates - ✅ Use exponential backoff for polling (start 2s, increase to 30s) - ✅ Estimate task duration and wait appropriately - ✅ Only check final results after confirmation of completion - ✅ Let OpenCode agents work independently - don't micromanage ## Task Initiation Protocol Before starting any task (new project, code analysis, debugging, etc.), **ask the user in ONE message**: > I'll help you with that. Two quick questions: > 1. **Provider**: Use default from config, or specify a provider (opencode, anthropic, gemini, etc.)? > 2. **Monitoring**: > - **Standard** (recommended): Send task → wait for completion summary → notify you when done (saves tokens) > - **Real-time**: Show live progress, file edits, and events as they happen (uses more tokens) > > How would you like to proceed? **Default if not specified**: Use config defaults + Standard mode. ### Why This Matters - **Standard mode**: Uses `send_message.sh` → waits → shows final summary. Efficient for most tasks. - **Real-time mode**: Uses `monitor_session.sh` with event streaming. Good for long/complex tasks where you want visibility. ### Example Response Handling - "Default provider, standard mode" → Proceed immediately - "Use Claude Sonnet, real-time" → Run `select_provider.sh` then `monitor_session.sh` - "Gemini Pro" → Find provider + ask monitoring preference if not specified --- ### Task Completion Verification When a task completes, get summary via: ```bash # Get file changes summary (not individual files) bash ./scripts/get_diff.sh # Output example: # added: src/App.tsx (+120/-0) # modified: package.json (+5/-2) # added: src/components/Dashboard.tsx (+89/-0) ``` This gives you all information needed to report to the user without reading actual file contents. **Only read specific files if**: - User explicitly asks to see code - User requests explanation of specific implementation - Debugging a reported issue Otherwise, trust the diff summary and OpenCode's implementation. ## Core Workflow ### Step 1: Verify Server ```bash # Check health curl -s "$BASE_URL/global/health" | jq # Expected: {"healthy": true, "version": "..."} ``` ### Step 2: Update Providers Cache ```bash # Run provider update script bash ./scripts/update_providers.sh ``` This caches **only connected providers** to `./providers.json`. ### Step 3: Create or Select Project **New Project**: ```bash PROJECT_NAME="dashboard-app" PROJECT_PATH="$PROJECTS_DIR/$PROJECT_NAME" mkdir -p "$PROJECT_PATH" ``` **Existing Project**: ```bash PROJECT_NAME="existing-app" PROJECT_PATH="$PROJECTS_DIR/$PROJECT_NAME" # Verify exists [ -d "$PROJECT_PATH" ] || { echo "Project not found"; exit 1; } ``` ### Step 4: Create Session Create a session in the project directory using the provided script: ```bash SESSION_ID=$(bash ./scripts/create_session.sh "$PROJECT_PATH" "Session Title") ``` ### Step 5: Save Session State ```bash # Use state management script bash ./scripts/save_state.sh "$SESSION_ID" "$PROJECT_PATH" ``` ### Step 6: Send Message Use the provided script to send prompts to the AI: ```bash # Use defaults from config bash ./scripts/send_message.sh "Your prompt here" # Or use a specific provider and model bash ./scripts/send_message.sh "Your prompt" "anthropic" "claude-sonnet-4-5" ``` ### Step 7: Monitor Progress (For Long Tasks) ```bash # Start monitoring in background bash ./scripts/monitor_session.sh & # Or check status periodically bash ./scripts/check_status.sh ``` ## Provider Selection ### Automatic (uses default from config.json) ```bash bash ./scripts/send_message.sh "Create app" ``` ### User Specifies Provider When the user specifies a provider (e.g., "use Gemini Pro" or "with Claude Sonnet"), use the search script: ```bash # Search for provider and model hints RESULT=$(bash ./scripts/select_provider.sh "gemini" "pro") # Returns: gemini gemini-3-pro # Extract and use the returned values PROVIDER_ID=$(echo "$RESULT" | cut -d' ' -f1) MODEL_ID=$(echo "$RESULT" | cut -d' ' -f2) bash ./scripts/send_message.sh "Your prompt" "$PROVIDER_ID" "$MODEL_ID" ``` ## Agent Selection **Default (no agent specified - recommended)**: ```bash bash ./scripts/send_message.sh "Build app" ``` **Planning phase**: ```bash bash ./scripts/send_message.sh "Analyze requirements" "plan" ``` **Implementation phase**: ```bash bash ./scripts/send_message.sh "Implement features" "build" ``` ## Common Patterns ### Pattern 1: New Project from Scratch ```bash # 1. Update providers bash ./scripts/update_providers.sh # 2. Create project directory mkdir -p "$PROJECTS_DIR/new-app" # 3. Create session SESSION_ID=$(bash ./scripts/create_session.sh "$PROJECTS_DIR/new-app" "New App") # 4. Send initial task bash ./scripts/send_message.sh "Create React app with TypeScript and Tailwind" # 5. Monitor progress bash ./scripts/monitor_session.sh ``` ### Pattern 2: Continue Existing Project ```bash # 1. Load saved project state bash ./scripts/load_project.sh "existing-app" # 2. Send new task bash ./scripts/send_message.sh "Add authentication feature" ``` ### Pattern 3: Multi-Phase Development ```bash # Phase 1: Planning bash ./scripts/create_session.sh "$PROJECT_PATH" "Planning" bash ./scripts/send_message.sh "Plan e-commerce platform" "plan" # Phase 2: Implementation bash ./scripts/send_message.sh "Implement the plan" "build" # Phase 3: Review bash ./scripts/get_diff.sh ``` ### Pattern 4: Use Specific Provider ```bash # User says: "Create dashboard using Claude Sonnet" # 1. Select provider PROVIDER_MODEL=$(bash ./scripts/select_provider.sh "claude" "sonnet") PROVIDER_ID=$(echo "$PROVIDER_MODEL" | cut -d' ' -f1) MODEL_ID=$(echo "$PROVIDER_MODEL" | cut -d' ' -f2) # 2. Create project and session mkdir -p "$PROJECTS_DIR/dashboard" SESSION_ID=$(bash ./scripts/create_session.sh "$PROJECTS_DIR/dashboard" "Dashboard") # 3. Send with selected provider bash ./scripts/send_message.sh "Create dashboard" "$PROVIDER_ID" "$MODEL_ID" ``` ## Event Monitoring For long-running tasks, monitor events: ```bash # Start monitoring (shows progress in real-time) bash ./scripts/monitor_session.sh # This will: # - Show text deltas as they're generated # - Display status changes (busy/idle) # - Show final token count and cost # - Exit when task completes ``` ## State Management All session state is saved in `./state/`: ```bash # Save current session bash ./scripts/save_state.sh "$SESSION_ID" "$PROJECT_PATH" # Load state (sets environment variables) source ./scripts/load_state.sh echo $SESSION_ID echo $PROJECT_PATH # Save project-specific state bash ./scripts/save_project.sh "project-name" # Load project-specific state bash ./scripts/load_project.sh "project-name" # List all saved projects ls -1 ./state/*.json | grep -v current.json | xargs -n1 basename .json ``` ## File Operations Get session changes: ```bash bash ./scripts/get_diff.sh ``` Get file content: ```bash curl -s "$BASE_URL/file/content?directory=$PROJECT_PATH&path=src/App.tsx" \ jq -r '.content' ``` List directory: ```bash curl -s "$BASE_URL/file?directory=$PROJECT_PATH&path=src" \ jq -r '.[] | "\(.type): \(.path)"' ``` ## Error Handling All scripts return proper exit codes: - `0` = Success - `1` = Error Check script status: ```bash if bash ./scripts/send_message.sh "prompt"; then echo "Success" else echo "Failed - check server or authentication" fi ``` ## Authentication This skill assumes the OpenCode server is running in a trusted local environment and does not use password authentication by default. ## Quick Reference | Task | Command | |------|---------| | Update providers | `bash ./scripts/update_providers.sh` | | Create session | `bash ./scripts/create_session.sh "$PATH" "Title"` | | Send message | `bash ./scripts/send_message.sh "prompt"` | | With provider | `bash ./scripts/send_message.sh "prompt" "provider" "model"` | | Monitor progress | `bash ./scripts/monitor_session.sh` | | Check status | `bash ./scripts/check_status.sh` | | Get changes | `bash ./scripts/get_diff.sh` | | Save state | `bash ./scripts/save_state.sh "$SID" "$PATH"` | | Load state | `source ./scripts/load_state.sh` | | Save project | `bash ./scripts/save_project.sh "name"` | | Load project | `bash ./scripts/load_project.sh "name"` | | Select provider | `bash ./scripts/select_provider.sh "name" "model"` | ## Important Notes 1. **Always run from skill directory**: Scripts use relative paths 2. **Update providers at workflow start**: Ensures cache is fresh 3. **Create projects in PROJECTS_BASE_DIR**: Configured in config.json 4. **Each session belongs to one project directory**: Don't mix 5. **Load state before curl commands**: Ensures variables are set 6. **Scripts handle authentication**: No need to add headers manually ## Troubleshooting **"No active session"**: ```bash # Load or create session first bash ./scripts/create_session.sh "$PROJECT_PATH" "Title" ``` **"Provider not found"**: ```bash # Update providers cache bash ./scripts/update_providers.sh # Check available providers jq -r '.providers[] | .id' ./providers.json ``` **"HTML response instead of JSON"**: - Missing `directory` parameter - Check: Are you using full PROJECT_PATH? ## Advanced Usage For complex workflows, state management, or advanced patterns, see: - `Reference/STATE_MANAGEMENT.md` - Advanced state handling - `Reference/PROVIDERS_REFERENCE.md` - Provider selection details - `Reference/EVENTS_GUIDE.md` - Event monitoring patterns - `Reference/COMPLETE_EXAMPLES.md` - Full workflow examples - `Reference/API_QUICK_REFERENCE.md` - Raw API endpoints ## Directory Structure ``` opencode-api-control/ ├── SKILL.md # This file ├── config.json # Configuration ├── providers.json # Connected providers cache ├── scripts/ # Helper scripts │ ├── update_providers.sh │ ├── create_session.sh │ ├── send_message.sh │ ├── monitor_session.sh │ ├── check_status.sh │ ├── get_diff.sh │ ├── save_state.sh │ ├── load_state.sh │ ├── save_project.sh │ ├── load_project.sh │ └── select_provider.sh ├── state/ # Session state │ ├── current.json │ └── project-name.json └── Reference/ # Reference docs ├── STATE_MANAGEMENT.md ├── PROVIDERS_REFERENCE.md ├── EVENTS_GUIDE.md ├── COMPLETE_EXAMPLES.md └── API_QUICK_REFERENCE.md ``` --- **Author:** [Malek RSH](https://github.com/malek262) | **Repository:** [OpenCode-CLI-Controller](https://github.com/malek262/opencode-api-control-skill)

path: config.json
content: base_url: http://127.0.0.1:4099
projects_base_dir: /home/user/projects-location
default_provider: opencode
default_model: kimi-k2.5-free

Security scan verdicts — ClawScan: clean | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)