opencode-client

---

name: oho description: OpenCode CLI for submitting coding tasks, managing sessions, and delegating work to coding agents. Use when: (1) submitting coding tasks, (2) creating/managing sessions, (3) delegating work to coding agents, (4) checking task status, (5) configuring OpenCode settings.

---

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 
Update session
oho session update  --title "New Title"
Get child sessions
oho session children 
Get todo items
oho session todo 
Branch session
oho session fork 
Abort session
oho session abort 
Share/unshare session
oho session share 
oho session unshare 
Get file diff
oho session diff 
Session summary
oho session summarize 
Revert message
oho session revert  --message 
oho session unrevert 
Respond to permission request
oho session permissions   --response allow
Delete session
oho session delete ses_xxx
Archive session
oho session achieve  --directory /mnt/d/fe/project

Message Management

# List messages
oho message list -s ses_xxx
Get message details
oho message get -s ses_xxx 
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 
Handle callback
oho provider oauth callback 

File Operations

# List files
oho file list [path]
Read file content
oho file content 
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  --config '{}'
TUI
oho tui open-help
oho tui show-toast --message "message"
Auth setup
oho auth set  --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 

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  "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  "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*