# Send OpenCode CLI API Controller to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - Download the package from Yavira. - Extract it into a folder your agent can access. - Paste one of the prompts below and point your agent at the extracted folder. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "opencode-api-control-skill", "name": "OpenCode CLI API Controller", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/malek262/opencode-api-control-skill", "canonicalUrl": "https://clawhub.ai/malek262/opencode-api-control-skill", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/opencode-api-control-skill", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=opencode-api-control-skill", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "config.json", "README.md", "SKILL.md", "Reference/STATE_MANAGEMENT.md", "Reference/COMPLETE_EXAMPLES.md", "Reference/EVENTS_GUIDE.md" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/opencode-api-control-skill" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/opencode-api-control-skill", "downloadUrl": "https://openagent3.xyz/downloads/opencode-api-control-skill", "agentUrl": "https://openagent3.xyz/skills/opencode-api-control-skill/agent", "manifestUrl": "https://openagent3.xyz/skills/opencode-api-control-skill/agent.json", "briefUrl": "https://openagent3.xyz/skills/opencode-api-control-skill/agent.md" } } ``` ## Documentation ### 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 OpenCode server running (Preferred: bash ./scripts/start_server.sh) Configuration file exists: ./config.json Required scripts in ./scripts/ directory ### Configuration Read settings from ./config.json: BASE_URL=$(jq -r '.base_url' ./config.json) PROJECTS_DIR=$(jq -r '.projects_base_dir' ./config.json) ### 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: # 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) # Start task bash ./scripts/send_message.sh "Complex task" & # Monitor events (blocks until completion) bash ./scripts/monitor_session.sh Option 2: Intelligent polling # 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 # 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: Provider: Use default from config, or specify a provider (opencode, anthropic, gemini, etc.)? 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: # 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. ### Step 1: Verify Server # Check health curl -s "$BASE_URL/global/health" | jq # Expected: {"healthy": true, "version": "..."} ### Step 2: Update Providers Cache # 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: PROJECT_NAME="dashboard-app" PROJECT_PATH="$PROJECTS_DIR/$PROJECT_NAME" mkdir -p "$PROJECT_PATH" Existing Project: 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: SESSION_ID=$(bash ./scripts/create_session.sh "$PROJECT_PATH" "Session Title") ### Step 5: Save Session State # 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: # 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) # Start monitoring in background bash ./scripts/monitor_session.sh & # Or check status periodically bash ./scripts/check_status.sh ### Automatic (uses default from config.json) 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: # 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 ./scripts/send_message.sh "Build app" Planning phase: bash ./scripts/send_message.sh "Analyze requirements" "plan" Implementation phase: bash ./scripts/send_message.sh "Implement features" "build" ### Pattern 1: New Project from Scratch # 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 # 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 # 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 # 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: # 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/: # 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 ./scripts/get_diff.sh Get file content: curl -s "$BASE_URL/file/content?directory=$PROJECT_PATH&path=src/App.tsx" \\ jq -r '.content' List directory: 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: 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 TaskCommandUpdate providersbash ./scripts/update_providers.shCreate sessionbash ./scripts/create_session.sh "$PATH" "Title"Send messagebash ./scripts/send_message.sh "prompt"With providerbash ./scripts/send_message.sh "prompt" "provider" "model"Monitor progressbash ./scripts/monitor_session.shCheck statusbash ./scripts/check_status.shGet changesbash ./scripts/get_diff.shSave statebash ./scripts/save_state.sh "$SID" "$PATH"Load statesource ./scripts/load_state.shSave projectbash ./scripts/save_project.sh "name"Load projectbash ./scripts/load_project.sh "name"Select providerbash ./scripts/select_provider.sh "name" "model" ### Important Notes Always run from skill directory: Scripts use relative paths Update providers at workflow start: Ensures cache is fresh Create projects in PROJECTS_BASE_DIR: Configured in config.json Each session belongs to one project directory: Don't mix Load state before curl commands: Ensures variables are set Scripts handle authentication: No need to add headers manually ### Troubleshooting "No active session": # Load or create session first bash ./scripts/create_session.sh "$PROJECT_PATH" "Title" "Provider not found": # 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 | Repository: OpenCode-CLI-Controller ## Trust - Source: tencent - Verification: Indexed source record - Publisher: malek262 - Version: 1.1.0 ## Source health - Status: healthy - Source download looks usable. - Yavira can redirect you to the upstream package for this source. - Health scope: source - Reason: direct_download_ok - Checked at: 2026-04-30T16:55:25.780Z - Expires at: 2026-05-07T16:55:25.780Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/opencode-api-control-skill) - [Send to Agent page](https://openagent3.xyz/skills/opencode-api-control-skill/agent) - [JSON manifest](https://openagent3.xyz/skills/opencode-api-control-skill/agent.json) - [Markdown brief](https://openagent3.xyz/skills/opencode-api-control-skill/agent.md) - [Download page](https://openagent3.xyz/downloads/opencode-api-control-skill)