OpenCode Agent

Use this skill to run coding tasks through a remote OpenCode server.

Required Command Pattern

Always use this shape:

opencode run --attach <server_url> "<task>" --dir "<server_path>"

Example:

opencode run --attach http://127.0.0.1:4096 "what is in this folder" --dir "/home/richard/FeedMob"

Configuration

Read these values from environment variables:

# Example values
export OPENCODE_SERVER_URL=http://127.0.0.1:4096
export OPENCODE_SERVER_DIR=/home/richard/FeedMob

# Check values
printenv OPENCODE_SERVER_URL && printenv OPENCODE_SERVER_DIR

If either value is missing, ask the user to provide the missing value(s) before running commands. Never assume, infer, or hardcode OPENCODE_SERVER_URL or OPENCODE_SERVER_DIR.

Preflight requirement before any attached run:

1. Run printenv OPENCODE_SERVER_URL && printenv OPENCODE_SERVER_DIR.
2. If the command fails or a value is missing/empty, ask the user for the missing value(s).
3. Only proceed after both values are explicitly provided.
4. Check existing projects by running opencode run --attach $OPENCODE_SERVER_URL 'pwd && ls -1d */ || true' --dir "$OPENCODE_SERVER_DIR", then list results for the user.
5. Create a new folder for new tasks by running opencode run --attach $OPENCODE_SERVER_URL 'mkdir -p <task-folder>' --dir "$OPENCODE_SERVER_DIR".

PTY Required

OpenCode is interactive. Always run with pty:true.

# Correct
bash pty:true command:"opencode run --attach $OPENCODE_SERVER_URL 'Explain async/await in JavaScript' --dir '$OPENCODE_SERVER_DIR'"

# Wrong (no PTY)
bash command:"opencode run --attach $OPENCODE_SERVER_URL 'Explain async/await in JavaScript' --dir '$OPENCODE_SERVER_DIR'"

Server-Side Directory Rule

--dir is required by this skill and points to a path on the machine where opencode server is running.

• Do not treat --dir as a client/local path unless server and client are the same machine.
• Prefer absolute paths for --dir.
• The workdir field in bash does not replace --dir for attached OpenCode execution.

One-Shot Usage

bash pty:true command:"opencode run --attach $OPENCODE_SERVER_URL 'Add error handling to API calls' --dir '$OPENCODE_SERVER_DIR'"

Background Usage

# Start
bash pty:true background:true command:"opencode run --attach $OPENCODE_SERVER_URL 'Refactor auth module and run tests' --dir '$OPENCODE_SERVER_DIR'"

# Monitor
process action:log sessionId:XXX
process action:poll sessionId:XXX

# Respond if needed
process action:submit sessionId:XXX data:"yes"

# Stop
process action:kill sessionId:XXX

Bash Tool Parameters

Parameter	Type	Description
command	string	The shell command to run
pty	boolean	Use for coding agents! Allocates a pseudo-terminal for interactive CLIs
workdir	string	Working directory (agent sees only this folder's context)
background	boolean	Run in background, returns sessionId for monitoring
timeout	number	Timeout in seconds (kills process on expiry)
elevated	boolean	Run on host instead of sandbox (if allowed)

Process Tool Actions (for background sessions)

Action	Description
list	List all running/recent sessions
poll	Check if session is still running
log	Get session output (with optional offset/limit)
write	Send raw data to stdin
submit	Send data + newline (like typing and pressing Enter)
send-keys	Send key tokens or hex bytes
paste	Paste text (with optional bracketed mode)
kill	Terminate the session

Rules

1. Always use opencode run --attach.
2. Always include --dir.
3. Always use pty:true.
4. Keep users updated when running background sessions (start, milestone, error, finish).
5. If a session hangs, inspect logs first, then restart or ask user for direction.
6. Never assume environment variable values; ask the user when missing.

Troubleshooting

# Start server
opencode server --port 4096

• Connection issue: verify OPENCODE_SERVER_URL points to a live server.
• Path issue: verify OPENCODE_SERVER_DIR exists on the server machine.
• No output: confirm pty:true is set and check process action:log.