opencode-client

OpenCode CLI for submitting coding tasks, managing sessions, delegating work to coding agents, checking status, and configuring OpenCode settings.

Security Scan

The SKILL.md expects and instructs use of an external 'oho' CLI and reading/attaching local files and doing auth flows, but the skill declares no required binary, no install, and no credentials — these mismatches could enable accidental data exposure or hide missing setup steps.

Purpose & Capability

The skill's stated purpose is an OpenCode CLI client, and the instructions repeatedly call a binary named 'oho' and describe auth/provider operations — but the metadata lists no required binaries, no install spec, and no credentials. A CLI-focused skill should declare the 'oho' binary (or provide an install) and required auth variables; that mismatch is incoherent.

Instruction Scope

The SKILL.md instructs sending local files (examples: /var/log/app.log, /mnt/d/...), reading file contents, running message-shell commands, and attaching files to tasks. Those actions can access and transmit arbitrary local data. The instructions do not limit or justify access to broad filesystem paths or explain authentication scopes, creating a risk of unintended data exfiltration.

Install Mechanism

There is no install specification (instruction-only). That reduces direct code install risk, but the handbook presumes an external 'oho' CLI exists; without an install or source/verification guidance for 'oho', you cannot verify the provenance of the required binary or how to obtain it safely.

Credentials

The skill metadata declares no required environment variables or primary credential, yet the instructions refer to provider listing, OAuth authorization/callback, and authentication flows. Authentication is implied but not declared, which is disproportionate and obscures what secrets or tokens will be used or stored.

Persistence & Privilege

The skill is not always-enabled and is user-invocable; it does not request permanent presence or claim to modify other skills or global agent config. No direct persistence/privilege escalation is requested in the metadata.

What to consider before installing

This skill is instruction-only but its handbook expects an 'oho' CLI, auth flows, and attaches local files — yet the package declares no binary, no install steps, and no credentials. Before installing or using it: (1) confirm the origin and authenticity of the 'oho' CLI and obtain it from a trusted source; (2) ask the publisher which credentials or OAuth flows are required and how tokens are stored; (3) do not attach or submit sensitive files (e.g., /var/log, ~/.ssh, source with secrets) until you verify privacy/retention policies; (4) request an explicit install spec or dependency list and a README that matches the SKILL.md; (5) if unsure, test in an isolated environment (VM/container) and avoid granting the agent access to directories with secrets. The mismatches may be benign oversights, but they also increase the risk of accidental data leakage — proceed cautiously.

OpenCode Server API Skill Handbook

Version: v4.6.0 | Server: v1.2.15 | oho CLI: v1.1.2

⚠️ Important: All OpenCode operations must be sent via oho CLI. Python SDK or curl are no longer supported.

---

🚫 Telegram Message Guidelines (Important)

Prohibited Content:

• ❌ Do not send notifications like "There are updates", "Skill has been updated"
• ❌ Do not send formatted version changelogs
• ❌ Do not send lengthy confirmation reports after task submission

Correct Approach:

• ✅ Return only a concise session ID and status after task submission
• ✅ Notify users only when there is substantial progress
• ✅ Keep messages brief and direct

Example:

✅ Task submitted
Session: ses_xxx
Project: babylon3DWorld

---

🚀 Quick Start

Submit Tasks (Async Mode to Avoid Timeout)

# Most common: create session + send message in one command, `directory` is the project path
oho add "Fix login bug" --title "Bug Fix" --directory /mnt/d/fe/babylon3DWorld --model "minimax-cn-coding-plan:MiniMax-M2.7" --no-reply

# Another example: summarize today's progress  
oho add "Summarize today's changes" --title "Command Test" --directory /mnt/d/fe/opencode_cli --model "minimax-cn-coding-plan:MiniMax-M2.7" --no-reply

# Specify Agent
oho add "@hephaestus Fix login bug" --title "Bug Fix" --directory /mnt/d/fe/project --model "minimax-cn-coding-plan:MiniMax-M2.7" --no-reply
  
# Attach files
oho add "Analyze logs" --file /var/log/app.log --directory /mnt/d/fe/project --no-reply

Key Parameters

Parameter	Type	Description	Default
--title	string	Session title (auto-generated if not provided)	Auto-generated
--parent	string	Parent session ID (for creating child sessions)	-
--directory	string	Session working directory, project path	Current directory
--agent	string	Agent ID for the message	-
--model	string	Model ID for the message (e.g., provider:model)	minimax-cn-coding-plan/MiniMax-M2.7
--no-reply	bool	Do not wait for AI response	false
--system	string	System prompt	-
--tools	string[]	Tool list (can be specified multiple times)	-
--file	string[]	File attachments (can be specified multiple times)	-
--timeout	int	Request timeout in seconds	300
-j, --json	bool	JSON output	false

---

📋 Common Commands

Session Management

# List all sessions
oho session list

# Filter by ID (fuzzy match)
oho session list --id ses_abc

# Filter by title (fuzzy)
oho session list --title "test"

# Filter by project ID
oho session list --project-id proj1

# Filter by directory
oho session list --directory babylon

# Filter by timestamp
oho session list --created 1773537883643
oho session list --updated 1773538142930

# Filter by status
oho session list --status running    # running/completed/error/aborted/idle
oho session list --running           # Show only running sessions

# Sort and pagination
oho session list --sort updated --order desc  # Sort by updated descending
oho session list --limit 10 --offset 0        # Pagination

# JSON output
oho session list -j

# Create session
oho session create
oho session create --title "name"
oho session create --parent ses_xxx    # Create child session
oho session create --path /path        # Create in specified directory

# Get session details
oho session get <id>

# Update session
oho session update <id> --title "New Title"

# Get child sessions
oho session children <id>

# Get todo items
oho session todo <id>

# Branch session
oho session fork <id>

# Abort session
oho session abort <id>

# Share/unshare session
oho session share <id>
oho session unshare <id>

# Get file diff
oho session diff <id>

# Session summary
oho session summarize <id>

# Revert message
oho session revert <id> --message <msg-id>
oho session unrevert <id>

# Respond to permission request
oho session permissions <id> <perm-id> --response allow

# Delete session
oho session delete ses_xxx

# Archive session
oho session achieve <id> --directory /mnt/d/fe/project

Message Management

# List messages
oho message list -s ses_xxx

# Get message details
oho message get -s ses_xxx <msg-id>

# Send message (sync)
oho message add -s ses_xxx "Continue task"

# Send async (don't wait for response)
oho message prompt-async -s ses_xxx "Task content"

# Execute command
oho message command -s ses_xxx /help

# Run shell command
oho message shell -s ses_xxx --agent default "ls -la"

Project Management

# List all projects
oho project list

# Get current project
oho project current

# Get current path
oho path

# Get VCS info
oho vcs

# Dispose current instance
oho instance dispose

Global Commands

# Check server health
oho global health

# Listen to global event stream (SSE)
oho global event

Configuration Management

# Get configuration
oho config get

# Update configuration
oho config set --theme dark

# List providers
oho config providers

Provider Management

# List all providers
oho provider list

# Get authentication methods
oho provider auth

# OAuth authorization
oho provider oauth authorize <id>

# Handle callback
oho provider oauth callback <id>

File Operations

# List files
oho file list [path]

# Read file content
oho file content <path>

# Get file status
oho file status

Find Commands

# Search text
oho find text "pattern"

# Find files
oho find file "query"

# Find symbols
oho find symbol "query"

Other Commands

# List agents
oho agent list

# List commands
oho command list

# List tool IDs
oho tool ids

# List tools
oho tool list --provider xxx --model xxx

# LSP status
oho lsp status

# Formatter status
oho formatter status

# MCP servers
oho mcp list
oho mcp add <name> --config '{}'

# TUI
oho tui open-help
oho tui show-toast --message "message"

# Auth setup
oho auth set <provider> --credentials key=value

---

⚠️ Timeout Handling (Important)

The oho add command waits for AI response by default. For complex tasks, the AI may need more time to think, which could cause timeout.

Ways to Avoid Timeout

Method 1: Use --no-reply Parameter (Recommended)

# ✅ Returns immediately after sending message, no waiting for AI response
oho add "Analyze project structure" --directory /mnt/d/fe/project --no-reply

# Check results later
oho message list -s <session-id>

Method 2: Increase Timeout

# Set timeout to 10 minutes (600 seconds)
export OPENCODE_CLIENT_TIMEOUT=600
oho add "Complex task" --directory /mnt/d/fe/project

# Or set temporarily
OPENCODE_CLIENT_TIMEOUT=600 oho add "Complex task" --directory /mnt/d/fe/project

Method 3: Use --timeout Parameter (Most Convenient)

# Temporarily set timeout to 10 minutes
oho add "Complex task" --directory /mnt/d/fe/project --timeout 600

# Set timeout to 1 hour
oho add "Large refactor" --directory /mnt/d/fe/project --timeout 3600

Method 4: Use Async Commands

# Create session first
oho session create --title "task" --path /mnt/d/fe/project

# Send message async
oho message prompt-async -s <session-id> "Task description"

Timeout Configuration

Configuration Method	Priority	Description
--timeout parameter	Highest	Temporary override, only effective for current command
OPENCODE_CLIENT_TIMEOUT env var	Medium	Effective for current shell session
Default value	Lowest	300 seconds (5 minutes)

Timeout Error Messages

If timeout occurs, you will see a friendly error:

Request timeout (300 seconds)

Suggestions:
  1. Use --no-reply parameter to avoid waiting
  2. Increase timeout via env var: export OPENCODE_CLIENT_TIMEOUT=600
  3. Use async command: oho message prompt-async -s <session-id> "task"

Background Polling (Optional)

#!/bin/bash
session_id=$(oho add "task" --directory /mnt/d/fe/project --json | jq -r '.sessionId')

while true; do
    count=$(oho message list -s "$session_id" -j | jq 'length')
    [ "$count" -ge 2 ] && echo "✅ Done" && break
    echo "⏳ Running... ($count messages)"
    sleep 10
done

---

🤖 Agent System

Agent	Role	Use Cases
@sisyphus	Main coordinator	Large feature development, parallel execution
@hephaestus	Deep worker	Code exploration, performance optimization
@prometheus	Strategic planner	Requirements clarification, architecture design

---

📝 Practical Examples

babylon3DWorld Project Tasks

#!/bin/bash
# Submit coding task

oho add "@hephaestus ulw optimize navigation logic between editor and world pages

**Coding Goals**:
1. When returning from editor to world page: refresh directly, no longer check if editor made changes
2. When entering editor from world page: no longer cache the world itself

**Keywords**: ulw" \
  --directory /mnt/d/fe/babylon3DWorld \
  --title "ulw - Optimize editor navigation logic" \
  --no-reply

echo "✅ Task submitted"

Multi-Project Batch Tasks

#!/bin/bash
# Batch submit tasks

oho add "Task 1" --directory /mnt/d/fe/babylon3DWorld --no-reply
oho add "Task 2" --directory /mnt/d/fe/wujimanager --no-reply
oho add "Task 3" --directory /mnt/d/fe/armdraw --no-reply

echo "✅ All tasks submitted"

---

OpenCode Server Usage

1. rerun.sh

#!/bin/bash

echo "🔴 stopping opencode web service..."
pkill -f "opencode web"
sleep 2


if pgrep -f "opencode web" > /dev/null; then
    pkill -9 -f "opencode web"
    sleep 1
fi

echo "✅ opencode web stopped"
echo "🟢 starting opencode web service..."
bash run.sh &

echo "✅ opencode web started"

2. run.sh

OPENCODE_SERVER_PASSWORD=cs516123456 opencode web --hostname 0.0.0.0  --port 4096 --mdns --mdns-domain opencode.local

🔧 Troubleshooting

Restart OpenCode Server

Standard Restart (Recommended):

# Switch to project directory and run restart script
cd /mnt/d/fe && bash rerun.sh &

Description:

• rerun.sh automatically stops old service and starts new one
• Use & to run in background to avoid blocking
• Wait 3-5 seconds after restart for service to fully start

Verify Service is Running:

# Wait for service to start
sleep 5

# Check processes
ps aux | grep "opencode web"

# Test API
oho session list

View Logs:

# View run.sh output logs
tail -f /tmp/opencode.log

# Or view recent logs
tail -50 /tmp/opencode.log

If Restart Script Gets Stuck:

# Force kill stuck process
pkill -9 -f "bash rerun.sh"

# Manual restart
cd /mnt/d/fe
pkill -f "opencode web"
sleep 2
OPENCODE_SERVER_PASSWORD=yourpassword opencode web --hostname 0.0.0.0 --port 4096 --mdns --mdns-domain opencode.local &

401 Unauthorized

# Check password
echo $OPENCODE_SERVER_PASSWORD

# Or specify via command line
oho --password yourpassword session list

Session Not Found

# Recreate session
oho session create --path /mnt/d/fe/babylon3DWorld

Task Timeout

# Use --no-reply to submit async
oho add "task" --directory /mnt/d/fe/project --no-reply

ConfigInvalidError (500 Error)

Symptoms:

Error: API Error [500]: {"name":"ConfigInvalidError","data":{"path":"/path/to/project/.opencode/opencode.json","issues":[...]}}

Cause: The opencode.json or .opencode/opencode.json config file in the project does not comply with the schema requirements.

Common Errors:

// ❌ Wrong: tools.lint should be boolean, not object
{
  "tools": {
    "lint": {
      "type": "shell",
      "command": ["yarn", "lint"]
    }
  }
}

// ❌ Wrong: lsp config format is incorrect
{
  "lsp": {
    "vue": {
      "disabled": false  // Should be true/false, but schema expects different format
    }
  }
}

Solution:

# 1. Backup incorrect config file
mv opencode.json opencode.json.bak
mv .opencode/opencode.json .opencode/opencode.json.bak

# 2. Restart opencode server (using rerun.sh)
cd /mnt/d/fe && bash rerun.sh &

# 3. Verify service is running
sleep 5
oho session list

# 4. If you need config, use correct format
cat > .opencode/opencode.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "model": "alibaba-cn/qwen3.5-plus"
}
EOF

Prevention:

• Backup opencode.json before modifying
• Use oho config get to verify config is valid
• Reference official schema: https://opencode.ai/config.json

---

🔗 MCP Server

oho can act as an MCP (Model Context Protocol) server, allowing external MCP clients (like Claude Desktop, Cursor, etc.) to call OpenCode API via MCP protocol.

Start MCP Server

# Start MCP server (stdio mode)
oho mcpserver

Available MCP Tools

Tool	Description
session_list	List all sessions
session_create	Create new session
session_get	Get session details
session_delete	Delete session
session_status	Get all session statuses
message_list	List messages in session
message_add	Send message to session
config_get	Get OpenCode configuration
project_list	List all projects
project_current	Get current project
provider_list	List AI providers
file_list	List files in directory
file_content	Read file content
find_text	Search text in project
find_file	Find files by name
global_health	Check server health status

MCP Client Configuration

Claude Desktop (macOS/Windows)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "oho": {
      "command": "oho",
      "args": ["mcpserver"],
      "env": {
        "OPENCODE_SERVER_HOST": "127.0.0.1",
        "OPENCODE_SERVER_PORT": "4096",
        "OPENCODE_SERVER_PASSWORD": "your-password"
      }
    }
  }
}

Cursor

Add to Cursor settings (JSON mode):

{
  "mcpServers": {
    "oho": {
      "command": "oho",
      "args": ["mcpserver"],
      "env": {
        "OPENCODE_SERVER_HOST": "127.0.0.1",
        "OPENCODE_SERVER_PORT": "4096",
        "OPENCODE_SERVER_PASSWORD": "your-password"
      }
    }
  }
}

---

🔗 Related Resources

• OpenCode Official Docs: https://opencode.ai/docs/
• oho CLI Repository: https://github.com/tornado404/opencode_cli
• OpenAPI Spec: http://localhost:4096/doc

---

Created: 2026-02-27 13:46 CST
Last Updated: 2026-04-02 00:43 CST - Added session achieve command