name	opencode-coding-agent
description	SSH-based access to opencode TUI coding agent in a remote container. Supports TUI mode, non-interactive run mode, server/attach patterns, and full CLI command set. Use when the user wants to delegate coding tasks to an opencode instance running remotely. Workflow: SSH into host, cd to projects/<repo>, create feature branch from updated default branch, launch opencode (TUI or run mode), execute coding instructions, commit with conventional prefix + signature, and push to GitHub. NEVER commit to default/main branch.

name

opencode-coding-agent

description

SSH-based access to opencode TUI coding agent in a remote container. Supports TUI mode, non-interactive run mode, server/attach patterns, and full CLI command set. Use when the user wants to delegate coding tasks to an opencode instance running remotely. Workflow: SSH into host, cd to projects/<repo>, create feature branch from updated default branch, launch opencode (TUI or run mode), execute coding instructions, commit with conventional prefix + signature, and push to GitHub. NEVER commit to default/main branch.

Opencode Coding Agent

SSH-based access to an opencode TUI (terminal user interface) coding agent running in an LXC container.

Environment Variables

Required environment variables (set by the user):

OPENCODE_HOST - SSH hostname/IP of the LXC container
OPENCODE_USERNAME - SSH username for the LXC
OPENCODE_PASSWORD - SSH password for the LXC

Workflow

1. Connect via SSH

ssh $OPENCODE_USERNAME@$OPENCODE_HOST

2. Navigate to Projects Directory

cd ~/projects

3. Set Up the Repository

If the repo already exists:

cd <repo-name>

If the repo needs to be cloned:

git clone <github-url> <repo-name>
cd <repo-name>

4. Create Feature Branch (Always Start Fresh)

CRITICAL: Always create feature branches from the updated default branch.

# 1. If there are uncommitted changes, stash them first (before anything else)
git stash  # This saves your work temporarily - prevents checkout conflicts

# 2. Checkout the default branch (main/master)
git checkout main  # or master, depending on the repo

# 3. Pull latest changes
git pull origin main

# 4. Create and checkout the new feature branch
git checkout -b feature/<descriptive-name>

# Note: Stashed changes remain in the stash list (not discarded). They are left untouched - do NOT restore them to the feature branch as they are from incomplete work or failed experiments.

5. Launch Opencode

Interactive TUI Mode (recommended for large/multi-step work):

opencode

This mode maintains session context across multiple prompts, allowing you to:

Work through complex tasks iteratively
Maintain conversation history
Refine and modify work in the same session
Resume later with --continue

Track Session ID: When opencode starts, it will display a session ID. Save this ID for later resumption:

session: abc123xyz

You can also list sessions to find it later:

opencode session list

TUI Mode with Prompt (one-shot):

opencode --prompt "Your prompt here"

Non-Interactive Mode (for scripting/single tasks):

opencode run "Your prompt here"

With specific model:

opencode --prompt "Your prompt here" --model provider/model
# or
opencode run --model provider/model "Your prompt here"

Attach files to prompt:

opencode --prompt "Explain this code" --file ./src/lru.js

Resume Session (after disconnect or to continue work):

opencode --continue              # Resume last session
# or
opencode --session abc123xyz     # Resume specific session by ID

Attach to running server:

opencode attach http://localhost:4096

Start headless server (for API access):

opencode serve --port 4096 --hostname 0.0.0.0
# Set password for auth: OPENCODE_SERVER_PASSWORD=secret

Security Note: Always set OPENCODE_SERVER_PASSWORD when exposing the server on a network. Default username is opencode. Default hostname is 127.0.0.1 (localhost only).

mDNS Discovery: Enable mDNS for network discovery:

opencode serve --mdns --mdns-domain myproject.local

CORS for browser clients:

opencode serve --cors http://localhost:5173 --cors https://app.example.com

Start with web interface:

opencode web --port 4096

6. Commit to Feature Branch

CRITICAL: Never commit to the default/main branch.

# Stage changes
git add .

# Commit with conventional prefix and signature
git commit -m "<type>: <description> -- Signed-off-by: Mads <openclaw>"

Examples:
- `feat: add user authentication`
- `doc: update README with installation steps`
- `fix: resolve null pointer in parser`
- `chore: update dependencies`

# Push to GitHub
git push -u origin <current-branch>

Commit Message Format

Every commit must follow this format:

<type>: <description> -- Signed-off-by: Mads <openclaw>

Common types:

feat: - New feature
fix: - Bug fix
doc: - Documentation
refactor: - Code refactoring
chore: - Maintenance/tasks
test: - Adding/fixing tests
style: - Formatting, missing semicolons, etc.

Example:

git commit -m "feat: add user authentication -- Signed-off-by: Mads <openclaw>"

Opencode CLI Commands

Common Commands

Command	Description
`opencode [project]`	Start TUI (default)
`opencode run "prompt"`	Non-interactive mode, run once and exit
`opencode serve`	Start headless HTTP server (API access)
`opencode web`	Start server with web interface
`opencode attach [url]`	Attach TUI to running backend

Server Options

Flag	Description	Default
`--port`	Port to listen on	4096
`--hostname`	Hostname to listen on	127.0.0.1
`--mdns`	Enable mDNS discovery	false
`--mdns-domain`	Custom mDNS domain	opencode.local
`--cors`	Browser origins (can be passed multiple times)	[]

Example:

opencode serve --port 4096 --hostname 0.0.0.0 --mdns --cors http://localhost:5173

TUI Commands (Slash Commands)

When in the TUI, type / followed by a command name:

Command	Keybind	Description
`/connect`	ctrl+x c	Add a provider (API keys)
`/compact`	ctrl+x c	Compact session (alias: `/summarize`)
`/details`	ctrl+x d	Toggle tool execution details
`/editor`	ctrl+x e	Open external editor for composing messages
`/exit`	ctrl+x q	Exit OpenCode (aliases: `/quit`, `/q`)
`/export`	ctrl+x x	Export conversation to Markdown
`/help`	ctrl+x h	Show help dialog
`/init`	ctrl+x i	Guided setup for AGENTS.md
`/models`	ctrl+x m	List available models
`/new`	ctrl+x n	Start new session (alias: `/clear`)
`/redo`	ctrl+x r	Redo previously undone message
`/sessions`	ctrl+x l	List and switch sessions (aliases: `/resume`, `/continue`)
`/share`	ctrl+x s	Share current session
`/themes`	ctrl+x t	List available themes
`/thinking`		Toggle thinking/reasoning visibility
`/undo`	ctrl+x u	Undo last message (uses Git)
`/unshare`		Unshare current session

Session Management Commands:

/sessions - List and switch between sessions
/share - Share current session
/unshare - Unshare current session
/new - Start fresh session
/exit - Quit TUI

File References: Use @ to reference files (fuzzy search)

How is auth handled in @packages/functions/src/api/index.ts?

Bash Commands: Start message with ! to run shell commands

!ls -la

Editor Setup:

export EDITOR="code --wait"  # VS Code
export EDITOR=vim
export EDITOR=nano

Session Management

Command	Description
`opencode session list`	List all sessions
`opencode export [sessionID]`	Export session as JSON
`opencode import <file>`	Import session from file or URL

Agent & Model Management

Command	Description
`opencode agent list`	List available agents
`opencode agent create`	Create new agent with custom config
`opencode models [provider]`	List available models
`opencode models --refresh`	Refresh model cache

Authentication

Command	Description
`opencode auth login`	Configure provider API keys
`opencode auth list`	Show authenticated providers
`opencode auth logout`	Clear provider credentials

MCP Servers (Model Context Protocol)

Command	Description
`opencode mcp add`	Add MCP server (local or remote)
`opencode mcp list`	List configured MCP servers
`opencode mcp auth [name]`	Authenticate with OAuth server

Use Case: MCP servers extend opencode with external tools (databases, APIs, file systems). Add servers as needed for specific tasks.

GitHub Integration

Command	Description
`opencode github install`	Install GitHub agent in repo (sets up Actions workflow)
`opencode github run`	Run GitHub agent (typically in Actions)

Use Case: The GitHub agent can automate PR creation, reviews, and repo management. Install once per repo for automated workflows.

Other Commands

Command	Description
`opencode stats`	Show token usage and cost stats
`opencode upgrade`	Update to latest version
`opencode uninstall`	Remove opencode and files

TUI Configuration

Customize TUI behavior through tui.json (or tui.jsonc):

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "keybinds": {
    "leader": "ctrl+x"
  },
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto"
}

Options:

theme - UI theme (see /themes in TUI)
keybinds.leader - Leader key for shortcuts (default: ctrl+x)
scroll_speed - Scroll speed (default: 3)
scroll_acceleration.enabled - macOS-style scroll acceleration
diff_style - "auto" (adaptive) or "stacked" (single-column)

Use OPENCODE_TUI_CONFIG to load a custom config path.

Common Flags

Flag	Short	Description
`--continue`	`-c`	Continue last session
`--session`	`-s`	Session ID to continue
`--fork`		Fork session when continuing
`--prompt`		Prompt to use
`--model`	`-m`	Model (provider/model format)
`--agent`		Agent to use
`--port`		Port to listen on
`--hostname`		Hostname to listen on
`--file`	`-f`	File(s) to attach
`--format`		Output format: `default` or `json` (raw JSON events for scripting)
`--title`		Title for the session (uses truncated prompt if no value provided)
`--share`		Share the session (requires OPENCODE_AUTO_SHARE or manual sharing)
`--help`	`-h`	Display help
`--version`	`-v`	Print version

Environment Variables

Variable	Description
`OPENCODE_CONFIG`	Path to config file
`OPENCODE_CONFIG_DIR`	Path to config directory (for agents, commands, plugins)
`OPENCODE_MODELS_URL`	Custom URL for models config
`OPENCODE_SERVER_PASSWORD`	HTTP basic auth password for serve/web (username: opencode)
`OPENCODE_SERVER_USERNAME`	Override basic auth username (default: opencode)
`OPENCODE_DISABLE_AUTOUPDATE`	Disable automatic update checks
`OPENCODE_TUI_CONFIG`	Path to custom TUI config file
`OPENCODE_CONFIG_CONTENT`	Inline config (JSON) for runtime overrides

Sharing Configuration

Sharing is configured in opencode.json (not via env var):

{
  "share": "manual"    // "manual" (default), "auto", or "disabled"
}

manual - Allow manual sharing via /share command (default)
auto - Automatically share new conversations
disabled - Disable sharing entirely

Experimental Variables

Variable	Description
`OPENCODE_EXPERIMENTAL`	Enable all experimental features
`OPENCODE_EXPERIMENTAL_PLAN_MODE`	Enable plan mode
`OPENCODE_EXPERIMENTAL_FILEWATCHER`	Enable file watcher for entire dir

Config Schema

Runtime config: opencode.ai/config.json TUI config: opencode.ai/tui.json

Use these schema URLs in your config files for editor validation:

{
  "$schema": "https://opencode.ai/config.json",
  // ... config options
}

Important Rules

Always start from default branch - Checkout main/master and pull latest before creating feature branch
Stash uncommitted changes - If working directory has changes, stash them before branching
Work inside the projects directory - All opencode sessions must run from ~/projects
Use descriptive branch names - Include what the feature/fix does
Use conventional commit prefixes - Match the type of change
Add signature to every commit - Required for attribution
Push after each logical unit of work - Don't leave unpushed commits
Save session IDs - For long tasks, note the session ID to resume if disconnected
Track token usage - Use opencode stats to monitor costs for expensive tasks

Session Management

After completing a task:

Exit opencode: /exit (or /quit, /q, or Ctrl+C)
Exit SSH session
Report completion to the user with:
- Branch name created
- Commit summary
- GitHub URL to the branch (if available)

Best Practices

For single-file changes: Use opencode --prompt "..." for quick one-shot tasks
For multi-file refactors: Use interactive TUI mode (opencode) to maintain context
For long tasks: Note the session ID to resume if SSH disconnects
For expensive tasks: Run opencode stats to track token usage and costs
For automation: Use opencode run with --format json for scriptable output
For security: Always set OPENCODE_SERVER_PASSWORD when exposing servers on a network
In TUI: Use @filename to reference files, !command to run shell commands
For context management: Use /compact to reduce session size during long tasks
For file changes: Use /undo and /redo to revert/restore changes (Git-based)

Architecture Notes

TUI + Server Model: When you run opencode, it starts both a TUI client and an HTTP server. The TUI talks to the server via the OpenAPI endpoint. This architecture allows:

Multiple clients (TUI, web, IDE plugins) to connect to one server
Programmatic control via HTTP API
Session persistence and remote access

Server Endpoints: View the full OpenAPI 3.1 spec at http://<host>:<port>/doc

Key APIs:

/session - Create, list, fork, share, summarize sessions
/session/:id/message - Send messages, get responses
/file/content - Read files programmatically
/find - Search files and symbols
/mcp - Manage MCP servers
/provider - OAuth authentication for providers

avoidwork/SKILL.md

Select an option

No results found

Select an option

No results found

Opencode Coding Agent

Environment Variables

Workflow

1. Connect via SSH

2. Navigate to Projects Directory

3. Set Up the Repository

4. Create Feature Branch (Always Start Fresh)

5. Launch Opencode

6. Commit to Feature Branch

Commit Message Format

Opencode CLI Commands

Common Commands

Server Options

TUI Commands (Slash Commands)

Session Management

Agent & Model Management

Authentication

MCP Servers (Model Context Protocol)

GitHub Integration

Other Commands

TUI Configuration

Common Flags

Environment Variables

Sharing Configuration

Experimental Variables

Config Schema

Important Rules

Session Management

Best Practices

Architecture Notes