Initial commit: homelab infrastructure wiki

- Full Obsidian vault content
- Host configs (ice, grizzley, ubuntu, proxmox, truenas, panda, hyte)
- Media stack documentation
- Traefik HA setup
- Automation scripts
- Bachelor party planning

homelab/raw/articles/opencode/docs/acp.md

@@ -0,0 +1,95 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/acp/
+scraped: 2026-04-28T21:02:06.607578+00:00
+content_hash: 189daad2
+---
+# ACP Support
+
+Use OpenCode in any ACP-compatible editor.
+
+OpenCode supports the Agent Client Protocol or (ACP), allowing you to use it directly in compatible editors and IDEs.
+
+ACP is an open protocol that standardizes communication between code editors and AI coding agents.
+
+---
+
+## Configure
+
+To use OpenCode via ACP, configure your editor to run the opencode acp command.
+
+The command starts OpenCode as an ACP-compatible subprocess that communicates with your editor over JSON-RPC via stdio.
+
+Below are examples for popular editors that support ACP.
+
+---
+
+### Zed
+
+Add to your Zed configuration (~/.config/zed/settings.json):
+
+```
+{  "agent_servers": {    "OpenCode": {      "command": "opencode",      "args": ["acp"]    }  }}
+```
+
+To open it, use the agent: new thread action in the Command Palette.
+
+You can also bind a keyboard shortcut by editing your keymap.json:
+
+```
+[  {    "bindings": {      "cmd-alt-o": [        "agent::NewExternalAgentThread",        {          "agent": {            "custom": {              "name": "OpenCode",              "command": {                "command": "opencode",                "args": ["acp"]              }            }          }        }      ]    }  }]
+```
+
+---
+
+### JetBrains IDEs
+
+Add to your JetBrains IDE acp.json according to the documentation:
+
+```
+{  "agent_servers": {    "OpenCode": {      "command": "/absolute/path/bin/opencode",      "args": ["acp"]    }  }}
+```
+
+To open it, use the new ‘OpenCode’ agent in the AI Chat agent selector.
+
+---
+
+### Avante.nvim
+
+Add to your Avante.nvim configuration:
+
+```
+{  acp_providers = {    ["opencode"] = {      command = "opencode",      args = { "acp" }    }  }}
+```
+
+If you need to pass environment variables:
+
+```
+{  acp_providers = {    ["opencode"] = {      command = "opencode",      args = { "acp" },      env = {        OPENCODE_API_KEY = os.getenv("OPENCODE_API_KEY")      }    }  }}
+```
+
+---
+
+### CodeCompanion.nvim
+
+To use OpenCode as an ACP agent in CodeCompanion.nvim, add the following to your Neovim config:
+
+```
+require("codecompanion").setup({  interactions = {    chat = {      adapter = {        name = "opencode",        model = "claude-sonnet-4",      },    },  },})
+```
+
+This config sets up CodeCompanion to use OpenCode as the ACP agent for chat.
+
+If you need to pass environment variables (like OPENCODE_API_KEY), refer to Configuring Adapters: Environment Variables in the CodeCompanion.nvim documentation for full details.
+
+## Support
+
+OpenCode works the same via ACP as it does in the terminal. All features are supported:
+
+- Built-in tools (file operations, terminal commands, etc.)
+- Custom tools and slash commands
+- MCP servers configured in your OpenCode config
+- Project-specific rules from AGENTS.md
+- Custom formatters and linters
+- Agents and permissions system

homelab/raw/articles/opencode/docs/agents.md

@@ -0,0 +1,458 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/agents/
+scraped: 2026-04-28T21:02:11.448912+00:00
+content_hash: 16dfe9c3
+---
+# Agents
+
+Configure and use specialized agents.
+
+Agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access.
+
+You can switch between agents during a session or invoke them with the @ mention.
+
+---
+
+## Types
+
+There are two types of agents in OpenCode; primary agents and subagents.
+
+---
+
+### Primary agents
+
+Primary agents are the main assistants you interact with directly. You can cycle through them using the Tab key, or your configured switch_agent keybind. These agents handle your main conversation. Tool access is configured via permissions — for example, Build has all tools enabled while Plan is restricted.
+
+OpenCode comes with two built-in primary agents, Build and Plan. We’ll look at these below.
+
+---
+
+### Subagents
+
+Subagents are specialized assistants that primary agents can invoke for specific tasks. You can also manually invoke them by @ mentioning them in your messages.
+
+OpenCode comes with two built-in subagents, General and Explore. We’ll look at this below.
+
+---
+
+## Built-in
+
+OpenCode comes with two built-in primary agents and two built-in subagents.
+
+---
+
+### Use build
+
+Mode: primary
+
+Build is the default primary agent with all tools enabled. This is the standard agent for development work where you need full access to file operations and system commands.
+
+---
+
+### Use plan
+
+Mode: primary
+
+A restricted agent designed for planning and analysis. We use a permission system to give you more control and prevent unintended changes. By default, all of the following are set to ask:
+
+- file edits: All writes, patches, and edits
+- bash: All bash commands
+
+This agent is useful when you want the LLM to analyze code, suggest changes, or create plans without making any actual modifications to your codebase.
+
+---
+
+### Use general
+
+Mode: subagent
+
+A general-purpose agent for researching complex questions and executing multi-step tasks. Has full tool access (except todo), so it can make file changes when needed. Use this to run multiple units of work in parallel.
+
+---
+
+### Use explore
+
+Mode: subagent
+
+A fast, read-only agent for exploring codebases. Cannot modify files. Use this when you need to quickly find files by patterns, search code for keywords, or answer questions about the codebase.
+
+---
+
+### Use compaction
+
+Mode: primary
+
+Hidden system agent that compacts long context into a smaller summary. It runs automatically when needed and is not selectable in the UI.
+
+---
+
+### Use title
+
+Mode: primary
+
+Hidden system agent that generates short session titles. It runs automatically and is not selectable in the UI.
+
+---
+
+### Use summary
+
+Mode: primary
+
+Hidden system agent that creates session summaries. It runs automatically and is not selectable in the UI.
+
+---
+
+## Usage
+
+1. For primary agents, use the Tab key to cycle through them during a session. You can also use your configured switch_agent keybind.
+2. Subagents can be invoked: Automatically by primary agents for specialized tasks based on their descriptions. Manually by @ mentioning a subagent in your message. For example. @general help me search for this function
+3. Navigation between sessions: When subagents create child sessions, use session_child_first (default: <Leader>+Down) to enter the first child session from the parent.
+4. Once you are in a child session, use: session_child_cycle (default: Right) to cycle to the next child session session_child_cycle_reverse (default: Left) to cycle to the previous child session session_parent (default: Up) to return to the parent session This lets you switch between the main conversation and specialized subagent work.
+
+---
+
+## Configure
+
+You can customize the built-in agents or create your own through configuration. Agents can be configured in two ways:
+
+---
+
+### JSON
+
+Configure agents in your opencode.json config file:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "agent": {    "build": {      "mode": "primary",      "model": "anthropic/claude-sonnet-4-20250514",      "prompt": "{file:./prompts/build.txt}",      "permission": {        "edit": "allow",        "bash": "allow"      }    },    "plan": {      "mode": "primary",      "model": "anthropic/claude-haiku-4-20250514",      "permission": {        "edit": "deny",        "bash": "deny"      }    },    "code-reviewer": {      "description": "Reviews code for best practices and potential issues",      "mode": "subagent",      "model": "anthropic/claude-sonnet-4-20250514",      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",      "permission": {        "edit": "deny"      }    }  }}
+```
+
+---
+
+### Markdown
+
+You can also define agents using markdown files. Place them in:
+
+- Global: ~/.config/opencode/agents/
+- Per-project: .opencode/agents/
+
+```
+---description: Reviews code for quality and best practicesmode: subagentmodel: anthropic/claude-sonnet-4-20250514temperature: 0.1permission:  edit: deny  bash: deny---
+You are in code review mode. Focus on:
+- Code quality and best practices- Potential bugs and edge cases- Performance implications- Security considerations
+Provide constructive feedback without making direct changes.
+```
+
+The markdown file name becomes the agent name. For example, review.md creates a review agent.
+
+---
+
+## Options
+
+Let’s look at these configuration options in detail.
+
+---
+
+### Description
+
+Use the description option to provide a brief description of what the agent does and when to use it.
+
+```
+{  "agent": {    "review": {      "description": "Reviews code for best practices and potential issues"    }  }}
+```
+
+This is a required config option.
+
+---
+
+### Temperature
+
+Control the randomness and creativity of the LLM’s responses with the temperature config.
+
+Lower values make responses more focused and deterministic, while higher values increase creativity and variability.
+
+```
+{  "agent": {    "plan": {      "temperature": 0.1    },    "creative": {      "temperature": 0.8    }  }}
+```
+
+Temperature values typically range from 0.0 to 1.0:
+
+- 0.0-0.2: Very focused and deterministic responses, ideal for code analysis and planning
+- 0.3-0.5: Balanced responses with some creativity, good for general development tasks
+- 0.6-1.0: More creative and varied responses, useful for brainstorming and exploration
+
+```
+{  "agent": {    "analyze": {      "temperature": 0.1,      "prompt": "{file:./prompts/analysis.txt}"    },    "build": {      "temperature": 0.3    },    "brainstorm": {      "temperature": 0.7,      "prompt": "{file:./prompts/creative.txt}"    }  }}
+```
+
+If no temperature is specified, OpenCode uses model-specific defaults; typically 0 for most models, 0.55 for Qwen models.
+
+---
+
+### Max steps
+
+Control the maximum number of agentic iterations an agent can perform before being forced to respond with text only. This allows users who wish to control costs to set a limit on agentic actions.
+
+If this is not set, the agent will continue to iterate until the model chooses to stop or the user interrupts the session.
+
+```
+{  "agent": {    "quick-thinker": {      "description": "Fast reasoning with limited iterations",      "prompt": "You are a quick thinker. Solve problems with minimal steps.",      "steps": 5    }  }}
+```
+
+When the limit is reached, the agent receives a special system prompt instructing it to respond with a summarization of its work and recommended remaining tasks.
+
+---
+
+### Disable
+
+Set to true to disable the agent.
+
+```
+{  "agent": {    "review": {      "disable": true    }  }}
+```
+
+---
+
+### Prompt
+
+Specify a custom system prompt file for this agent with the prompt config. The prompt file should contain instructions specific to the agent’s purpose.
+
+```
+{  "agent": {    "review": {      "prompt": "{file:./prompts/code-review.txt}"    }  }}
+```
+
+This path is relative to where the config file is located. So this works for both the global OpenCode config and the project specific config.
+
+---
+
+### Model
+
+Use the model config to override the model for this agent. Useful for using different models optimized for different tasks. For example, a faster model for planning, a more capable model for implementation.
+
+```
+{  "agent": {    "plan": {      "model": "anthropic/claude-haiku-4-20250514"    }  }}
+```
+
+The model ID in your OpenCode config uses the format provider/model-id. For example, if you’re using OpenCode Zen, you would use opencode/gpt-5.1-codex for GPT 5.1 Codex.
+
+---
+
+### Tools (deprecated)
+
+tools is deprecated. Prefer the agent’s permission field for new configs, updates and more fine-grained control.
+
+Allows you to control which tools are available in this agent. You can enable or disable specific tools by setting them to true or false. In an agent’s tools config, true is equivalent to {"*": "allow"} permission and false is equivalent to {"*": "deny"} permission.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "tools": {    "write": true,    "bash": true  },  "agent": {    "plan": {      "tools": {        "write": false,        "bash": false      }    }  }}
+```
+
+You can also use wildcards in legacy tools entries to control multiple tools at once. For example, to disable all tools from an MCP server:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "agent": {    "readonly": {      "tools": {        "mymcp_*": false,        "write": false,        "edit": false      }    }  }}
+```
+
+Learn more about tools.
+
+---
+
+### Permissions
+
+You can configure permissions to manage what actions an agent can take. Each permission key can be set to:
+
+- "ask" — Prompt for approval before running the tool
+- "allow" — Allow all operations without approval
+- "deny" — Disable the tool
+
+The available permission keys are:
+
+| Key | Tools it gates |
+|---|---|
+| read | read |
+| edit | write, edit, apply_patch |
+| glob | glob |
+| grep | grep |
+| list | list |
+| bash | bash |
+| task | task |
+| external_directory | Any tool that reads or writes files outside the project worktree |
+| todowrite | todowrite, todoread |
+| webfetch | webfetch |
+| websearch | websearch |
+| codesearch | codesearch |
+| lsp | lsp |
+| skill | skill |
+| question | question |
+| doom_loop | Recovery prompts when an agent appears stuck |
+
+read, edit, glob, grep, list, bash, task, external_directory, lsp, and skill accept either a shorthand action ("allow" | "ask" | "deny") or an object of glob/pattern → action for fine-grained control. The remaining keys accept the shorthand action only.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "edit": "deny"  }}
+```
+
+You can override these permissions per agent.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "edit": "deny"  },  "agent": {    "build": {      "permission": {        "edit": "ask"      }    }  }}
+```
+
+You can also set permissions in Markdown agents.
+
+```
+---description: Code review without editsmode: subagentpermission:  edit: deny  bash:    "*": ask    "git diff": allow    "git log*": allow    "grep *": allow  webfetch: deny---
+Only analyze code and suggest changes.
+```
+
+You can set permissions for specific bash commands.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "agent": {    "build": {      "permission": {        "bash": {          "git push": "ask",          "grep *": "allow"        }      }    }  }}
+```
+
+This can take a glob pattern.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "agent": {    "build": {      "permission": {        "bash": {          "git *": "ask"        }      }    }  }}
+```
+
+And you can also use the * wildcard to manage permissions for all commands. Since the last matching rule takes precedence, put the * wildcard first and specific rules after.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "agent": {    "build": {      "permission": {        "bash": {          "*": "ask",          "git status *": "allow"        }      }    }  }}
+```
+
+Learn more about permissions.
+
+---
+
+### Mode
+
+Control the agent’s mode with the mode config. The mode option is used to determine how the agent can be used.
+
+```
+{  "agent": {    "review": {      "mode": "subagent"    }  }}
+```
+
+The mode option can be set to primary, subagent, or all. If no mode is specified, it defaults to all.
+
+---
+
+### Hidden
+
+Hide a subagent from the @ autocomplete menu with hidden: true. Useful for internal subagents that should only be invoked programmatically by other agents via the Task tool.
+
+```
+{  "agent": {    "internal-helper": {      "mode": "subagent",      "hidden": true    }  }}
+```
+
+This only affects user visibility in the autocomplete menu. Hidden agents can still be invoked by the model via the Task tool if permissions allow.
+
+---
+
+### Task permissions
+
+Control which subagents an agent can invoke via the Task tool with permission.task. Uses glob patterns for flexible matching.
+
+```
+{  "agent": {    "orchestrator": {      "mode": "primary",      "permission": {        "task": {          "*": "deny",          "orchestrator-*": "allow",          "code-reviewer": "ask"        }      }    }  }}
+```
+
+When set to deny, the subagent is removed from the Task tool description entirely, so the model won’t attempt to invoke it.
+
+---
+
+### Color
+
+Customize the agent’s visual appearance in the UI with the color option. This affects how the agent appears in the interface.
+
+Use a valid hex color (e.g., #FF5733) or theme color: primary, secondary, accent, success, warning, error, info.
+
+```
+{  "agent": {    "creative": {      "color": "#ff6b6b"    },    "code-reviewer": {      "color": "accent"    }  }}
+```
+
+---
+
+### Top P
+
+Control response diversity with the top_p option. Alternative to temperature for controlling randomness.
+
+```
+{  "agent": {    "brainstorm": {      "top_p": 0.9    }  }}
+```
+
+Values range from 0.0 to 1.0. Lower values are more focused, higher values more diverse.
+
+---
+
+### Additional
+
+Any other options you specify in your agent configuration will be passed through directly to the provider as model options. This allows you to use provider-specific features and parameters.
+
+For example, with OpenAI’s reasoning models, you can control the reasoning effort:
+
+```
+{  "agent": {    "deep-thinker": {      "description": "Agent that uses high reasoning effort for complex problems",      "model": "openai/gpt-5",      "reasoningEffort": "high",      "textVerbosity": "low"    }  }}
+```
+
+These additional options are model and provider-specific. Check your provider’s documentation for available parameters.
+
+---
+
+## Create agents
+
+You can create new agents using the following command:
+
+```
+opencode agent create
+```
+
+This interactive command will:
+
+1. Ask where to save the agent; global or project-specific.
+2. Description of what the agent should do.
+3. Generate an appropriate system prompt and identifier.
+4. Let you select which permissions the agent should be allowed (anything you don’t select is denied).
+5. Finally, create a markdown file with the agent configuration.
+
+---
+
+## Use cases
+
+Here are some common use cases for different agents.
+
+- Build agent: Full development work with all tools enabled
+- Plan agent: Analysis and planning without making changes
+- Review agent: Code review with read-only access plus documentation tools
+- Debug agent: Focused on investigation with bash and read tools enabled
+- Docs agent: Documentation writing with file operations but no system commands
+
+---
+
+## Examples
+
+Here are some example agents you might find useful.
+
+---
+
+### Documentation agent
+
+```
+---description: Writes and maintains project documentationmode: subagentpermission:  bash: deny---
+You are a technical writer. Create clear, comprehensive documentation.
+Focus on:
+- Clear explanations- Proper structure- Code examples- User-friendly language
+```
+
+---
+
+### Security auditor
+
+```
+---description: Performs security audits and identifies vulnerabilitiesmode: subagentpermission:  edit: deny---
+You are a security expert. Focus on identifying potential security issues.
+Look for:
+- Input validation vulnerabilities- Authentication and authorization flaws- Data exposure risks- Dependency vulnerabilities- Configuration security issues
+```

homelab/raw/articles/opencode/docs/cli.md

@@ -0,0 +1,575 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/cli/
+scraped: 2026-04-28T21:02:10.769385+00:00
+content_hash: fe7ba75e
+---
+# CLI
+
+OpenCode CLI options and commands.
+
+The OpenCode CLI by default starts the TUI when run without any arguments.
+
+```
+opencode
+```
+
+But it also accepts commands as documented on this page. This allows you to interact with OpenCode programmatically.
+
+```
+opencode run "Explain how closures work in JavaScript"
+```
+
+---
+
+### tui
+
+Start the OpenCode terminal user interface.
+
+```
+opencode [project]
+```
+
+#### Flags
+
+| Flag | Short | Description |
+|---|---|---|
+| --continue | -c | Continue the last session |
+| --session | -s | Session ID to continue |
+| --fork |  | Fork the session when continuing (use with --continue or --session) |
+| --prompt |  | Prompt to use |
+| --model | -m | Model to use in the form of provider/model |
+| --agent |  | Agent to use |
+| --port |  | Port to listen on |
+| --hostname |  | Hostname to listen on |
+
+---
+
+## Commands
+
+The OpenCode CLI also has the following commands.
+
+---
+
+### agent
+
+Manage agents for OpenCode.
+
+```
+opencode agent [command]
+```
+
+---
+
+### attach
+
+Attach a terminal to an already running OpenCode backend server started via serve or web commands.
+
+```
+opencode attach [url]
+```
+
+This allows using the TUI with a remote OpenCode backend. For example:
+
+```
+# Start the backend server for web/mobile accessopencode web --port 4096 --hostname 0.0.0.0
+# In another terminal, attach the TUI to the running backendopencode attach http://10.20.30.40:4096
+```
+
+| Flag | Short | Description |
+|---|---|---|
+| --dir |  | Working directory to start TUI in |
+| --session | -s | Session ID to continue |
+
+---
+
+#### create
+
+Create a new agent with custom configuration.
+
+```
+opencode agent create
+```
+
+This command will guide you through creating a new agent with a custom system prompt and permission configuration. Anything you don’t allow is denied in the generated agent’s frontmatter.
+
+| Flag | Description |
+|---|---|
+| --path | Directory to write the agent file to (defaults to global or .opencode/agent based on the prompt) |
+| --description | What the agent should do |
+| --mode | Agent mode: all, primary, or subagent |
+| --permissions | Comma-separated list of permissions to allow (default: all). Available: bash, read, edit, glob, grep, webfetch, task, todowrite, websearch, codesearch, lsp, skill. Anything omitted is denied. Alias: --tools |
+| --model, -m | Model to use, in provider/model format |
+
+Passing all of --path, --description, --mode, and --permissions runs the command non-interactively.
+
+---
+
+#### list
+
+List all available agents.
+
+```
+opencode agent list
+```
+
+---
+
+### auth
+
+Command to manage credentials and login for providers.
+
+```
+opencode auth [command]
+```
+
+---
+
+#### login
+
+OpenCode is powered by the provider list at Models.dev, so you can use opencode auth login to configure API keys for any provider you’d like to use. This is stored in ~/.local/share/opencode/auth.json.
+
+```
+opencode auth login
+```
+
+When OpenCode starts up it loads the providers from the credentials file. And if there are any keys defined in your environments or a .env file in your project.
+
+---
+
+Lists all the authenticated providers as stored in the credentials file.
+
+```
+opencode auth list
+```
+
+Or the short version.
+
+```
+opencode auth ls
+```
+
+---
+
+#### logout
+
+Logs you out of a provider by clearing it from the credentials file.
+
+```
+opencode auth logout
+```
+
+---
+
+### github
+
+Manage the GitHub agent for repository automation.
+
+```
+opencode github [command]
+```
+
+---
+
+#### install
+
+Install the GitHub agent in your repository.
+
+```
+opencode github install
+```
+
+This sets up the necessary GitHub Actions workflow and guides you through the configuration process. Learn more.
+
+---
+
+#### run
+
+Run the GitHub agent. This is typically used in GitHub Actions.
+
+```
+opencode github run
+```
+
+| Flag | Description |
+|---|---|
+| --event | GitHub mock event to run the agent for |
+| --token | GitHub personal access token |
+
+---
+
+### mcp
+
+Manage Model Context Protocol servers.
+
+```
+opencode mcp [command]
+```
+
+---
+
+#### add
+
+Add an MCP server to your configuration.
+
+```
+opencode mcp add
+```
+
+This command will guide you through adding either a local or remote MCP server.
+
+---
+
+List all configured MCP servers and their connection status.
+
+```
+opencode mcp list
+```
+
+Or use the short version.
+
+```
+opencode mcp ls
+```
+
+---
+
+Authenticate with an OAuth-enabled MCP server.
+
+```
+opencode mcp auth [name]
+```
+
+If you don’t provide a server name, you’ll be prompted to select from available OAuth-capable servers.
+
+You can also list OAuth-capable servers and their authentication status.
+
+```
+opencode mcp auth list
+```
+
+Or use the short version.
+
+```
+opencode mcp auth ls
+```
+
+---
+
+Remove OAuth credentials for an MCP server.
+
+```
+opencode mcp logout [name]
+```
+
+---
+
+#### debug
+
+Debug OAuth connection issues for an MCP server.
+
+```
+opencode mcp debug <name>
+```
+
+---
+
+### models
+
+List all available models from configured providers.
+
+```
+opencode models [provider]
+```
+
+This command displays all models available across your configured providers in the format provider/model.
+
+This is useful for figuring out the exact model name to use in your config.
+
+You can optionally pass a provider ID to filter models by that provider.
+
+```
+opencode models anthropic
+```
+
+| Flag | Description |
+|---|---|
+| --refresh | Refresh the models cache from models.dev |
+| --verbose | Use more verbose model output (includes metadata like costs) |
+
+Use the --refresh flag to update the cached model list. This is useful when new models have been added to a provider and you want to see them in OpenCode.
+
+```
+opencode models --refresh
+```
+
+---
+
+Run opencode in non-interactive mode by passing a prompt directly.
+
+```
+opencode run [message..]
+```
+
+This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.
+
+```
+opencode run Explain the use of context in Go
+```
+
+You can also attach to a running opencode serve instance to avoid MCP server cold boot times on every run:
+
+```
+# Start a headless server in one terminalopencode serve
+# In another terminal, run commands that attach to itopencode run --attach http://localhost:4096 "Explain async/await in JavaScript"
+```
+
+| Flag | Short | Description |
+|---|---|---|
+| --command |  | The command to run, use message for args |
+| --continue | -c | Continue the last session |
+| --session | -s | Session ID to continue |
+| --fork |  | Fork the session when continuing (use with --continue or --session) |
+| --share |  | Share the session |
+| --model | -m | Model to use in the form of provider/model |
+| --agent |  | Agent to use |
+| --file | -f | File(s) to attach to message |
+| --format |  | Format: default (formatted) or json (raw JSON events) |
+| --title |  | Title for the session (uses truncated prompt if no value provided) |
+| --attach |  | Attach to a running opencode server (e.g., http://localhost:4096) |
+| --port |  | Port for the local server (defaults to random port) |
+| --dangerously-skip-permissions |  | Auto-approve permissions that are not explicitly denied (dangerous!) |
+
+---
+
+### serve
+
+Start a headless OpenCode server for API access. Check out the server docs for the full HTTP interface.
+
+```
+opencode serve
+```
+
+This starts an HTTP server that provides API access to opencode functionality without the TUI interface. Set OPENCODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to opencode).
+
+| Flag | Description |
+|---|---|
+| --port | Port to listen on |
+| --hostname | Hostname to listen on |
+| --mdns | Enable mDNS discovery |
+| --cors | Additional browser origin(s) to allow CORS |
+
+---
+
+### session
+
+Manage OpenCode sessions.
+
+```
+opencode session [command]
+```
+
+---
+
+List all OpenCode sessions.
+
+```
+opencode session list
+```
+
+| Flag | Short | Description |
+|---|---|---|
+| --max-count | -n | Limit to N most recent sessions |
+| --format |  | Output format: table or json (table) |
+
+---
+
+### stats
+
+Show token usage and cost statistics for your OpenCode sessions.
+
+```
+opencode stats
+```
+
+| Flag | Description |
+|---|---|
+| --days | Show stats for the last N days (all time) |
+| --tools | Number of tools to show (all) |
+| --models | Show model usage breakdown (hidden by default). Pass a number to show top N |
+| --project | Filter by project (all projects, empty string: current project) |
+
+---
+
+### export
+
+Export session data as JSON.
+
+```
+opencode export [sessionID]
+```
+
+If you don’t provide a session ID, you’ll be prompted to select from available sessions.
+
+---
+
+### import
+
+Import session data from a JSON file or OpenCode share URL.
+
+```
+opencode import <file>
+```
+
+You can import from a local file or an OpenCode share URL.
+
+```
+opencode import session.jsonopencode import https://opncd.ai/s/abc123
+```
+
+---
+
+### web
+
+Start a headless OpenCode server with a web interface.
+
+```
+opencode web
+```
+
+This starts an HTTP server and opens a web browser to access OpenCode through a web interface. Set OPENCODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to opencode).
+
+| Flag | Description |
+|---|---|
+| --port | Port to listen on |
+| --hostname | Hostname to listen on |
+| --mdns | Enable mDNS discovery |
+| --cors | Additional browser origin(s) to allow CORS |
+
+---
+
+### acp
+
+Start an ACP (Agent Client Protocol) server.
+
+```
+opencode acp
+```
+
+This command starts an ACP server that communicates via stdin/stdout using nd-JSON.
+
+| Flag | Description |
+|---|---|
+| --cwd | Working directory |
+| --port | Port to listen on |
+| --hostname | Hostname to listen on |
+
+---
+
+### uninstall
+
+Uninstall OpenCode and remove all related files.
+
+```
+opencode uninstall
+```
+
+| Flag | Short | Description |
+|---|---|---|
+| --keep-config | -c | Keep configuration files |
+| --keep-data | -d | Keep session data and snapshots |
+| --dry-run |  | Show what would be removed without removing |
+| --force | -f | Skip confirmation prompts |
+
+---
+
+### upgrade
+
+Updates opencode to the latest version or a specific version.
+
+```
+opencode upgrade [target]
+```
+
+To upgrade to the latest version.
+
+```
+opencode upgrade
+```
+
+To upgrade to a specific version.
+
+```
+opencode upgrade v0.1.48
+```
+
+| Flag | Short | Description |
+|---|---|---|
+| --method | -m | The installation method that was used; curl, npm, pnpm, bun, brew |
+
+---
+
+## Global Flags
+
+The opencode CLI takes the following global flags.
+
+| Flag | Short | Description |
+|---|---|---|
+| --help | -h | Display help |
+| --version | -v | Print version number |
+| --print-logs |  | Print logs to stderr |
+| --log-level |  | Log level (DEBUG, INFO, WARN, ERROR) |
+
+---
+
+## Environment variables
+
+OpenCode can be configured using environment variables.
+
+| Variable | Type | Description |
+|---|---|---|
+| OPENCODE_AUTO_SHARE | boolean | Automatically share sessions |
+| OPENCODE_GIT_BASH_PATH | string | Path to Git Bash executable on Windows |
+| OPENCODE_CONFIG | string | Path to config file |
+| OPENCODE_TUI_CONFIG | string | Path to TUI config file |
+| OPENCODE_CONFIG_DIR | string | Path to config directory |
+| OPENCODE_CONFIG_CONTENT | string | Inline json config content |
+| OPENCODE_DISABLE_AUTOUPDATE | boolean | Disable automatic update checks |
+| OPENCODE_DISABLE_PRUNE | boolean | Disable pruning of old data |
+| OPENCODE_DISABLE_TERMINAL_TITLE | boolean | Disable automatic terminal title updates |
+| OPENCODE_PERMISSION | string | Inlined json permissions config |
+| OPENCODE_DISABLE_DEFAULT_PLUGINS | boolean | Disable default plugins |
+| OPENCODE_DISABLE_LSP_DOWNLOAD | boolean | Disable automatic LSP server downloads |
+| OPENCODE_ENABLE_EXPERIMENTAL_MODELS | boolean | Enable experimental models |
+| OPENCODE_DISABLE_AUTOCOMPACT | boolean | Disable automatic context compaction |
+| OPENCODE_DISABLE_MODELS_FETCH | boolean | Disable fetching models from remote sources |
+| OPENCODE_DISABLE_MOUSE | boolean | Disable mouse capture in the TUI |
+| OPENCODE_FAKE_VCS | string | Fake VCS provider for testing purposes |
+| OPENCODE_CLIENT | string | Client identifier (defaults to cli) |
+| OPENCODE_ENABLE_EXA | boolean | Enable Exa web search tools |
+| OPENCODE_SERVER_PASSWORD | string | Enable basic auth for serve/web |
+| OPENCODE_SERVER_USERNAME | string | Override basic auth username (default opencode) |
+| OPENCODE_MODELS_URL | string | Custom URL for fetching models configuration |
+
+---
+
+### Experimental
+
+These environment variables enable experimental features that may change or be removed.
+
+| Variable | Type | Description |
+|---|---|---|
+| OPENCODE_EXPERIMENTAL | boolean | Enable all experimental features |
+| OPENCODE_EXPERIMENTAL_ICON_DISCOVERY | boolean | Enable icon discovery |
+| OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT | boolean | Disable copy on select in TUI |
+| OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS | number | Default timeout for bash commands in ms |
+| OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX | number | Max output tokens for LLM responses |
+| OPENCODE_EXPERIMENTAL_FILEWATCHER | boolean | Enable file watcher for entire dir |
+| OPENCODE_EXPERIMENTAL_OXFMT | boolean | Enable oxfmt formatter |
+| OPENCODE_EXPERIMENTAL_LSP_TOOL | boolean | Enable experimental LSP tool |
+| OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER | boolean | Disable file watcher |
+| OPENCODE_EXPERIMENTAL_EXA | boolean | Enable experimental Exa features |
+| OPENCODE_EXPERIMENTAL_LSP_TY | boolean | Enable TY LSP for python files |
+| OPENCODE_EXPERIMENTAL_MARKDOWN | boolean | Enable experimental markdown features |
+| OPENCODE_EXPERIMENTAL_PLAN_MODE | boolean | Enable plan mode |

homelab/raw/articles/opencode/docs/commands.md

@@ -0,0 +1,243 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/commands/
+scraped: 2026-04-28T21:02:13.673917+00:00
+content_hash: 3ce60cf9
+---
+# Commands
+
+Create custom commands for repetitive tasks.
+
+Custom commands let you specify a prompt you want to run when that command is executed in the TUI.
+
+```
+/my-command
+```
+
+Custom commands are in addition to the built-in commands like /init, /undo, /redo, /share, /help. Learn more.
+
+---
+
+## Create command files
+
+Create markdown files in the commands/ directory to define custom commands.
+
+Create .opencode/commands/test.md:
+
+```
+---description: Run tests with coverageagent: buildmodel: anthropic/claude-3-5-sonnet-20241022---
+Run the full test suite with coverage report and show any failures.Focus on the failing tests and suggest fixes.
+```
+
+The frontmatter defines command properties. The content becomes the template.
+
+Use the command by typing / followed by the command name.
+
+```
+"/test"
+```
+
+---
+
+## Configure
+
+You can add custom commands through the OpenCode config or by creating markdown files in the commands/ directory.
+
+---
+
+### JSON
+
+Use the command option in your OpenCode config:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "command": {    // This becomes the name of the command    "test": {      // This is the prompt that will be sent to the LLM      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",      // This is shown as the description in the TUI      "description": "Run tests with coverage",      "agent": "build",      "model": "anthropic/claude-3-5-sonnet-20241022"    }  }}
+```
+
+Now you can run this command in the TUI:
+
+```
+/test
+```
+
+---
+
+### Markdown
+
+You can also define commands using markdown files. Place them in:
+
+- Global: ~/.config/opencode/commands/
+- Per-project: .opencode/commands/
+
+```
+---description: Run tests with coverageagent: buildmodel: anthropic/claude-3-5-sonnet-20241022---
+Run the full test suite with coverage report and show any failures.Focus on the failing tests and suggest fixes.
+```
+
+The markdown file name becomes the command name. For example, test.md lets you run:
+
+```
+/test
+```
+
+---
+
+## Prompt config
+
+The prompts for the custom commands support several special placeholders and syntax.
+
+---
+
+### Arguments
+
+Pass arguments to commands using the $ARGUMENTS placeholder.
+
+```
+---description: Create a new component---
+Create a new React component named $ARGUMENTS with TypeScript support.Include proper typing and basic structure.
+```
+
+Run the command with arguments:
+
+```
+/component Button
+```
+
+And $ARGUMENTS will be replaced with Button.
+
+You can also access individual arguments using positional parameters:
+
+- $1 - First argument
+- $2 - Second argument
+- $3 - Third argument
+- And so on…
+
+For example:
+
+```
+---description: Create a new file with content---
+Create a file named $1 in the directory $2with the following content: $3
+```
+
+Run the command:
+
+```
+/create-file config.json src "{ \"key\": \"value\" }"
+```
+
+This replaces:
+
+- $1 with config.json
+- $2 with src
+- $3 with { "key": "value" }
+
+---
+
+### Shell output
+
+Use !command to inject bash command output into your prompt.
+
+For example, to create a custom command that analyzes test coverage:
+
+```
+---description: Analyze test coverage---
+Here are the current test results:!`npm test`
+Based on these results, suggest improvements to increase coverage.
+```
+
+Or to review recent changes:
+
+```
+---description: Review recent changes---
+Recent git commits:!`git log --oneline -10`
+Review these changes and suggest any improvements.
+```
+
+Commands run in your project’s root directory and their output becomes part of the prompt.
+
+---
+
+### File references
+
+Include files in your command using @ followed by the filename.
+
+```
+---description: Review component---
+Review the component in @src/components/Button.tsx.Check for performance issues and suggest improvements.
+```
+
+The file content gets included in the prompt automatically.
+
+---
+
+## Options
+
+Let’s look at the configuration options in detail.
+
+---
+
+### Template
+
+The template option defines the prompt that will be sent to the LLM when the command is executed.
+
+```
+{  "command": {    "test": {      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes."    }  }}
+```
+
+This is a required config option.
+
+---
+
+### Description
+
+Use the description option to provide a brief description of what the command does.
+
+```
+{  "command": {    "test": {      "description": "Run tests with coverage"    }  }}
+```
+
+This is shown as the description in the TUI when you type in the command.
+
+---
+
+### Agent
+
+Use the agent config to optionally specify which agent should execute this command. If this is a subagent the command will trigger a subagent invocation by default. To disable this behavior, set subtask to false.
+
+```
+{  "command": {    "review": {      "agent": "plan"    }  }}
+```
+
+This is an optional config option. If not specified, defaults to your current agent.
+
+---
+
+### Subtask
+
+Use the subtask boolean to force the command to trigger a subagent invocation. This is useful if you want the command to not pollute your primary context and will force the agent to act as a subagent, even if mode is set to primary on the agent configuration.
+
+```
+{  "command": {    "analyze": {      "subtask": true    }  }}
+```
+
+This is an optional config option.
+
+---
+
+### Model
+
+Use the model config to override the default model for this command.
+
+```
+{  "command": {    "analyze": {      "model": "anthropic/claude-3-5-sonnet-20241022"    }  }}
+```
+
+This is an optional config option.
+
+---
+
+## Built-in
+
+opencode includes several built-in commands like /init, /undo, /redo, /share, /help; learn more.
+
+If you define a custom command with the same name, it will override the built-in command.

homelab/raw/articles/opencode/docs/config.md

@@ -0,0 +1,556 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/config/
+scraped: 2026-04-28T21:02:10.402906+00:00
+content_hash: 684c343f
+---
+# Config
+
+Using the OpenCode JSON config.
+
+You can configure OpenCode using a JSON config file.
+
+---
+
+## Format
+
+OpenCode supports both JSON and JSONC (JSON with Comments) formats.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "model": "anthropic/claude-sonnet-4-5",  "autoupdate": true,  "server": {    "port": 4096,  },}
+```
+
+---
+
+## Locations
+
+You can place your config in a couple of different locations and they have a different order of precedence.
+
+Configuration files are merged together, not replaced. Settings from the following config locations are combined. Later configs override earlier ones only for conflicting keys. Non-conflicting settings from all configs are preserved.
+
+For example, if your global config sets autoupdate: true and your project config sets model: "anthropic/claude-sonnet-4-5", the final configuration will include both settings.
+
+---
+
+### Precedence order
+
+Config sources are loaded in this order (later sources override earlier ones):
+
+1. Remote config (from .well-known/opencode) - organizational defaults
+2. Global config (~/.config/opencode/opencode.json) - user preferences
+3. Custom config (OPENCODE_CONFIG env var) - custom overrides
+4. Project config (opencode.json in project) - project-specific settings
+5. .opencode directories - agents, commands, plugins
+6. Inline config (OPENCODE_CONFIG_CONTENT env var) - runtime overrides
+7. Managed config files (/Library/Application Support/opencode/ on macOS) - admin-controlled
+8. macOS managed preferences (.mobileconfig via MDM) - highest priority, not user-overridable
+
+This means project configs can override global defaults, and global configs can override remote organizational defaults. Managed settings override everything.
+
+---
+
+### Remote
+
+Organizations can provide default configuration via the .well-known/opencode endpoint. This is fetched automatically when you authenticate with a provider that supports it.
+
+Remote config is loaded first, serving as the base layer. All other config sources (global, project) can override these defaults.
+
+For example, if your organization provides MCP servers that are disabled by default:
+
+```
+{  "mcp": {    "jira": {      "type": "remote",      "url": "https://jira.example.com/mcp",      "enabled": false    }  }}
+```
+
+You can enable specific servers in your local config:
+
+```
+{  "mcp": {    "jira": {      "type": "remote",      "url": "https://jira.example.com/mcp",      "enabled": true    }  }}
+```
+
+---
+
+### Global
+
+Place your global OpenCode config in ~/.config/opencode/opencode.json. Use global config for user-wide server/runtime preferences like providers, models, and permissions.
+
+For TUI-specific settings, use ~/.config/opencode/tui.json.
+
+Global config overrides remote organizational defaults.
+
+---
+
+### Per project
+
+Add opencode.json in your project root. Project config has the highest precedence among standard config files - it overrides both global and remote configs.
+
+For project-specific TUI settings, add tui.json alongside it.
+
+When OpenCode starts up, it looks for a config file in the current directory or traverse up to the nearest Git directory.
+
+This is also safe to be checked into Git and uses the same schema as the global one.
+
+---
+
+### Custom path
+
+Specify a custom config file path using the OPENCODE_CONFIG environment variable.
+
+```
+export OPENCODE_CONFIG=/path/to/my/custom-config.jsonopencode run "Hello world"
+```
+
+Custom config is loaded between global and project configs in the precedence order.
+
+---
+
+### Custom directory
+
+Specify a custom config directory using the OPENCODE_CONFIG_DIR environment variable. This directory will be searched for agents, commands, modes, and plugins just like the standard .opencode directory, and should follow the same structure.
+
+```
+export OPENCODE_CONFIG_DIR=/path/to/my/config-directoryopencode run "Hello world"
+```
+
+The custom directory is loaded after the global config and .opencode directories, so it can override their settings.
+
+---
+
+### Managed settings
+
+Organizations can enforce configuration that users cannot override. Managed settings are loaded at the highest priority tier.
+
+#### File-based
+
+Drop an opencode.json or opencode.jsonc file in the system managed config directory:
+
+| Platform | Path |
+|---|---|
+| macOS | /Library/Application Support/opencode/ |
+| Linux | /etc/opencode/ |
+| Windows | %ProgramData%\opencode |
+
+These directories require admin/root access to write, so users cannot modify them.
+
+#### macOS managed preferences
+
+On macOS, OpenCode reads managed preferences from the ai.opencode.managed preference domain. Deploy a .mobileconfig via MDM (Jamf, Kandji, FleetDM) and the settings are enforced automatically.
+
+OpenCode checks these paths:
+
+1. /Library/Managed Preferences/<user>/ai.opencode.managed.plist
+2. /Library/Managed Preferences/ai.opencode.managed.plist
+
+The plist keys map directly to opencode.json fields. MDM metadata keys (PayloadUUID, PayloadType, etc.) are stripped automatically.
+
+Creating a .mobileconfig
+
+Use the ai.opencode.managed PayloadType. The OpenCode config keys go directly in the payload dict:
+
+```
+<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"  "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict>  <key>PayloadContent</key>  <array>    <dict>      <key>PayloadType</key>      <string>ai.opencode.managed</string>      <key>PayloadIdentifier</key>      <string>com.example.opencode.config</string>      <key>PayloadUUID</key>      <string>GENERATE-YOUR-OWN-UUID</string>      <key>PayloadVersion</key>      <integer>1</integer>      <key>share</key>      <string>disabled</string>      <key>server</key>      <dict>        <key>hostname</key>        <string>127.0.0.1</string>      </dict>      <key>permission</key>      <dict>        <key>*</key>        <string>ask</string>        <key>bash</key>        <dict>          <key>*</key>          <string>ask</string>          <key>rm -rf *</key>          <string>deny</string>        </dict>      </dict>    </dict>  </array>  <key>PayloadType</key>  <string>Configuration</string>  <key>PayloadIdentifier</key>  <string>com.example.opencode</string>  <key>PayloadUUID</key>  <string>GENERATE-YOUR-OWN-UUID</string>  <key>PayloadVersion</key>  <integer>1</integer></dict></plist>
+```
+
+Generate unique UUIDs with uuidgen. Customize the settings to match your organization’s requirements.
+
+Deploying via MDM
+
+- Jamf Pro: Computers > Configuration Profiles > Upload > scope to target devices or smart groups
+- FleetDM: Add the .mobileconfig to your gitops repo under mdm.macos_settings.custom_settings and run fleetctl apply
+
+Verifying on a device
+
+Double-click the .mobileconfig to install locally for testing (shows in System Settings > Privacy & Security > Profiles), then run:
+
+```
+opencode debug config
+```
+
+All managed preference keys appear in the resolved config and cannot be overridden by user or project configuration.
+
+---
+
+## Schema
+
+The server/runtime config schema is defined in opencode.ai/config.json.
+
+TUI config uses opencode.ai/tui.json.
+
+Your editor should be able to validate and autocomplete based on the schema.
+
+---
+
+### TUI
+
+Use a dedicated tui.json (or tui.jsonc) file for TUI-specific settings.
+
+```
+{  "$schema": "https://opencode.ai/tui.json",  "scroll_speed": 3,  "scroll_acceleration": {    "enabled": true  },  "diff_style": "auto",  "mouse": true}
+```
+
+Use OPENCODE_TUI_CONFIG to point to a custom TUI config file.
+
+Legacy theme, keybinds, and tui keys in opencode.json are deprecated and automatically migrated when possible.
+
+---
+
+### Server
+
+You can configure server settings for the opencode serve and opencode web commands through the server option.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "server": {    "port": 4096,    "hostname": "0.0.0.0",    "mdns": true,    "mdnsDomain": "myproject.local",    "cors": ["http://localhost:5173"]  }}
+```
+
+Available options:
+
+- port - Port to listen on.
+- hostname - Hostname to listen on. When mdns is enabled and no hostname is set, defaults to 0.0.0.0.
+- mdns - Enable mDNS service discovery. This allows other devices on the network to discover your OpenCode server.
+- mdnsDomain - Custom domain name for mDNS service. Defaults to opencode.local. Useful for running multiple instances on the same network.
+- cors - Additional origins to allow for CORS when using the HTTP server from a browser-based client. Values must be full origins (scheme + host + optional port), eg https://app.example.com.
+
+Learn more about the server here.
+
+---
+
+### Shell
+
+You can configure the shell used for the interactive terminal using the shell option. Compatible shells are also used for agent tool calls.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "shell": "pwsh"}
+```
+
+If not specified, OpenCode will automatically discover and use a sensible default based on your operating system (e.g. pwsh or cmd.exe on Windows, /bin/zsh or /bin/bash on macOS/Linux). You can provide an absolute path or a short name.
+
+---
+
+### Tools
+
+You can manage the tools an LLM can use through the tools option.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "tools": {    "write": false,    "bash": false  }}
+```
+
+Learn more about tools here.
+
+---
+
+### Models
+
+You can configure the providers and models you want to use in your OpenCode config through the provider, model and small_model options.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {},  "model": "anthropic/claude-sonnet-4-5",  "small_model": "anthropic/claude-haiku-4-5"}
+```
+
+The small_model option configures a separate model for lightweight tasks like title generation. By default, OpenCode tries to use a cheaper model if one is available from your provider, otherwise it falls back to your main model.
+
+Provider options can include timeout, chunkTimeout, and setCacheKey:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "anthropic": {      "options": {        "timeout": 600000,        "chunkTimeout": 30000,        "setCacheKey": true      }    }  }}
+```
+
+- timeout - Request timeout in milliseconds (default: 300000). Set to false to disable.
+- chunkTimeout - Timeout in milliseconds between streamed response chunks. If no chunk arrives in time, the request is aborted.
+- setCacheKey - Ensure a cache key is always set for designated provider.
+
+You can also configure local models. Learn more.
+
+---
+
+#### Provider-Specific Options
+
+Some providers support additional configuration options beyond the generic timeout and apiKey settings.
+
+##### Amazon Bedrock
+
+Amazon Bedrock supports AWS-specific configuration:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "amazon-bedrock": {      "options": {        "region": "us-east-1",        "profile": "my-aws-profile",        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"      }    }  }}
+```
+
+- region - AWS region for Bedrock (defaults to AWS_REGION env var or us-east-1)
+- profile - AWS named profile from ~/.aws/credentials (defaults to AWS_PROFILE env var)
+- endpoint - Custom endpoint URL for VPC endpoints. This is an alias for the generic baseURL option using AWS-specific terminology. If both are specified, endpoint takes precedence.
+
+Learn more about Amazon Bedrock configuration.
+
+---
+
+### Themes
+
+Set your UI theme in tui.json.
+
+```
+{  "$schema": "https://opencode.ai/tui.json",  "theme": "tokyonight"}
+```
+
+Learn more here.
+
+---
+
+### Agents
+
+You can configure specialized agents for specific tasks through the agent option.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "agent": {    "code-reviewer": {      "description": "Reviews code for best practices and potential issues",      "model": "anthropic/claude-sonnet-4-5",      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",      "tools": {        // Disable file modification tools for review-only agent        "write": false,        "edit": false,      },    },  },}
+```
+
+You can also define agents using markdown files in ~/.config/opencode/agents/ or .opencode/agents/. Learn more here.
+
+---
+
+### Default agent
+
+You can set the default agent using the default_agent option. This determines which agent is used when none is explicitly specified.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "default_agent": "plan"}
+```
+
+The default agent must be a primary agent (not a subagent). This can be a built-in agent like "build" or "plan", or a custom agent you’ve defined. If the specified agent doesn’t exist or is a subagent, OpenCode will fall back to "build" with a warning.
+
+This setting applies across all interfaces: TUI, CLI (opencode run), desktop app, and GitHub Action.
+
+---
+
+### Sharing
+
+You can configure the share feature through the share option.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "share": "manual"}
+```
+
+This takes:
+
+- "manual" - Allow manual sharing via commands (default)
+- "auto" - Automatically share new conversations
+- "disabled" - Disable sharing entirely
+
+By default, sharing is set to manual mode where you need to explicitly share conversations using the /share command.
+
+---
+
+### Commands
+
+You can configure custom commands for repetitive tasks through the command option.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "command": {    "test": {      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",      "description": "Run tests with coverage",      "agent": "build",      "model": "anthropic/claude-haiku-4-5",    },    "component": {      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",      "description": "Create a new component",    },  },}
+```
+
+You can also define commands using markdown files in ~/.config/opencode/commands/ or .opencode/commands/. Learn more here.
+
+---
+
+### Keybinds
+
+Customize keybinds in tui.json.
+
+```
+{  "$schema": "https://opencode.ai/tui.json",  "keybinds": {}}
+```
+
+Learn more here.
+
+---
+
+### Snapshot
+
+OpenCode uses snapshots to track file changes during agent operations, enabling you to undo and revert changes within a session. Snapshots are enabled by default.
+
+For large repositories or projects with many submodules, the snapshot system can cause slow indexing and significant disk usage as it tracks all changes using an internal git repository. You can disable snapshots using the snapshot option.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "snapshot": false}
+```
+
+Note that disabling snapshots means changes made by the agent cannot be rolled back through the UI.
+
+---
+
+### Autoupdate
+
+OpenCode will automatically download any new updates when it starts up. You can disable this with the autoupdate option.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "autoupdate": false}
+```
+
+If you don’t want updates but want to be notified when a new version is available, set autoupdate to "notify". Notice that this only works if it was not installed using a package manager such as Homebrew.
+
+---
+
+### Formatters
+
+You can configure code formatters through the formatter option.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "formatter": {    "prettier": {      "disabled": true    },    "custom-prettier": {      "command": ["npx", "prettier", "--write", "$FILE"],      "environment": {        "NODE_ENV": "development"      },      "extensions": [".js", ".ts", ".jsx", ".tsx"]    }  }}
+```
+
+Learn more about formatters here.
+
+---
+
+### Permissions
+
+By default, opencode allows all operations without requiring explicit approval. You can change this using the permission option.
+
+For example, to ensure that the edit and bash tools require user approval:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "edit": "ask",    "bash": "ask"  }}
+```
+
+Learn more about permissions here.
+
+---
+
+### Compaction
+
+You can control context compaction behavior through the compaction option.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "compaction": {    "auto": true,    "prune": true,    "reserved": 10000  }}
+```
+
+- auto - Automatically compact the session when context is full (default: true).
+- prune - Remove old tool outputs to save tokens (default: true).
+- reserved - Token buffer for compaction. Leaves enough window to avoid overflow during compaction
+
+---
+
+### Watcher
+
+You can configure file watcher ignore patterns through the watcher option.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "watcher": {    "ignore": ["node_modules/**", "dist/**", ".git/**"]  }}
+```
+
+Patterns follow glob syntax. Use this to exclude noisy directories from file watching.
+
+---
+
+### MCP servers
+
+You can configure MCP servers you want to use through the mcp option.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {}}
+```
+
+Learn more here.
+
+---
+
+### Plugins
+
+Plugins extend OpenCode with custom tools, hooks, and integrations.
+
+Place plugin files in .opencode/plugins/ or ~/.config/opencode/plugins/. You can also load plugins from npm through the plugin option.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]}
+```
+
+Learn more here.
+
+---
+
+### Instructions
+
+You can configure the instructions for the model you’re using through the instructions option.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]}
+```
+
+This takes an array of paths and glob patterns to instruction files. Learn more about rules here.
+
+---
+
+### Disabled providers
+
+You can disable providers that are loaded automatically through the disabled_providers option. This is useful when you want to prevent certain providers from being loaded even if their credentials are available.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "disabled_providers": ["openai", "gemini"]}
+```
+
+The disabled_providers option accepts an array of provider IDs. When a provider is disabled:
+
+- It won’t be loaded even if environment variables are set.
+- It won’t be loaded even if API keys are configured through the /connect command.
+- The provider’s models won’t appear in the model selection list.
+
+---
+
+### Enabled providers
+
+You can specify an allowlist of providers through the enabled_providers option. When set, only the specified providers will be enabled and all others will be ignored.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "enabled_providers": ["anthropic", "openai"]}
+```
+
+This is useful when you want to restrict OpenCode to only use specific providers rather than disabling them one by one.
+
+If a provider appears in both enabled_providers and disabled_providers, the disabled_providers takes priority for backwards compatibility.
+
+---
+
+### Experimental
+
+The experimental key contains options that are under active development.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "experimental": {}}
+```
+
+---
+
+## Variables
+
+You can use variable substitution in your config files to reference environment variables and file contents.
+
+---
+
+### Env vars
+
+Use {env:VARIABLE_NAME} to substitute environment variables:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "model": "{env:OPENCODE_MODEL}",  "provider": {    "anthropic": {      "models": {},      "options": {        "apiKey": "{env:ANTHROPIC_API_KEY}"      }    }  }}
+```
+
+If the environment variable is not set, it will be replaced with an empty string.
+
+---
+
+### Files
+
+Use {file:path/to/file} to substitute the contents of a file:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "instructions": ["./custom-instructions.md"],  "provider": {    "openai": {      "options": {        "apiKey": "{file:~/.secrets/openai-key}"      }    }  }}
+```
+
+File paths can be:
+
+- Relative to the config file directory
+- Or absolute paths starting with / or ~
+
+These are useful for:
+
+- Keeping sensitive data like API keys in separate files.
+- Including large instruction files without cluttering your config.
+- Sharing common configuration snippets across multiple config files.

homelab/raw/articles/opencode/docs/custom-tools.md

@@ -0,0 +1,121 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/custom-tools/
+scraped: 2026-04-28T21:02:14.861865+00:00
+content_hash: 34c22729
+---
+# Custom Tools
+
+Create tools the LLM can call in opencode.
+
+Custom tools are functions you create that the LLM can call during conversations. They work alongside opencode’s built-in tools like read, write, and bash.
+
+---
+
+## Creating a tool
+
+Tools are defined as TypeScript or JavaScript files. However, the tool definition can invoke scripts written in any language — TypeScript or JavaScript is only used for the tool definition itself.
+
+---
+
+### Location
+
+They can be defined:
+
+- Locally by placing them in the .opencode/tools/ directory of your project.
+- Or globally, by placing them in ~/.config/opencode/tools/.
+
+---
+
+### Structure
+
+The easiest way to create tools is using the tool() helper which provides type-safety and validation.
+
+```
+import { tool } from "@opencode-ai/plugin"
+export default tool({  description: "Query the project database",  args: {    query: tool.schema.string().describe("SQL query to execute"),  },  async execute(args) {    // Your database logic here    return `Executed query: ${args.query}`  },})
+```
+
+The filename becomes the tool name. The above creates a database tool.
+
+---
+
+#### Multiple tools per file
+
+You can also export multiple tools from a single file. Each export becomes a separate tool with the name <filename>_<exportname>:
+
+```
+import { tool } from "@opencode-ai/plugin"
+export const add = tool({  description: "Add two numbers",  args: {    a: tool.schema.number().describe("First number"),    b: tool.schema.number().describe("Second number"),  },  async execute(args) {    return args.a + args.b  },})
+export const multiply = tool({  description: "Multiply two numbers",  args: {    a: tool.schema.number().describe("First number"),    b: tool.schema.number().describe("Second number"),  },  async execute(args) {    return args.a * args.b  },})
+```
+
+This creates two tools: math_add and math_multiply.
+
+---
+
+#### Name collisions with built-in tools
+
+Custom tools are keyed by tool name. If a custom tool uses the same name as a built-in tool, the custom tool takes precedence.
+
+For example, this file replaces the built-in bash tool:
+
+```
+import { tool } from "@opencode-ai/plugin"
+export default tool({  description: "Restricted bash wrapper",  args: {    command: tool.schema.string(),  },  async execute(args) {    return `blocked: ${args.command}`  },})
+```
+
+---
+
+### Arguments
+
+You can use tool.schema, which is just Zod, to define argument types.
+
+```
+args: {  query: tool.schema.string().describe("SQL query to execute")}
+```
+
+You can also import Zod directly and return a plain object:
+
+```
+import { z } from "zod"
+export default {  description: "Tool description",  args: {    param: z.string().describe("Parameter description"),  },  async execute(args, context) {    // Tool implementation    return "result"  },}
+```
+
+---
+
+### Context
+
+Tools receive context about the current session:
+
+```
+import { tool } from "@opencode-ai/plugin"
+export default tool({  description: "Get project information",  args: {},  async execute(args, context) {    // Access context information    const { agent, sessionID, messageID, directory, worktree } = context    return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}, Directory: ${directory}, Worktree: ${worktree}`  },})
+```
+
+Use context.directory for the session working directory. Use context.worktree for the git worktree root.
+
+---
+
+## Examples
+
+### Write a tool in Python
+
+You can write your tools in any language you want. Here’s an example that adds two numbers using Python.
+
+First, create the tool as a Python script:
+
+```
+import sys
+a = int(sys.argv[1])b = int(sys.argv[2])print(a + b)
+```
+
+Then create the tool definition that invokes it:
+
+```
+import { tool } from "@opencode-ai/plugin"import path from "path"
+export default tool({  description: "Add two numbers using Python",  args: {    a: tool.schema.number().describe("First number"),    b: tool.schema.number().describe("Second number"),  },  async execute(args, context) {    const script = path.join(context.worktree, ".opencode/tools/add.py")    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()    return result.trim()  },})
+```
+
+Here we are using the Bun.$ utility to run the Python script.

homelab/raw/articles/opencode/docs/ecosystem.md

@@ -0,0 +1,83 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/ecosystem/
+scraped: 2026-04-28T21:02:06.386974+00:00
+content_hash: 1d236fc1
+---
+# Ecosystem
+
+Projects and integrations built with OpenCode.
+
+A collection of community projects built on OpenCode.
+
+You can also check out awesome-opencode and opencode.cafe, a community that aggregates the ecosystem and community.
+
+---
+
+## Plugins
+
+| Name | Description |
+|---|---|
+| opencode-daytona | Automatically run OpenCode sessions in isolated Daytona sandboxes with git sync and live previews |
+| opencode-helicone-session | Automatically inject Helicone session headers for request grouping |
+| opencode-type-inject | Auto-inject TypeScript/Svelte types into file reads with lookup tools |
+| opencode-openai-codex-auth | Use your ChatGPT Plus/Pro subscription instead of API credits |
+| opencode-gemini-auth | Use your existing Gemini plan instead of API billing |
+| opencode-antigravity-auth | Use Antigravity’s free models instead of API billing |
+| opencode-devcontainers | Multi-branch devcontainer isolation with shallow clones and auto-assigned ports |
+| opencode-google-antigravity-auth | Google Antigravity OAuth Plugin, with support for Google Search, and more robust API handling |
+| opencode-dynamic-context-pruning | Optimize token usage by pruning obsolete tool outputs |
+| opencode-vibeguard | Redact secrets/PII into VibeGuard-style placeholders before LLM calls; restore locally |
+| opencode-websearch-cited | Add native websearch support for supported providers with Google grounded style |
+| opencode-pty | Enables AI agents to run background processes in a PTY, send interactive input to them. |
+| opencode-shell-strategy | Instructions for non-interactive shell commands - prevents hangs from TTY-dependent operations |
+| opencode-wakatime | Track OpenCode usage with Wakatime |
+| opencode-md-table-formatter | Clean up markdown tables produced by LLMs |
+| opencode-morph-fast-apply | 10x faster code editing with Morph Fast Apply API and lazy edit markers |
+| opencode-morph-plugin | Fast Apply editing, WarpGrep codebase search, and context compaction via Morph |
+| oh-my-opencode | Background agents, pre-built LSP/AST/MCP tools, curated agents, Claude Code compatible |
+| opencode-notificator | Desktop notifications and sound alerts for OpenCode sessions |
+| opencode-notifier | Desktop notifications and sound alerts for permission, completion, and error events |
+| opencode-zellij-namer | AI-powered automatic Zellij session naming based on OpenCode context |
+| opencode-skillful | Allow OpenCode agents to lazy load prompts on demand with skill discovery and injection |
+| opencode-supermemory | Persistent memory across sessions using Supermemory |
+| @plannotator/opencode | Interactive plan review with visual annotation and private/offline sharing |
+| @openspoon/subtask2 | Extend opencode /commands into a powerful orchestration system with granular flow control |
+| opencode-scheduler | Schedule recurring jobs using launchd (Mac) or systemd (Linux) with cron syntax |
+| opencode-conductor | Protocol-Driven Workflow: Automation of the Context -> Spec -> Plan -> Implement lifecycle. |
+| micode | Structured Brainstorm → Plan → Implement workflow with session continuity |
+| octto | Interactive browser UI for AI brainstorming with multi-question forms |
+| opencode-background-agents | Claude Code-style background agents with async delegation and context persistence |
+| opencode-notify | Native OS notifications for OpenCode – know when tasks complete |
+| opencode-workspace | Bundled multi-agent orchestration harness – 16 components, one install |
+| opencode-worktree | Zero-friction git worktrees for OpenCode |
+| opencode-sentry-monitor | Trace and debug your AI agents with Sentry AI Monitoring |
+| opencode-firecrawl | Web scraping, crawling, and search via the Firecrawl CLI |
+
+---
+
+## Projects
+
+| Name | Description |
+|---|---|
+| kimaki | Discord bot to control OpenCode sessions, built on the SDK |
+| opencode.nvim | Neovim plugin for editor-aware prompts, built on the API |
+| portal | Mobile-first web UI for OpenCode over Tailscale/VPN |
+| opencode plugin template | Template for building OpenCode plugins |
+| opencode.nvim | Neovim frontend for opencode - a terminal-based AI coding agent |
+| ai-sdk-provider-opencode-sdk | Vercel AI SDK provider for using OpenCode via @opencode-ai/sdk |
+| OpenChamber | Web / Desktop App and VS Code Extension for OpenCode |
+| OpenCode-Obsidian | Obsidian plugin that embeds OpenCode in Obsidian’s UI |
+| OpenWork | An open-source alternative to Claude Cowork, powered by OpenCode |
+| ocx | OpenCode extension manager with portable, isolated profiles. |
+| CodeNomad | Desktop, Web, Mobile and Remote Client App for OpenCode |
+
+---
+
+## Agents
+
+| Name | Description |
+|---|---|
+| Agentic | Modular AI agents and commands for structured development |
+| opencode-agents | Configs, prompts, agents, and plugins for enhanced workflows |

homelab/raw/articles/opencode/docs/enterprise.md

@@ -0,0 +1,136 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/enterprise/
+scraped: 2026-04-28T21:02:08.075106+00:00
+content_hash: c8c067cf
+---
+# Enterprise
+
+Using OpenCode securely in your organization.
+
+OpenCode Enterprise is for organizations that want to ensure that their code and data never leaves their infrastructure. It can do this by using a centralized config that integrates with your SSO and internal AI gateway.
+
+To get started with OpenCode Enterprise:
+
+1. Do a trial internally with your team.
+2. Contact us to discuss pricing and implementation options.
+
+---
+
+## Trial
+
+OpenCode is open source and does not store any of your code or context data, so your developers can simply get started and carry out a trial.
+
+---
+
+### Data handling
+
+OpenCode does not store your code or context data. All processing happens locally or through direct API calls to your AI provider.
+
+This means that as long as you are using a provider you trust, or an internal AI gateway, you can use OpenCode securely.
+
+The only caveat here is the optional /share feature.
+
+---
+
+#### Sharing conversations
+
+If a user enables the /share feature, the conversation and the data associated with it are sent to the service we use to host these share pages at opencode.ai.
+
+The data is currently served through our CDN’s edge network, and is cached on the edge near your users.
+
+We recommend you disable this for your trial.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "share": "disabled"}
+```
+
+Learn more about sharing.
+
+---
+
+### Code ownership
+
+You own all code produced by OpenCode. There are no licensing restrictions or ownership claims.
+
+---
+
+## Pricing
+
+We use a per-seat model for OpenCode Enterprise. If you have your own LLM gateway, we do not charge for tokens used. For further details about pricing and implementation options, contact us.
+
+---
+
+## Deployment
+
+Once you have completed your trial and you are ready to use OpenCode at your organization, you can contact us to discuss pricing and implementation options.
+
+---
+
+### Central Config
+
+We can set up OpenCode to use a single central config for your entire organization.
+
+This centralized config can integrate with your SSO provider and ensures all users access only your internal AI gateway.
+
+---
+
+### SSO integration
+
+Through the central config, OpenCode can integrate with your organization’s SSO provider for authentication.
+
+This allows OpenCode to obtain credentials for your internal AI gateway through your existing identity management system.
+
+---
+
+### Internal AI gateway
+
+With the central config, OpenCode can also be configured to use only your internal AI gateway.
+
+You can also disable all other AI providers, ensuring all requests go through your organization’s approved infrastructure.
+
+---
+
+### Self-hosting
+
+While we recommend disabling the share pages to ensure your data never leaves your organization, we can also help you self-host them on your infrastructure.
+
+This is currently on our roadmap. If you’re interested, let us know.
+
+---
+
+## FAQ
+
+What is OpenCode Enterprise?
+OpenCode Enterprise is for organizations that want to ensure that their code and data never leaves their infrastructure. It can do this by using a centralized config that integrates with your SSO and internal AI gateway.
+
+How do I get started with OpenCode Enterprise?
+Simply start with an internal trial with your team. OpenCode by default does not store your code or context data, making it easy to get started.
+
+Then contact us to discuss pricing and implementation options.
+
+How does enterprise pricing work?
+We offer per-seat enterprise pricing. If you have your own LLM gateway, we do not charge for tokens used. For further details, contact us for a custom quote based on your organization’s needs.
+
+Is my data secure with OpenCode Enterprise?
+Yes. OpenCode does not store your code or context data. All processing happens locally or through direct API calls to your AI provider. With central config and SSO integration, your data remains secure within your organization’s infrastructure.
+
+Can we use our own private NPM registry?
+OpenCode supports private npm registries through Bun’s native .npmrc file support. If your organization uses a private registry, such as JFrog Artifactory, Nexus, or similar, ensure developers are authenticated before running OpenCode.
+
+To set up authentication with your private registry:
+
+```
+npm login --registry=https://your-company.jfrog.io/api/npm/npm-virtual/
+```
+
+This creates ~/.npmrc with authentication details. OpenCode will automatically pick this up.
+
+Alternatively, you can manually configure a .npmrc file:
+
+```
+registry=https://your-company.jfrog.io/api/npm/npm-virtual///your-company.jfrog.io/api/npm/npm-virtual/:_authToken=${NPM_AUTH_TOKEN}
+```
+
+Developers must be logged into the private registry before running OpenCode to ensure packages can be installed from your enterprise registry.

homelab/raw/articles/opencode/docs/formatters.md

@@ -0,0 +1,110 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/formatters/
+scraped: 2026-04-28T21:02:12.276311+00:00
+content_hash: 6c06fc44
+---
+# Formatters
+
+OpenCode uses language specific formatters.
+
+OpenCode automatically formats files after they are written or edited using language-specific formatters. This ensures that the code that is generated follows the code styles of your project.
+
+---
+
+## Built-in
+
+OpenCode comes with several built-in formatters for popular languages and frameworks. Below is a list of the formatters, supported file extensions, and commands or config options it needs.
+
+| Formatter | Extensions | Requirements |
+|---|---|---|
+| air | .R | air command available |
+| biome | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, and more | biome.json(c) config file |
+| cargofmt | .rs | cargo fmt command available |
+| clang-format | .c, .cpp, .h, .hpp, .ino, and more | .clang-format config file |
+| cljfmt | .clj, .cljs, .cljc, .edn | cljfmt command available |
+| dart | .dart | dart command available |
+| dfmt | .d | dfmt command available |
+| gleam | .gleam | gleam command available |
+| gofmt | .go | gofmt command available |
+| htmlbeautifier | .erb, .html.erb | htmlbeautifier command available |
+| ktlint | .kt, .kts | ktlint command available |
+| mix | .ex, .exs, .eex, .heex, .leex, .neex, .sface | mix command available |
+| nixfmt | .nix | nixfmt command available |
+| ocamlformat | .ml, .mli | ocamlformat command available and .ocamlformat config file |
+| ormolu | .hs | ormolu command available |
+| oxfmt (Experimental) | .js, .jsx, .ts, .tsx | oxfmt dependency in package.json and an experimental env variable flag |
+| pint | .php | laravel/pint dependency in composer.json |
+| prettier | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, and more | prettier dependency in package.json |
+| rubocop | .rb, .rake, .gemspec, .ru | rubocop command available |
+| ruff | .py, .pyi | ruff command available with config |
+| rustfmt | .rs | rustfmt command available |
+| shfmt | .sh, .bash | shfmt command available |
+| standardrb | .rb, .rake, .gemspec, .ru | standardrb command available |
+| terraform | .tf, .tfvars | terraform command available |
+| uv | .py, .pyi | uv command available |
+| zig | .zig, .zon | zig command available |
+
+So if your project has prettier in your package.json, OpenCode will automatically use it.
+
+---
+
+## How it works
+
+When OpenCode writes or edits a file, it:
+
+1. Checks the file extension against all enabled formatters.
+2. Runs the appropriate formatter command on the file.
+3. Applies the formatting changes automatically.
+
+This process happens in the background, ensuring your code styles are maintained without any manual steps.
+
+---
+
+## Configure
+
+You can customize formatters through the formatter section in your OpenCode config.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "formatter": {}}
+```
+
+Each formatter configuration supports the following:
+
+| Property | Type | Description |
+|---|---|---|
+| disabled | boolean | Set this to true to disable the formatter |
+| command | string[] | The command to run for formatting |
+| environment | object | Environment variables to set when running the formatter |
+| extensions | string[] | File extensions this formatter should handle |
+
+Let’s look at some examples.
+
+---
+
+### Disabling formatters
+
+To disable all formatters globally, set formatter to false:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "formatter": false}
+```
+
+To disable a specific formatter, set disabled to true:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "formatter": {    "prettier": {      "disabled": true    }  }}
+```
+
+---
+
+### Custom formatters
+
+You can override the built-in formatters or add new ones by specifying the command, environment variables, and file extensions:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "formatter": {    "prettier": {      "command": ["npx", "prettier", "--write", "$FILE"],      "environment": {        "NODE_ENV": "development"      },      "extensions": [".js", ".ts", ".jsx", ".tsx"]    },    "custom-markdown-formatter": {      "command": ["deno", "fmt", "$FILE"],      "extensions": [".md"]    }  }}
+```
+
+The $FILE placeholder in the command will be replaced with the path to the file being formatted.

homelab/raw/articles/opencode/docs/github.md

@@ -0,0 +1,137 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/github/
+scraped: 2026-04-28T21:02:08.343881+00:00
+content_hash: 6383fc1d
+---
+# GitHub
+
+Use OpenCode in GitHub issues and pull-requests.
+
+OpenCode integrates with your GitHub workflow. Mention /opencode or /oc in your comment, and OpenCode will execute tasks within your GitHub Actions runner.
+
+---
+
+## Features
+
+- Triage issues: Ask OpenCode to look into an issue and explain it to you.
+- Fix and implement: Ask OpenCode to fix an issue or implement a feature. And it will work in a new branch and submits a PR with all the changes.
+- Secure: OpenCode runs inside your GitHub’s runners.
+
+---
+
+## Installation
+
+Run the following command in a project that is in a GitHub repo:
+
+```
+opencode github install
+```
+
+This will walk you through installing the GitHub app, creating the workflow, and setting up secrets.
+
+---
+
+### Manual Setup
+
+Or you can set it up manually.
+
+1. Install the GitHub app Head over to github.com/apps/opencode-agent. Make sure it’s installed on the target repository.
+2. Add the workflow Add the following workflow file to .github/workflows/opencode.yml in your repo. Make sure to set the appropriate model and required API keys in env. .github/workflows/opencode.ymlname: opencode on: issue_comment: types: [created] pull_request_review_comment: types: [created] jobs: opencode: if: | contains(github.event.comment.body, '/oc') || contains(github.event.comment.body, '/opencode') runs-on: ubuntu-latest permissions: id-token: write steps: - name: Checkout repository uses: actions/checkout@v6 with: fetch-depth: 1 persist-credentials: false - name: Run OpenCode uses: anomalyco/opencode/github@latest env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} with: model: anthropic/claude-sonnet-4-20250514 # share: true # github_token: xxxx
+3. Store the API keys in secrets In your organization or project settings, expand Secrets and variables on the left and select Actions. And add the required API keys.
+
+---
+
+## Configuration
+
+- model: The model to use with OpenCode. Takes the format of provider/model. This is required.
+- agent: The agent to use. Must be a primary agent. Falls back to default_agent from config or "build" if not found.
+- share: Whether to share the OpenCode session. Defaults to true for public repositories.
+- prompt: Optional custom prompt to override the default behavior. Use this to customize how OpenCode processes requests.
+- token: Optional GitHub access token for performing operations such as creating comments, committing changes, and opening pull requests. By default, OpenCode uses the installation access token from the OpenCode GitHub App, so commits, comments, and pull requests appear as coming from the app. Alternatively, you can use the GitHub Action runner’s built-in GITHUB_TOKEN without installing the OpenCode GitHub App. Just make sure to grant the required permissions in your workflow: permissions: id-token: write contents: write pull-requests: write issues: write You can also use a personal access tokens(PAT) if preferred.
+
+---
+
+## Supported Events
+
+OpenCode can be triggered by the following GitHub events:
+
+| Event Type | Triggered By | Details |
+|---|---|---|
+| issue_comment | Comment on an issue or PR | Mention /opencode or /oc in your comment. OpenCode reads context and can create branches, open PRs, or reply. |
+| pull_request_review_comment | Comment on specific code lines in a PR | Mention /opencode or /oc while reviewing code. OpenCode receives file path, line numbers, and diff context. |
+| issues | Issue opened or edited | Automatically trigger OpenCode when issues are created or modified. Requires prompt input. |
+| pull_request | PR opened or updated | Automatically trigger OpenCode when PRs are opened, synchronized, or reopened. Useful for automated reviews. |
+| schedule | Cron-based schedule | Run OpenCode on a schedule. Requires prompt input. Output goes to logs and PRs (no issue to comment on). |
+| workflow_dispatch | Manual trigger from GitHub UI | Trigger OpenCode on demand via Actions tab. Requires prompt input. Output goes to logs and PRs. |
+
+### Schedule Example
+
+Run OpenCode on a schedule to perform automated tasks:
+
+```
+name: Scheduled OpenCode Task
+on:  schedule:    - cron: "0 9 * * 1" # Every Monday at 9am UTC
+jobs:  opencode:    runs-on: ubuntu-latest    permissions:      id-token: write      contents: write      pull-requests: write      issues: write    steps:      - name: Checkout repository        uses: actions/checkout@v6        with:          persist-credentials: false
+      - name: Run OpenCode        uses: anomalyco/opencode/github@latest        env:          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}        with:          model: anthropic/claude-sonnet-4-20250514          prompt: |            Review the codebase for any TODO comments and create a summary.            If you find issues worth addressing, open an issue to track them.
+```
+
+For scheduled events, the prompt input is required since there’s no comment to extract instructions from. Scheduled workflows run without a user context to permission-check, so the workflow must grant contents: write and pull-requests: write if you expect OpenCode to create branches or PRs.
+
+---
+
+### Pull Request Example
+
+Automatically review PRs when they are opened or updated:
+
+```
+name: opencode-review
+on:  pull_request:    types: [opened, synchronize, reopened, ready_for_review]
+jobs:  review:    runs-on: ubuntu-latest    permissions:      id-token: write      contents: read      pull-requests: read      issues: read    steps:      - uses: actions/checkout@v6        with:          persist-credentials: false      - uses: anomalyco/opencode/github@latest        env:          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}        with:          model: anthropic/claude-sonnet-4-20250514          use_github_token: true          prompt: |            Review this pull request:            - Check for code quality issues            - Look for potential bugs            - Suggest improvements
+```
+
+For pull_request events, if no prompt is provided, OpenCode defaults to reviewing the pull request.
+
+---
+
+### Issues Triage Example
+
+Automatically triage new issues. This example filters to accounts older than 30 days to reduce spam:
+
+```
+name: Issue Triage
+on:  issues:    types: [opened]
+jobs:  triage:    runs-on: ubuntu-latest    permissions:      id-token: write      contents: write      pull-requests: write      issues: write    steps:      - name: Check account age        id: check        uses: actions/github-script@v7        with:          script: |            const user = await github.rest.users.getByUsername({              username: context.payload.issue.user.login            });            const created = new Date(user.data.created_at);            const days = (Date.now() - created) / (1000 * 60 * 60 * 24);            return days >= 30;          result-encoding: string
+      - uses: actions/checkout@v6        if: steps.check.outputs.result == 'true'        with:          persist-credentials: false
+      - uses: anomalyco/opencode/github@latest        if: steps.check.outputs.result == 'true'        env:          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}        with:          model: anthropic/claude-sonnet-4-20250514          prompt: |            Review this issue. If there's a clear fix or relevant docs:            - Provide documentation links            - Add error handling guidance for code examples            Otherwise, do not comment.
+```
+
+For issues events, the prompt input is required since there’s no comment to extract instructions from.
+
+---
+
+## Custom prompts
+
+Override the default prompt to customize OpenCode’s behavior for your workflow.
+
+```
+- uses: anomalyco/opencode/github@latest  with:    model: anthropic/claude-sonnet-4-5    prompt: |      Review this pull request:      - Check for code quality issues      - Look for potential bugs      - Suggest improvements
+```
+
+This is useful for enforcing specific review criteria, coding standards, or focus areas relevant to your project.
+
+---
+
+## Examples
+
+Here are some examples of how you can use OpenCode in GitHub.
+
+- Explain an issue Add this comment in a GitHub issue. /opencode explain this issue OpenCode will read the entire thread, including all comments, and reply with a clear explanation.
+- Fix an issue In a GitHub issue, say: /opencode fix this And OpenCode will create a new branch, implement the changes, and open a PR with the changes.
+- Review PRs and make changes Leave the following comment on a GitHub PR. Delete the attachment from S3 when the note is removed /oc OpenCode will implement the requested change and commit it to the same PR.
+- Review specific code lines Leave a comment directly on code lines in the PR’s “Files” tab. OpenCode automatically detects the file, line numbers, and diff context to provide precise responses. [Comment on specific lines in Files tab]/oc add error handling here When commenting on specific lines, OpenCode receives: The exact file being reviewed The specific lines of code The surrounding diff context Line number information This allows for more targeted requests without needing to specify file paths or line numbers manually.
+- The exact file being reviewed
+- The specific lines of code
+- The surrounding diff context
+- Line number information

homelab/raw/articles/opencode/docs/gitlab.md

@@ -0,0 +1,74 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/gitlab/
+scraped: 2026-04-28T21:02:15.327901+00:00
+content_hash: 649e608d
+---
+# GitLab
+
+Use OpenCode in GitLab issues and merge requests.
+
+OpenCode integrates with your GitLab workflow through your GitLab CI/CD pipeline or with GitLab Duo.
+
+In both cases, OpenCode will run on your GitLab runners.
+
+---
+
+## GitLab CI
+
+OpenCode works in a regular GitLab pipeline. You can build it into a pipeline as a CI component
+
+Here we are using a community-created CI/CD component for OpenCode — nagyv/gitlab-opencode.
+
+---
+
+### Features
+
+- Use custom configuration per job: Configure OpenCode with a custom configuration directory, for example ./config/#custom-directory to enable or disable functionality per OpenCode invocation.
+- Minimal setup: The CI component sets up OpenCode in the background, you only need to create the OpenCode configuration and the initial prompt.
+- Flexible: The CI component supports several inputs for customizing its behavior
+
+---
+
+### Setup
+
+1. Store your OpenCode authentication JSON as a File type CI environment variables under Settings > CI/CD > Variables. Make sure to mark them as “Masked and hidden”.
+2. Add the following to your .gitlab-ci.yml file. .gitlab-ci.ymlinclude: - component: $CI_SERVER_FQDN/nagyv/gitlab-opencode/opencode@2 inputs: config_dir: ${CI_PROJECT_DIR}/opencode-config auth_json: $OPENCODE_AUTH_JSON # The variable name for your OpenCode authentication JSON command: optional-custom-command message: "Your prompt here"
+
+For more inputs and use cases check out the docs for this component.
+
+---
+
+## GitLab Duo
+
+OpenCode integrates with your GitLab workflow. Mention @opencode in a comment, and OpenCode will execute tasks within your GitLab CI pipeline.
+
+---
+
+- Triage issues: Ask OpenCode to look into an issue and explain it to you.
+- Fix and implement: Ask OpenCode to fix an issue or implement a feature. It will create a new branch and raise a merge request with the changes.
+- Secure: OpenCode runs on your GitLab runners.
+
+---
+
+OpenCode runs in your GitLab CI/CD pipeline, here’s what you’ll need to set it up:
+
+1. Configure your GitLab environment
+2. Set up CI/CD
+3. Get an AI model provider API key
+4. Create a service account
+5. Configure CI/CD variables
+6. Create a flow config file, here’s an example: Flow configurationimage: node:22-slimcommands: - echo "Installing opencode" - npm install --global opencode-ai - echo "Installing glab" - export GITLAB_TOKEN=$GITLAB_TOKEN_OPENCODE - apt-get update --quiet && apt-get install --yes curl wget gpg git && rm --recursive --force /var/lib/apt/lists/* - curl --silent --show-error --location "https://raw.githubusercontent.com/upciti/wakemeops/main/assets/install_repository" | bash - apt-get install --yes glab - echo "Configuring glab" - echo $GITLAB_HOST - echo "Creating OpenCode auth configuration" - mkdir --parents ~/.local/share/opencode - | cat > ~/.local/share/opencode/auth.json << EOF { "anthropic": { "type": "api", "key": "$ANTHROPIC_API_KEY" } } EOF - echo "Configuring git" - git config --global user.email "opencode@gitlab.com" - git config --global user.name "OpenCode" - echo "Testing glab" - glab issue list - echo "Running OpenCode" - | opencode run " You are an AI assistant helping with GitLab operations. Context: $AI_FLOW_CONTEXT Task: $AI_FLOW_INPUT Event: $AI_FLOW_EVENT Please execute the requested task using the available GitLab tools. Be thorough in your analysis and provide clear explanations. <important> Please use the glab CLI to access data from GitLab. The glab CLI has already been authenticated. You can run the corresponding commands. If you are asked to summarize an MR or issue or asked to provide more information then please post back a note to the MR/Issue so that the user can see it. You don't need to commit or push up changes, those will be done automatically based on the file changes you make. </important> " - git checkout --branch $CI_WORKLOAD_REF origin/$CI_WORKLOAD_REF - echo "Checking for git changes and pushing if any exist" - | if ! git diff --quiet || ! git diff --cached --quiet || [ --not --zero "$(git ls-files --others --exclude-standard)" ]; then echo "Git changes detected, adding and pushing..." git add . if git diff --cached --quiet; then echo "No staged changes to commit" else echo "Committing changes to branch: $CI_WORKLOAD_REF" git commit --message "Codex changes" echo "Pushing changes up to $CI_WORKLOAD_REF" git push https://gitlab-ci-token:$GITLAB_TOKEN@$GITLAB_HOST/gl-demo-ultimate-dev-ai-epic-17570/test-java-project.git $CI_WORKLOAD_REF echo "Changes successfully pushed" fi else echo "No git changes detected, skipping push" fivariables: - ANTHROPIC_API_KEY - GITLAB_TOKEN_OPENCODE - GITLAB_HOST
+
+You can refer to the GitLab CLI agents docs for detailed instructions.
+
+---
+
+### Examples
+
+Here are some examples of how you can use OpenCode in GitLab.
+
+- Explain an issue Add this comment in a GitLab issue. @opencode explain this issue OpenCode will read the issue and reply with a clear explanation.
+- Fix an issue In a GitLab issue, say: @opencode fix this OpenCode will create a new branch, implement the changes, and open a merge request with the changes.
+- Review merge requests Leave the following comment on a GitLab merge request. @opencode review this merge request OpenCode will review the merge request and provide feedback.

homelab/raw/articles/opencode/docs/go.md

@@ -0,0 +1,168 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/go/
+scraped: 2026-04-28T21:02:05.387685+00:00
+content_hash: 01fbbedc
+---
+# Go
+
+Low cost subscription for open coding models.
+
+OpenCode Go is a low cost subscription — $5 for your first month, then $10/month — that gives you reliable access to popular open coding models.
+
+Go works like any other provider in OpenCode. You subscribe to OpenCode Go and get your API key. It’s completely optional and you don’t need to use it to use OpenCode.
+
+It is designed primarily for international users, with models hosted in the US, EU, and Singapore for stable global access.
+
+---
+
+## Background
+
+Open models have gotten really good. They now reach performance close to proprietary models for coding tasks. And because many providers can serve them competitively, they are usually far cheaper.
+
+However, getting reliable, low latency access to them can be difficult. Providers vary in quality and availability.
+
+To fix this, we did a couple of things:
+
+1. We tested a select group of open models and talked to their teams about how to best run them.
+2. We then worked with a few providers to make sure these were being served correctly.
+3. Finally, we benchmarked the combination of the model/provider and came up with a list that we feel good recommending.
+
+OpenCode Go gives you access to these models for $5 for your first month, then $10/month.
+
+---
+
+## How it works
+
+OpenCode Go works like any other provider in OpenCode.
+
+1. You sign in to OpenCode Zen, subscribe to Go, and copy your API key.
+2. You run the /connect command in the TUI, select OpenCode Go, and paste your API key.
+3. Run /models in the TUI to see the list of models available through Go.
+
+The current list of models includes:
+
+- GLM-5
+- GLM-5.1
+- Kimi K2.5
+- Kimi K2.6
+- MiMo-V2-Pro
+- MiMo-V2-Omni
+- MiMo-V2.5-Pro
+- MiMo-V2.5
+- MiniMax M2.5
+- MiniMax M2.7
+- Qwen3.5 Plus
+- Qwen3.6 Plus
+- DeepSeek V4 Pro
+- DeepSeek V4 Flash
+
+The list of models may change as we test and add new ones.
+
+---
+
+## Usage limits
+
+OpenCode Go includes the following limits:
+
+- 5 hour limit — $12 of usage
+- Weekly limit — $30 of usage
+- Monthly limit — $60 of usage
+
+Limits are defined in dollar value. This means your actual request count depends on the model you use. Cheaper models like Qwen3.5 Plus allow for more requests, while higher-cost models like GLM-5.1 allow for fewer.
+
+The table below provides an estimated request count based on typical Go usage patterns:
+
+| Model | requests per 5 hour | requests per week | requests per month |
+|---|---|---|---|
+| GLM-5.1 | 880 | 2,150 | 4,300 |
+| GLM-5 | 1,150 | 2,880 | 5,750 |
+| Kimi K2.5 | 1,850 | 4,630 | 9,250 |
+| Kimi K2.6 | 1,150 | 2,880 | 5,750 |
+| MiMo-V2-Pro | 1,290 | 3,225 | 6,450 |
+| MiMo-V2-Omni | 2,150 | 5,450 | 10,900 |
+| MiMo-V2.5-Pro | 1,290 | 3,225 | 6,450 |
+| MiMo-V2.5 (≤ 256K) | 2,150 | 5,450 | 10,900 |
+| MiniMax M2.7 | 3,400 | 8,500 | 17,000 |
+| MiniMax M2.5 | 6,300 | 15,900 | 31,800 |
+| Qwen3.6 Plus | 3,300 | 8,200 | 16,300 |
+| Qwen3.5 Plus | 10,200 | 25,200 | 50,500 |
+| DeepSeek V4 Pro | 3,450 | 8,550 | 17,150 |
+| DeepSeek V4 Flash | 31,650 | 79,050 | 158,150 |
+
+Estimates are based on observed average request patterns:
+
+- GLM-5/5.1 — 700 input, 52,000 cached, 150 output tokens per request
+- Kimi K2.5/K2.6 — 870 input, 55,000 cached, 200 output tokens per request
+- DeepSeek V4 Pro — 750 input, 82,000 cached, 290 output tokens per request
+- DeepSeek V4 Flash — 790 input, 68,000 cached, 280 output tokens per request
+- MiniMax M2.7/M2.5 — 300 input, 55,000 cached, 125 output tokens per request
+- MiMo-V2-Pro — 350 input, 41,000 cached, 250 output tokens per request
+- MiMo-V2-Omni — 1000 input, 60,000 cached, 140 output tokens per request
+- MiMo-V2.5-Pro — 350 input, 41,000 cached, 250 output tokens per request
+- MiMo-V2.5 — 1000 input, 60,000 cached, 140 output tokens per request
+- Qwen3.5 Plus — 410 input, 47,000 cached, 140 output tokens per request
+- Qwen3.6 Plus — 500 input, 57,000 cached, 190 output tokens per request
+
+You can track your current usage in the console.
+
+Usage limits may change as we learn from early usage and feedback.
+
+---
+
+### Usage beyond limits
+
+If you also have credits on your Zen balance, you can enable the Use balance option in the console. When enabled, Go will fall back to your Zen balance after you’ve reached your usage limits instead of blocking requests.
+
+---
+
+## Endpoints
+
+You can also access Go models through the following API endpoints.
+
+| Model | Model ID | Endpoint | AI SDK Package |
+|---|---|---|---|
+| GLM-5.1 | glm-5.1 | https://opencode.ai/zen/go/v1/chat/completions | @ai-sdk/openai-compatible |
+| GLM-5 | glm-5 | https://opencode.ai/zen/go/v1/chat/completions | @ai-sdk/openai-compatible |
+| Kimi K2.5 | kimi-k2.5 | https://opencode.ai/zen/go/v1/chat/completions | @ai-sdk/openai-compatible |
+| Kimi K2.6 | kimi-k2.6 | https://opencode.ai/zen/go/v1/chat/completions | @ai-sdk/openai-compatible |
+| DeepSeek V4 Pro | deepseek-v4-pro | https://opencode.ai/zen/go/v1/chat/completions | @ai-sdk/openai-compatible |
+| DeepSeek V4 Flash | deepseek-v4-flash | https://opencode.ai/zen/go/v1/chat/completions | @ai-sdk/openai-compatible |
+| MiMo-V2-Pro | mimo-v2-pro | https://opencode.ai/zen/go/v1/chat/completions | @ai-sdk/openai-compatible |
+| MiMo-V2-Omni | mimo-v2-omni | https://opencode.ai/zen/go/v1/chat/completions | @ai-sdk/openai-compatible |
+| MiMo-V2.5-Pro | mimo-v2.5-pro | https://opencode.ai/zen/go/v1/chat/completions | @ai-sdk/openai-compatible |
+| MiMo-V2.5 | mimo-v2.5 | https://opencode.ai/zen/go/v1/chat/completions | @ai-sdk/openai-compatible |
+| MiniMax M2.7 | minimax-m2.7 | https://opencode.ai/zen/go/v1/messages | @ai-sdk/anthropic |
+| MiniMax M2.5 | minimax-m2.5 | https://opencode.ai/zen/go/v1/messages | @ai-sdk/anthropic |
+| Qwen3.6 Plus | qwen3.6-plus | https://opencode.ai/zen/go/v1/chat/completions | @ai-sdk/alibaba |
+| Qwen3.5 Plus | qwen3.5-plus | https://opencode.ai/zen/go/v1/chat/completions | @ai-sdk/alibaba |
+
+The model id in your OpenCode config uses the format opencode-go/<model-id>. For example, for Kimi K2.6, you would use opencode-go/kimi-k2.6 in your config.
+
+---
+
+### Models
+
+You can fetch the full list of available models and their metadata from:
+
+```
+https://opencode.ai/zen/go/v1/models
+```
+
+---
+
+## Privacy
+
+The plan is designed primarily for international users, with models hosted in the US, EU, and Singapore for stable global access. Our providers follow a zero-retention policy and do not use your data for model training.
+
+---
+
+## Goals
+
+We created OpenCode Go to:
+
+1. Make AI coding accessible to more people with a low cost subscription.
+2. Provide reliable access to the best open coding models.
+3. Curate models that are tested and benchmarked for coding agent use.
+4. Have no lock-in by allowing you to use any other provider with OpenCode as well.

homelab/raw/articles/opencode/docs/ide.md

@@ -0,0 +1,55 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/ide/
+scraped: 2026-04-28T21:02:07.880123+00:00
+content_hash: 55751af4
+---
+# IDE
+
+The OpenCode extension for VS Code, Cursor, and other IDEs
+
+OpenCode integrates with VS Code, Cursor, or any IDE that supports a terminal. Just run opencode in the terminal to get started.
+
+---
+
+## Usage
+
+- Quick Launch: Use Cmd+Esc (Mac) or Ctrl+Esc (Windows/Linux) to open OpenCode in a split terminal view, or focus an existing terminal session if one is already running.
+- New Session: Use Cmd+Shift+Esc (Mac) or Ctrl+Shift+Esc (Windows/Linux) to start a new OpenCode terminal session, even if one is already open. You can also click the OpenCode button in the UI.
+- Context Awareness: Automatically share your current selection or tab with OpenCode.
+- File Reference Shortcuts: Use Cmd+Option+K (Mac) or Alt+Ctrl+K (Linux/Windows) to insert file references. For example, @File#L37-42.
+
+---
+
+## Installation
+
+To install OpenCode on VS Code and popular forks like Cursor, Windsurf, VSCodium:
+
+1. Open VS Code
+2. Open the integrated terminal
+3. Run opencode - the extension installs automatically
+
+If on the other hand you want to use your own IDE when you run /editor or /export from the TUI, you’ll need to set export EDITOR="code --wait". Learn more.
+
+---
+
+### Manual Install
+
+Search for OpenCode in the Extension Marketplace and click Install.
+
+---
+
+### Troubleshooting
+
+If the extension fails to install automatically:
+
+- Ensure you’re running opencode in the integrated terminal.
+- Confirm the CLI for your IDE is installed: For VS Code: code command For Cursor: cursor command For Windsurf: windsurf command For VSCodium: codium command If not, run Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux) and search for “Shell Command: Install ‘code’ command in PATH” (or the equivalent for your IDE)
+- For VS Code: code command
+- For Cursor: cursor command
+- For Windsurf: windsurf command
+- For VSCodium: codium command
+- If not, run Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux) and search for “Shell Command: Install ‘code’ command in PATH” (or the equivalent for your IDE)
+
+- Ensure VS Code has permission to install extensions

homelab/raw/articles/opencode/docs/index.md

@@ -0,0 +1,185 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/
+scraped: 2026-04-28T21:02:15.583643+00:00
+content_hash: d58b0fa2
+---
+# Intro
+
+Get started with OpenCode.
+
+OpenCode is an open source AI coding agent. It’s available as a terminal-based interface, desktop app, or IDE extension.
+
+Let’s get started.
+
+---
+
+#### Prerequisites
+
+To use OpenCode in your terminal, you’ll need:
+
+1. A modern terminal emulator like: WezTerm, cross-platform Alacritty, cross-platform Ghostty, Linux and macOS Kitty, Linux and macOS
+2. API keys for the LLM providers you want to use.
+
+---
+
+## Install
+
+The easiest way to install OpenCode is through the install script.
+
+```
+curl -fsSL https://opencode.ai/install | bash
+```
+
+You can also install it with the following commands:
+
+- Using Node.js npm Bun pnpm Yarn Terminal windownpm install -g opencode-ai
+- Using Homebrew on macOS and Linux Terminal windowbrew install anomalyco/tap/opencode We recommend using the OpenCode tap for the most up to date releases. The official brew install opencode formula is maintained by the Homebrew team and is updated less frequently.
+- Installing on Arch Linux Terminal windowsudo pacman -S opencode # Arch Linux (Stable)paru -S opencode-bin # Arch Linux (Latest from AUR)
+
+#### Windows
+
+- Using Chocolatey Terminal windowchoco install opencode
+- Using Scoop Terminal windowscoop install opencode
+- Using NPM Terminal windownpm install -g opencode-ai
+- Using Mise Terminal windowmise use -g github:anomalyco/opencode
+- Using Docker Terminal windowdocker run -it --rm ghcr.io/anomalyco/opencode
+
+Support for installing OpenCode on Windows using Bun is currently in progress.
+
+You can also grab the binary from the Releases.
+
+---
+
+## Configure
+
+With OpenCode you can use any LLM provider by configuring their API keys.
+
+If you are new to using LLM providers, we recommend using OpenCode Zen. It’s a curated list of models that have been tested and verified by the OpenCode team.
+
+1. Run the /connect command in the TUI, select opencode, and head to opencode.ai/auth. /connect
+2. Sign in, add your billing details, and copy your API key.
+3. Paste your API key. ┌ API key││└ enter
+
+Alternatively, you can select one of the other providers. Learn more.
+
+---
+
+## Initialize
+
+Now that you’ve configured a provider, you can navigate to a project that you want to work on.
+
+```
+cd /path/to/project
+```
+
+And run OpenCode.
+
+```
+opencode
+```
+
+Next, initialize OpenCode for the project by running the following command.
+
+```
+/init
+```
+
+This will get OpenCode to analyze your project and create an AGENTS.md file in the project root.
+
+This helps OpenCode understand the project structure and the coding patterns used.
+
+---
+
+## Usage
+
+You are now ready to use OpenCode to work on your project. Feel free to ask it anything!
+
+If you are new to using an AI coding agent, here are some examples that might help.
+
+---
+
+### Ask questions
+
+You can ask OpenCode to explain the codebase to you.
+
+```
+How is authentication handled in @packages/functions/src/api/index.ts
+```
+
+This is helpful if there’s a part of the codebase that you didn’t work on.
+
+---
+
+### Add features
+
+You can ask OpenCode to add new features to your project. Though we first recommend asking it to create a plan.
+
+1. Create a plan OpenCode has a Plan mode that disables its ability to make changes and instead suggest how it’ll implement the feature. Switch to it using the Tab key. You’ll see an indicator for this in the lower right corner. <TAB> Now let’s describe what we want it to do. When a user deletes a note, we'd like to flag it as deleted in the database.Then create a screen that shows all the recently deleted notes.From this screen, the user can undelete a note or permanently delete it. You want to give OpenCode enough details to understand what you want. It helps to talk to it like you are talking to a junior developer on your team.
+2. Iterate on the plan Once it gives you a plan, you can give it feedback or add more details. We'd like to design this new screen using a design I've used before.[Image #1] Take a look at this image and use it as a reference. OpenCode can scan any images you give it and add them to the prompt. You can do this by dragging and dropping an image into the terminal.
+3. Build the feature Once you feel comfortable with the plan, switch back to Build mode by hitting the Tab key again. <TAB> And asking it to make the changes. Sounds good! Go ahead and make the changes.
+
+---
+
+### Make changes
+
+For more straightforward changes, you can ask OpenCode to directly build it without having to review the plan first.
+
+```
+We need to add authentication to the /settings route. Take a look at how this ishandled in the /notes route in @packages/functions/src/notes.ts and implementthe same logic in @packages/functions/src/settings.ts
+```
+
+You want to make sure you provide a good amount of detail so OpenCode makes the right changes.
+
+---
+
+### Undo changes
+
+Let’s say you ask OpenCode to make some changes.
+
+```
+Can you refactor the function in @packages/functions/src/api/index.ts?
+```
+
+But you realize that it is not what you wanted. You can undo the changes using the /undo command.
+
+```
+/undo
+```
+
+OpenCode will now revert the changes you made and show your original message again.
+
+```
+Can you refactor the function in @packages/functions/src/api/index.ts?
+```
+
+From here you can tweak the prompt and ask OpenCode to try again.
+
+Or you can redo the changes using the /redo command.
+
+```
+/redo
+```
+
+---
+
+## Share
+
+The conversations that you have with OpenCode can be shared with your team.
+
+```
+/share
+```
+
+This will create a link to the current conversation and copy it to your clipboard.
+
+Here’s an example conversation with OpenCode.
+
+---
+
+## Customize
+
+And that’s it! You are now a pro at using OpenCode.
+
+To make it your own, we recommend picking a theme, customizing the keybinds, configuring code formatters, creating custom commands, or playing around with the OpenCode config.

homelab/raw/articles/opencode/docs/keybinds.md

@@ -0,0 +1,88 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/keybinds/
+scraped: 2026-04-28T21:02:11.014139+00:00
+content_hash: 4638350d
+---
+# Keybinds
+
+Customize your keybinds.
+
+OpenCode has a list of keybinds that you can customize through tui.json.
+
+```
+{  "$schema": "https://opencode.ai/tui.json",  "keybinds": {    "leader": "ctrl+x",    "app_exit": "ctrl+c,ctrl+d,<leader>q",    "editor_open": "<leader>e",    "theme_list": "<leader>t",    "sidebar_toggle": "<leader>b",    "scrollbar_toggle": "none",    "username_toggle": "none",    "status_view": "<leader>s",    "tool_details": "none",    "session_export": "<leader>x",    "session_new": "<leader>n",    "session_list": "<leader>l",    "session_timeline": "<leader>g",    "session_fork": "none",    "session_rename": "none",    "session_share": "none",    "session_unshare": "none",    "session_interrupt": "escape",    "session_compact": "<leader>c",    "session_child_first": "<leader>down",    "session_child_cycle": "right",    "session_child_cycle_reverse": "left",    "session_parent": "up",    "messages_page_up": "pageup,ctrl+alt+b",    "messages_page_down": "pagedown,ctrl+alt+f",    "messages_line_up": "ctrl+alt+y",    "messages_line_down": "ctrl+alt+e",    "messages_half_page_up": "ctrl+alt+u",    "messages_half_page_down": "ctrl+alt+d",    "messages_first": "ctrl+g,home",    "messages_last": "ctrl+alt+g,end",    "messages_next": "none",    "messages_previous": "none",    "messages_copy": "<leader>y",    "messages_undo": "<leader>u",    "messages_redo": "<leader>r",    "messages_last_user": "none",    "messages_toggle_conceal": "<leader>h",    "model_list": "<leader>m",    "model_cycle_recent": "f2",    "model_cycle_recent_reverse": "shift+f2",    "model_cycle_favorite": "none",    "model_cycle_favorite_reverse": "none",    "variant_cycle": "ctrl+t",    "variant_list": "none",    "command_list": "ctrl+p",    "agent_list": "<leader>a",    "agent_cycle": "tab",    "agent_cycle_reverse": "shift+tab",    "input_clear": "ctrl+c",    "input_paste": "ctrl+v",    "input_submit": "return",    "input_newline": "shift+return,ctrl+return,alt+return,ctrl+j",    "input_move_left": "left,ctrl+b",    "input_move_right": "right,ctrl+f",    "input_move_up": "up",    "input_move_down": "down",    "input_select_left": "shift+left",    "input_select_right": "shift+right",    "input_select_up": "shift+up",    "input_select_down": "shift+down",    "input_line_home": "ctrl+a",    "input_line_end": "ctrl+e",    "input_select_line_home": "ctrl+shift+a",    "input_select_line_end": "ctrl+shift+e",    "input_visual_line_home": "alt+a",    "input_visual_line_end": "alt+e",    "input_select_visual_line_home": "alt+shift+a",    "input_select_visual_line_end": "alt+shift+e",    "input_buffer_home": "home",    "input_buffer_end": "end",    "input_select_buffer_home": "shift+home",    "input_select_buffer_end": "shift+end",    "input_delete_line": "ctrl+shift+d",    "input_delete_to_line_end": "ctrl+k",    "input_delete_to_line_start": "ctrl+u",    "input_backspace": "backspace,shift+backspace",    "input_delete": "ctrl+d,delete,shift+delete",    "input_undo": "ctrl+-,super+z",    "input_redo": "ctrl+.,super+shift+z",    "input_word_forward": "alt+f,alt+right,ctrl+right",    "input_word_backward": "alt+b,alt+left,ctrl+left",    "input_select_word_forward": "alt+shift+f,alt+shift+right",    "input_select_word_backward": "alt+shift+b,alt+shift+left",    "input_delete_word_forward": "alt+d,alt+delete,ctrl+delete",    "input_delete_word_backward": "ctrl+w,ctrl+backspace,alt+backspace",    "history_previous": "up",    "history_next": "down",    "terminal_suspend": "ctrl+z",    "terminal_title_toggle": "none",    "tips_toggle": "<leader>h",    "display_thinking": "none"  }}
+```
+
+---
+
+## Leader key
+
+OpenCode uses a leader key for most keybinds. This avoids conflicts in your terminal.
+
+By default, ctrl+x is the leader key and most actions require you to first press the leader key and then the shortcut. For example, to start a new session you first press ctrl+x and then press n.
+
+You don’t need to use a leader key for your keybinds but we recommend doing so.
+
+Some navigation keybinds intentionally do not use the leader key by default. For subagent sessions, the defaults are session_child_first = \<leader>down, session_child_cycle = right, session_child_cycle_reverse = left, and session_parent = up.
+
+---
+
+## Disable keybind
+
+You can disable a keybind by adding the key to tui.json with a value of “none”.
+
+```
+{  "$schema": "https://opencode.ai/tui.json",  "keybinds": {    "session_compact": "none"  }}
+```
+
+---
+
+## Desktop prompt shortcuts
+
+The OpenCode desktop app prompt input supports common Readline/Emacs-style shortcuts for editing text. These are built-in and currently not configurable via opencode.json.
+
+| Shortcut | Action |
+|---|---|
+| ctrl+a | Move to start of current line |
+| ctrl+e | Move to end of current line |
+| ctrl+b | Move cursor back one character |
+| ctrl+f | Move cursor forward one character |
+| alt+b | Move cursor back one word |
+| alt+f | Move cursor forward one word |
+| ctrl+d | Delete character under cursor |
+| ctrl+k | Kill to end of line |
+| ctrl+u | Kill to start of line |
+| ctrl+w | Kill previous word |
+| alt+d | Kill next word |
+| ctrl+t | Transpose characters |
+| ctrl+g | Cancel popovers / abort running response |
+
+---
+
+## Shift+Enter
+
+Some terminals don’t send modifier keys with Enter by default. You may need to configure your terminal to send Shift+Enter as an escape sequence.
+
+### Windows Terminal
+
+Open your settings.json at:
+
+```
+%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json
+```
+
+Add this to the root-level actions array:
+
+```
+"actions": [  {    "command": {      "action": "sendInput",      "input": "\u001b[13;2u"    },    "id": "User.sendInput.ShiftEnterCustom"  }]
+```
+
+Add this to the root-level keybindings array:
+
+```
+"keybindings": [  {    "keys": "shift+enter",    "id": "User.sendInput.ShiftEnterCustom"  }]
+```
+
+Save the file and restart Windows Terminal or open a new tab.

homelab/raw/articles/opencode/docs/lsp.md

@@ -0,0 +1,147 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/lsp/
+scraped: 2026-04-28T21:02:09.047665+00:00
+content_hash: bc22b327
+---
+# LSP Servers
+
+OpenCode integrates with your LSP servers.
+
+OpenCode integrates with your Language Server Protocol (LSP) to help the LLM interact with your codebase. It uses diagnostics to provide feedback to the LLM.
+
+---
+
+## Built-in
+
+OpenCode comes with several built-in LSP servers for popular languages:
+
+| LSP Server | Extensions | Requirements |
+|---|---|---|
+| astro | .astro | Auto-installs for Astro projects |
+| bash | .sh, .bash, .zsh, .ksh | Auto-installs bash-language-server |
+| clangd | .c, .cpp, .cc, .cxx, .c++, .h, .hpp, .hh, .hxx, .h++ | Auto-installs for C/C++ projects |
+| csharp | .cs, .csx | .NET SDK installed |
+| clojure-lsp | .clj, .cljs, .cljc, .edn | clojure-lsp command available |
+| dart | .dart | dart command available |
+| deno | .ts, .tsx, .js, .jsx, .mjs | deno command available (auto-detects deno.json/deno.jsonc) |
+| elixir-ls | .ex, .exs | elixir command available |
+| eslint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue | eslint dependency in project |
+| fsharp | .fs, .fsi, .fsx, .fsscript | .NET SDK installed |
+| gleam | .gleam | gleam command available |
+| gopls | .go | go command available |
+| hls | .hs, .lhs | haskell-language-server-wrapper command available |
+| jdtls | .java | Java SDK (version 21+) installed |
+| julials | .jl | julia and LanguageServer.jl installed |
+| kotlin-ls | .kt, .kts | Auto-installs for Kotlin projects |
+| lua-ls | .lua | Auto-installs for Lua projects |
+| nixd | .nix | nixd command available |
+| ocaml-lsp | .ml, .mli | ocamllsp command available |
+| oxlint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue, .astro, .svelte | oxlint dependency in project |
+| php intelephense | .php | Auto-installs for PHP projects |
+| prisma | .prisma | prisma command available |
+| pyright | .py, .pyi | pyright dependency installed |
+| razor | .razor, .cshtml | .NET SDK and VS Code C# extension installed |
+| ruby-lsp (rubocop) | .rb, .rake, .gemspec, .ru | ruby and gem commands available |
+| rust | .rs | rust-analyzer command available |
+| sourcekit-lsp | .swift, .objc, .objcpp | swift installed (xcode on macOS) |
+| svelte | .svelte | Auto-installs for Svelte projects |
+| terraform | .tf, .tfvars | Auto-installs from GitHub releases |
+| tinymist | .typ, .typc | Auto-installs from GitHub releases |
+| typescript | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts | typescript dependency in project |
+| vue | .vue | Auto-installs for Vue projects |
+| yaml-ls | .yaml, .yml | Auto-installs Red Hat yaml-language-server |
+| zls | .zig, .zon | zig command available |
+
+LSP servers are automatically enabled when one of the above file extensions are detected and the requirements are met.
+
+---
+
+## How It Works
+
+When opencode opens a file, it:
+
+1. Checks the file extension against all enabled LSP servers.
+2. Starts the appropriate LSP server if not already running.
+
+---
+
+## Configure
+
+You can customize LSP servers through the lsp section in your opencode config.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "lsp": {}}
+```
+
+Each LSP server supports the following:
+
+| Property | Type | Description |
+|---|---|---|
+| disabled | boolean | Set this to true to disable the LSP server |
+| command | string[] | The command to start the LSP server |
+| extensions | string[] | File extensions this LSP server should handle |
+| env | object | Environment variables to set when starting server |
+| initialization | object | Initialization options to send to the LSP server |
+
+Let’s look at some examples.
+
+---
+
+### Environment variables
+
+Use the env property to set environment variables when starting the LSP server:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "lsp": {    "rust": {      "env": {        "RUST_LOG": "debug"      }    }  }}
+```
+
+---
+
+### Initialization options
+
+Use the initialization property to pass initialization options to the LSP server. These are server-specific settings sent during the LSP initialize request:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "lsp": {    "typescript": {      "initialization": {        "preferences": {          "importModuleSpecifierPreference": "relative"        }      }    }  }}
+```
+
+---
+
+### Disabling LSP servers
+
+To disable all LSP servers globally, set lsp to false:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "lsp": false}
+```
+
+To disable a specific LSP server, set disabled to true:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "lsp": {    "typescript": {      "disabled": true    }  }}
+```
+
+---
+
+### Custom LSP servers
+
+You can add custom LSP servers by specifying the command and file extensions:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "lsp": {    "custom-lsp": {      "command": ["custom-lsp-server", "--stdio"],      "extensions": [".custom"]    }  }}
+```
+
+---
+
+## Additional Information
+
+### PHP Intelephense
+
+PHP Intelephense offers premium features through a license key. You can provide a license key by placing (only) the key in a text file at:
+
+- On macOS/Linux: $HOME/intelephense/license.txt
+- On Windows: %USERPROFILE%/intelephense/license.txt
+
+The file should contain only the license key with no additional content.

homelab/raw/articles/opencode/docs/mcp-servers.md

@@ -0,0 +1,328 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/mcp-servers/
+scraped: 2026-04-28T21:02:09.938559+00:00
+content_hash: b7c008c9
+---
+# MCP servers
+
+Add local and remote MCP tools.
+
+You can add external tools to OpenCode using the Model Context Protocol, or MCP. OpenCode supports both local and remote servers.
+
+Once added, MCP tools are automatically available to the LLM alongside built-in tools.
+
+---
+
+#### Caveats
+
+When you use an MCP server, it adds to the context. This can quickly add up if you have a lot of tools. So we recommend being careful with which MCP servers you use.
+
+Certain MCP servers, like the GitHub MCP server, tend to add a lot of tokens and can easily exceed the context limit.
+
+---
+
+## Enable
+
+You can define MCP servers in your OpenCode Config under mcp. Add each MCP with a unique name. You can refer to that MCP by name when prompting the LLM.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "name-of-mcp-server": {      // ...      "enabled": true,    },    "name-of-other-mcp-server": {      // ...    },  },}
+```
+
+You can also disable a server by setting enabled to false. This is useful if you want to temporarily disable a server without removing it from your config.
+
+---
+
+### Overriding remote defaults
+
+Organizations can provide default MCP servers via their .well-known/opencode endpoint. These servers may be disabled by default, allowing users to opt-in to the ones they need.
+
+To enable a specific server from your organization’s remote config, add it to your local config with enabled: true:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "jira": {      "type": "remote",      "url": "https://jira.example.com/mcp",      "enabled": true    }  }}
+```
+
+Your local config values override the remote defaults. See config precedence for more details.
+
+---
+
+## Local
+
+Add local MCP servers using type to "local" within the MCP object.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "my-local-mcp-server": {      "type": "local",      // Or ["bun", "x", "my-mcp-command"]      "command": ["npx", "-y", "my-mcp-command"],      "enabled": true,      "environment": {        "MY_ENV_VAR": "my_env_var_value",      },    },  },}
+```
+
+The command is how the local MCP server is started. You can also pass in a list of environment variables as well.
+
+For example, here’s how you can add the test @modelcontextprotocol/server-everything MCP server.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "mcp_everything": {      "type": "local",      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],    },  },}
+```
+
+And to use it I can add use the mcp_everything tool to my prompts.
+
+```
+use the mcp_everything tool to add the number 3 and 4
+```
+
+---
+
+#### Options
+
+Here are all the options for configuring a local MCP server.
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| type | String | Y | Type of MCP server connection, must be "local". |
+| command | Array | Y | Command and arguments to run the MCP server. |
+| environment | Object |  | Environment variables to set when running the server. |
+| enabled | Boolean |  | Enable or disable the MCP server on startup. |
+| timeout | Number |  | Timeout in ms for fetching tools from the MCP server. Defaults to 5000 (5 seconds). |
+
+---
+
+## Remote
+
+Add remote MCP servers by setting type to "remote".
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "my-remote-mcp": {      "type": "remote",      "url": "https://my-mcp-server.com",      "enabled": true,      "headers": {        "Authorization": "Bearer MY_API_KEY"      }    }  }}
+```
+
+The url is the URL of the remote MCP server and with the headers option you can pass in a list of headers.
+
+---
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| type | String | Y | Type of MCP server connection, must be "remote". |
+| url | String | Y | URL of the remote MCP server. |
+| enabled | Boolean |  | Enable or disable the MCP server on startup. |
+| headers | Object |  | Headers to send with the request. |
+| oauth | Object |  | OAuth authentication configuration. See OAuth section below. |
+| timeout | Number |  | Timeout in ms for fetching tools from the MCP server. Defaults to 5000 (5 seconds). |
+
+---
+
+## OAuth
+
+OpenCode automatically handles OAuth authentication for remote MCP servers. When a server requires authentication, OpenCode will:
+
+1. Detect the 401 response and initiate the OAuth flow
+2. Use Dynamic Client Registration (RFC 7591) if supported by the server
+3. Store tokens securely for future requests
+
+---
+
+### Automatic
+
+For most OAuth-enabled MCP servers, no special configuration is needed. Just configure the remote server:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "my-oauth-server": {      "type": "remote",      "url": "https://mcp.example.com/mcp"    }  }}
+```
+
+If the server requires authentication, OpenCode will prompt you to authenticate when you first try to use it. If not, you can manually trigger the flow with opencode mcp auth <server-name>.
+
+---
+
+### Pre-registered
+
+If you have client credentials from the MCP server provider, you can configure them:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "my-oauth-server": {      "type": "remote",      "url": "https://mcp.example.com/mcp",      "oauth": {        "clientId": "{env:MY_MCP_CLIENT_ID}",        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",        "scope": "tools:read tools:execute"      }    }  }}
+```
+
+---
+
+### Authenticating
+
+You can manually trigger authentication or manage credentials.
+
+Authenticate with a specific MCP server:
+
+```
+opencode mcp auth my-oauth-server
+```
+
+List all MCP servers and their auth status:
+
+```
+opencode mcp list
+```
+
+Remove stored credentials:
+
+```
+opencode mcp logout my-oauth-server
+```
+
+The mcp auth command will open your browser for authorization. After you authorize, OpenCode will store the tokens securely in ~/.local/share/opencode/mcp-auth.json.
+
+---
+
+#### Disabling OAuth
+
+If you want to disable automatic OAuth for a server (e.g., for servers that use API keys instead), set oauth to false:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "my-api-key-server": {      "type": "remote",      "url": "https://mcp.example.com/mcp",      "oauth": false,      "headers": {        "Authorization": "Bearer {env:MY_API_KEY}"      }    }  }}
+```
+
+---
+
+#### OAuth Options
+
+| Option | Type | Description |
+|---|---|---|
+| oauth | Object | false | OAuth config object, or false to disable OAuth auto-detection. |
+| clientId | String | OAuth client ID. If not provided, dynamic client registration will be attempted. |
+| clientSecret | String | OAuth client secret, if required by the authorization server. |
+| scope | String | OAuth scopes to request during authorization. |
+
+#### Debugging
+
+If a remote MCP server is failing to authenticate, you can diagnose issues with:
+
+```
+# View auth status for all OAuth-capable serversopencode mcp auth list
+# Debug connection and OAuth flow for a specific serveropencode mcp debug my-oauth-server
+```
+
+The mcp debug command shows the current auth status, tests HTTP connectivity, and attempts the OAuth discovery flow.
+
+---
+
+## Manage
+
+Your MCPs are available as tools in OpenCode, alongside built-in tools. So you can manage them through the OpenCode config like any other tool.
+
+---
+
+### Global
+
+This means that you can enable or disable them globally.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "my-mcp-foo": {      "type": "local",      "command": ["bun", "x", "my-mcp-command-foo"]    },    "my-mcp-bar": {      "type": "local",      "command": ["bun", "x", "my-mcp-command-bar"]    }  },  "tools": {    "my-mcp-foo": false  }}
+```
+
+We can also use a glob pattern to disable all matching MCPs.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "my-mcp-foo": {      "type": "local",      "command": ["bun", "x", "my-mcp-command-foo"]    },    "my-mcp-bar": {      "type": "local",      "command": ["bun", "x", "my-mcp-command-bar"]    }  },  "tools": {    "my-mcp*": false  }}
+```
+
+Here we are using the glob pattern my-mcp* to disable all MCPs.
+
+---
+
+### Per agent
+
+If you have a large number of MCP servers you may want to only enable them per agent and disable them globally. To do this:
+
+1. Disable it as a tool globally.
+2. In your agent config, enable the MCP server as a tool.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "my-mcp": {      "type": "local",      "command": ["bun", "x", "my-mcp-command"],      "enabled": true    }  },  "tools": {    "my-mcp*": false  },  "agent": {    "my-agent": {      "tools": {        "my-mcp*": true      }    }  }}
+```
+
+---
+
+#### Glob patterns
+
+The glob pattern uses simple regex globbing patterns:
+
+- * matches zero or more of any character (e.g., "my-mcp*" matches my-mcp_search, my-mcp_list, etc.)
+- ? matches exactly one character
+- All other characters match literally
+
+---
+
+## Examples
+
+Below are examples of some common MCP servers. You can submit a PR if you want to document other servers.
+
+---
+
+### Sentry
+
+Add the Sentry MCP server to interact with your Sentry projects and issues.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "sentry": {      "type": "remote",      "url": "https://mcp.sentry.dev/mcp",      "oauth": {}    }  }}
+```
+
+After adding the configuration, authenticate with Sentry:
+
+```
+opencode mcp auth sentry
+```
+
+This will open a browser window to complete the OAuth flow and connect OpenCode to your Sentry account.
+
+Once authenticated, you can use Sentry tools in your prompts to query issues, projects, and error data.
+
+```
+Show me the latest unresolved issues in my project. use sentry
+```
+
+---
+
+### Context7
+
+Add the Context7 MCP server to search through docs.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "context7": {      "type": "remote",      "url": "https://mcp.context7.com/mcp"    }  }}
+```
+
+If you have signed up for a free account, you can use your API key and get higher rate-limits.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "context7": {      "type": "remote",      "url": "https://mcp.context7.com/mcp",      "headers": {        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"      }    }  }}
+```
+
+Here we are assuming that you have the CONTEXT7_API_KEY environment variable set.
+
+Add use context7 to your prompts to use Context7 MCP server.
+
+```
+Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7
+```
+
+Alternatively, you can add something like this to your AGENTS.md.
+
+```
+When you need to search docs, use `context7` tools.
+```
+
+---
+
+### Grep by Vercel
+
+Add the Grep by Vercel MCP server to search through code snippets on GitHub.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "gh_grep": {      "type": "remote",      "url": "https://mcp.grep.app"    }  }}
+```
+
+Since we named our MCP server gh_grep, you can add use the gh_grep tool to your prompts to get the agent to use it.
+
+```
+What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool
+```
+
+Alternatively, you can add something like this to your AGENTS.md.
+
+```
+If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
+```

homelab/raw/articles/opencode/docs/models.md

@@ -0,0 +1,135 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/models/
+scraped: 2026-04-28T21:02:05.883345+00:00
+content_hash: 694788f0
+---
+# Models
+
+Configuring an LLM provider and model.
+
+OpenCode uses the AI SDK and Models.dev to support 75+ LLM providers and it supports running local models.
+
+---
+
+## Providers
+
+Most popular providers are preloaded by default. If you’ve added the credentials for a provider through the /connect command, they’ll be available when you start OpenCode.
+
+Learn more about providers.
+
+---
+
+## Select a model
+
+Once you’ve configured your provider you can select the model you want by typing in:
+
+```
+/models
+```
+
+---
+
+## Recommended models
+
+There are a lot of models out there, with new models coming out every week.
+
+However, there are only a few of them that are good at both generating code and tool calling.
+
+Here are several models that work well with OpenCode, in no particular order. (This is not an exhaustive list nor is it necessarily up to date):
+
+- GPT 5.2
+- GPT 5.1 Codex
+- Claude Opus 4.5
+- Claude Sonnet 4.5
+- Minimax M2.1
+- Gemini 3 Pro
+
+---
+
+## Set a default
+
+To set one of these as the default model, you can set the model key in your OpenCode config.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "model": "lmstudio/google/gemma-3n-e4b"}
+```
+
+Here the full ID is provider_id/model_id. For example, if you’re using OpenCode Zen, you would use opencode/gpt-5.1-codex for GPT 5.1 Codex.
+
+If you’ve configured a custom provider, the provider_id is key from the provider part of your config, and the model_id is the key from provider.models.
+
+---
+
+## Configure models
+
+You can globally configure a model’s options through the config.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "openai": {      "models": {        "gpt-5": {          "options": {            "reasoningEffort": "high",            "textVerbosity": "low",            "reasoningSummary": "auto",            "include": ["reasoning.encrypted_content"],          },        },      },    },    "anthropic": {      "models": {        "claude-sonnet-4-5-20250929": {          "options": {            "thinking": {              "type": "enabled",              "budgetTokens": 16000,            },          },        },      },    },  },}
+```
+
+Here we’re configuring global settings for two built-in models: gpt-5 when accessed via the openai provider, and claude-sonnet-4-20250514 when accessed via the anthropic provider. The built-in provider and model names can be found on Models.dev.
+
+You can also configure these options for any agents that you are using. The agent config overrides any global options here. Learn more.
+
+You can also define custom variants that extend built-in ones. Variants let you configure different settings for the same model without creating duplicate entries:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "opencode": {      "models": {        "gpt-5": {          "variants": {            "high": {              "reasoningEffort": "high",              "textVerbosity": "low",              "reasoningSummary": "auto",            },            "low": {              "reasoningEffort": "low",              "textVerbosity": "low",              "reasoningSummary": "auto",            },          },        },      },    },  },}
+```
+
+---
+
+## Variants
+
+Many models support multiple variants with different configurations. OpenCode ships with built-in default variants for popular providers.
+
+### Built-in variants
+
+OpenCode ships with default variants for many providers:
+
+Anthropic:
+
+- high - High thinking budget (default)
+- max - Maximum thinking budget
+
+OpenAI:
+
+Varies by model but roughly:
+
+- none - No reasoning
+- minimal - Minimal reasoning effort
+- low - Low reasoning effort
+- medium - Medium reasoning effort
+- high - High reasoning effort
+- xhigh - Extra high reasoning effort
+
+Google:
+
+- low - Lower effort/token budget
+- high - Higher effort/token budget
+
+### Custom variants
+
+You can override existing variants or add your own:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "openai": {      "models": {        "gpt-5": {          "variants": {            "thinking": {              "reasoningEffort": "high",              "textVerbosity": "low",            },            "fast": {              "disabled": true,            },          },        },      },    },  },}
+```
+
+### Cycle variants
+
+Use the keybind variant_cycle to quickly switch between variants. Learn more.
+
+---
+
+## Loading models
+
+When OpenCode starts up, it checks for models in the following priority order:
+
+1. The --model or -m command line flag. The format is the same as in the config file: provider_id/model_id.
+2. The model list in the OpenCode config. opencode.json{ "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4-20250514"} The format here is provider/model.
+3. The last used model.
+4. The first model using an internal priority.

homelab/raw/articles/opencode/docs/network.md

@@ -0,0 +1,50 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/network/
+scraped: 2026-04-28T21:02:06.800678+00:00
+content_hash: da20ad5d
+---
+# Network
+
+Configure proxies and custom certificates.
+
+OpenCode supports standard proxy environment variables and custom certificates for enterprise network environments.
+
+---
+
+## Proxy
+
+OpenCode respects standard proxy environment variables.
+
+```
+# HTTPS proxy (recommended)export HTTPS_PROXY=https://proxy.example.com:8080
+# HTTP proxy (if HTTPS not available)export HTTP_PROXY=http://proxy.example.com:8080
+# Bypass proxy for local server (required)export NO_PROXY=localhost,127.0.0.1
+```
+
+You can configure the server’s port and hostname using CLI flags.
+
+---
+
+### Authenticate
+
+If your proxy requires basic authentication, include credentials in the URL.
+
+```
+export HTTPS_PROXY=http://username:password@proxy.example.com:8080
+```
+
+For proxies requiring advanced authentication like NTLM or Kerberos, consider using an LLM Gateway that supports your authentication method.
+
+---
+
+## Custom certificates
+
+If your enterprise uses custom CAs for HTTPS connections, configure OpenCode to trust them.
+
+```
+export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
+```
+
+This works for both proxy connections and direct API access.

homelab/raw/articles/opencode/docs/permissions.md

@@ -0,0 +1,151 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/permissions/
+scraped: 2026-04-28T21:02:05.634890+00:00
+content_hash: 1f09c7d7
+---
+# Permissions
+
+Control which actions require approval to run.
+
+OpenCode uses the permission config to decide whether a given action should run automatically, prompt you, or be blocked.
+
+As of v1.1.1, the legacy tools boolean config is deprecated and has been merged into permission. The old tools config is still supported for backwards compatibility.
+
+---
+
+## Actions
+
+Each permission rule resolves to one of:
+
+- "allow" — run without approval
+- "ask" — prompt for approval
+- "deny" — block the action
+
+---
+
+## Configuration
+
+You can set permissions globally (with *), and override specific tools.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "*": "ask",    "bash": "allow",    "edit": "deny"  }}
+```
+
+You can also set all permissions at once:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": "allow"}
+```
+
+---
+
+## Granular Rules (Object Syntax)
+
+For most permissions, you can use an object to apply different actions based on the tool input.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "bash": {      "*": "ask",      "git *": "allow",      "npm *": "allow",      "rm *": "deny",      "grep *": "allow"    },    "edit": {      "*": "deny",      "packages/web/src/content/docs/*.mdx": "allow"    }  }}
+```
+
+Rules are evaluated by pattern match, with the last matching rule winning. A common pattern is to put the catch-all "*" rule first, and more specific rules after it.
+
+### Wildcards
+
+Permission patterns use simple wildcard matching:
+
+- * matches zero or more of any character
+- ? matches exactly one character
+- All other characters match literally
+
+### Home Directory Expansion
+
+You can use ~ or $HOME at the start of a pattern to reference your home directory. This is particularly useful for external_directory rules.
+
+- ~/projects/* -> /Users/username/projects/*
+- $HOME/projects/* -> /Users/username/projects/*
+- ~ -> /Users/username
+
+### External Directories
+
+Use external_directory to allow tool calls that touch paths outside the working directory where OpenCode was started. This applies to any tool that takes a path as input (for example read, edit, glob, grep, and many bash commands).
+
+Home expansion (like ~/...) only affects how a pattern is written. It does not make an external path part of the current workspace, so paths outside the working directory must still be allowed via external_directory.
+
+For example, this allows access to everything under ~/projects/personal/:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "external_directory": {      "~/projects/personal/**": "allow"    }  }}
+```
+
+Any directory allowed here inherits the same defaults as the current workspace. Since read defaults to allow, reads are also allowed for entries under external_directory unless overridden. Add explicit rules when a tool should be restricted in these paths, such as blocking edits while keeping reads:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "external_directory": {      "~/projects/personal/**": "allow"    },    "edit": {      "~/projects/personal/**": "deny"    }  }}
+```
+
+Keep the list focused on trusted paths, and layer extra allow or deny rules as needed for other tools (for example bash).
+
+---
+
+## Available Permissions
+
+OpenCode permissions are keyed by tool name, plus a couple of safety guards:
+
+- read — reading a file (matches the file path)
+- edit — all file modifications (covers edit, write, patch)
+- glob — file globbing (matches the glob pattern)
+- grep — content search (matches the regex pattern)
+- bash — running shell commands (matches parsed commands like git status --porcelain)
+- task — launching subagents (matches the subagent type)
+- skill — loading a skill (matches the skill name)
+- lsp — running LSP queries (currently non-granular)
+- question — asking the user questions during execution
+- webfetch — fetching a URL (matches the URL)
+- websearch, codesearch — web/code search (matches the query)
+- external_directory — triggered when a tool touches paths outside the project working directory
+- doom_loop — triggered when the same tool call repeats 3 times with identical input
+
+---
+
+## Defaults
+
+If you don’t specify anything, OpenCode starts from permissive defaults:
+
+- Most permissions default to "allow".
+- doom_loop and external_directory default to "ask".
+- read is "allow", but .env files are denied by default:
+
+```
+{  "permission": {    "read": {      "*": "allow",      "*.env": "deny",      "*.env.*": "deny",      "*.env.example": "allow"    }  }}
+```
+
+---
+
+## What “Ask” Does
+
+When OpenCode prompts for approval, the UI offers three outcomes:
+
+- once — approve just this request
+- always — approve future requests matching the suggested patterns (for the rest of the current OpenCode session)
+- reject — deny the request
+
+The set of patterns that always would approve is provided by the tool (for example, bash approvals typically whitelist a safe command prefix like git status*).
+
+---
+
+## Agents
+
+You can override permissions per agent. Agent permissions are merged with the global config, and agent rules take precedence. Learn more about agent permissions.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "bash": {      "*": "ask",      "git *": "allow",      "git commit *": "deny",      "git push *": "deny",      "grep *": "allow"    }  },  "agent": {    "build": {      "permission": {        "bash": {          "*": "ask",          "git *": "allow",          "git commit *": "ask",          "git push *": "deny",          "grep *": "allow"        }      }    }  }}
+```
+
+You can also configure agent permissions in Markdown:
+
+```
+---description: Code review without editsmode: subagentpermission:  edit: deny  bash: ask  webfetch: deny---
+Only analyze code and suggest changes.
+```

homelab/raw/articles/opencode/docs/plugins.md

@@ -0,0 +1,281 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/plugins/
+scraped: 2026-04-28T21:02:07.734614+00:00
+content_hash: abb83ecb
+---
+# Plugins
+
+Write your own plugins to extend OpenCode.
+
+Plugins allow you to extend OpenCode by hooking into various events and customizing behavior. You can create plugins to add new features, integrate with external services, or modify OpenCode’s default behavior.
+
+For examples, check out the plugins created by the community.
+
+---
+
+## Use a plugin
+
+There are two ways to load plugins.
+
+---
+
+### From local files
+
+Place JavaScript or TypeScript files in the plugin directory.
+
+- .opencode/plugins/ - Project-level plugins
+- ~/.config/opencode/plugins/ - Global plugins
+
+Files in these directories are automatically loaded at startup.
+
+---
+
+### From npm
+
+Specify npm packages in your config file.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]}
+```
+
+Both regular and scoped npm packages are supported.
+
+Browse available plugins in the ecosystem.
+
+---
+
+### How plugins are installed
+
+npm plugins are installed automatically using Bun at startup. Packages and their dependencies are cached in ~/.cache/opencode/node_modules/.
+
+Local plugins are loaded directly from the plugin directory. To use external packages, you must create a package.json within your config directory (see Dependencies), or publish the plugin to npm and add it to your config.
+
+---
+
+### Load order
+
+Plugins are loaded from all sources and all hooks run in sequence. The load order is:
+
+1. Global config (~/.config/opencode/opencode.json)
+2. Project config (opencode.json)
+3. Global plugin directory (~/.config/opencode/plugins/)
+4. Project plugin directory (.opencode/plugins/)
+
+Duplicate npm packages with the same name and version are loaded once. However, a local plugin and an npm plugin with similar names are both loaded separately.
+
+---
+
+## Create a plugin
+
+A plugin is a JavaScript/TypeScript module that exports one or more plugin functions. Each function receives a context object and returns a hooks object.
+
+---
+
+### Dependencies
+
+Local plugins and custom tools can use external npm packages. Add a package.json to your config directory with the dependencies you need.
+
+```
+{  "dependencies": {    "shescape": "^2.1.0"  }}
+```
+
+OpenCode runs bun install at startup to install these. Your plugins and tools can then import them.
+
+```
+import { escape } from "shescape"
+export const MyPlugin = async (ctx) => {  return {    "tool.execute.before": async (input, output) => {      if (input.tool === "bash") {        output.args.command = escape(output.args.command)      }    },  }}
+```
+
+---
+
+### Basic structure
+
+```
+export const MyPlugin = async ({ project, client, $, directory, worktree }) => {  console.log("Plugin initialized!")
+  return {    // Hook implementations go here  }}
+```
+
+The plugin function receives:
+
+- project: The current project information.
+- directory: The current working directory.
+- worktree: The git worktree path.
+- client: An opencode SDK client for interacting with the AI.
+- $: Bun’s shell API for executing commands.
+
+---
+
+### TypeScript support
+
+For TypeScript plugins, you can import types from the plugin package:
+
+```
+import type { Plugin } from "@opencode-ai/plugin"
+export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {  return {    // Type-safe hook implementations  }}
+```
+
+---
+
+### Events
+
+Plugins can subscribe to events as seen below in the Examples section. Here is a list of the different events available.
+
+#### Command Events
+
+- command.executed
+
+#### File Events
+
+- file.edited
+- file.watcher.updated
+
+#### Installation Events
+
+- installation.updated
+
+#### LSP Events
+
+- lsp.client.diagnostics
+- lsp.updated
+
+#### Message Events
+
+- message.part.removed
+- message.part.updated
+- message.removed
+- message.updated
+
+#### Permission Events
+
+- permission.asked
+- permission.replied
+
+#### Server Events
+
+- server.connected
+
+#### Session Events
+
+- session.created
+- session.compacted
+- session.deleted
+- session.diff
+- session.error
+- session.idle
+- session.status
+- session.updated
+
+#### Todo Events
+
+- todo.updated
+
+#### Shell Events
+
+- shell.env
+
+#### Tool Events
+
+- tool.execute.after
+- tool.execute.before
+
+#### TUI Events
+
+- tui.prompt.append
+- tui.command.execute
+- tui.toast.show
+
+---
+
+## Examples
+
+Here are some examples of plugins you can use to extend opencode.
+
+---
+
+### Send notifications
+
+Send notifications when certain events occur:
+
+```
+export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {  return {    event: async ({ event }) => {      // Send notification on session completion      if (event.type === "session.idle") {        await $`osascript -e 'display notification "Session completed!" with title "opencode"'`      }    },  }}
+```
+
+We are using osascript to run AppleScript on macOS. Here we are using it to send notifications.
+
+---
+
+### .env protection
+
+Prevent opencode from reading .env files:
+
+```
+export const EnvProtection = async ({ project, client, $, directory, worktree }) => {  return {    "tool.execute.before": async (input, output) => {      if (input.tool === "read" && output.args.filePath.includes(".env")) {        throw new Error("Do not read .env files")      }    },  }}
+```
+
+---
+
+### Inject environment variables
+
+Inject environment variables into all shell execution (AI tools and user terminals):
+
+```
+export const InjectEnvPlugin = async () => {  return {    "shell.env": async (input, output) => {      output.env.MY_API_KEY = "secret"      output.env.PROJECT_ROOT = input.cwd    },  }}
+```
+
+---
+
+### Custom tools
+
+Plugins can also add custom tools to opencode:
+
+```
+import { type Plugin, tool } from "@opencode-ai/plugin"
+export const CustomToolsPlugin: Plugin = async (ctx) => {  return {    tool: {      mytool: tool({        description: "This is a custom tool",        args: {          foo: tool.schema.string(),        },        async execute(args, context) {          const { directory, worktree } = context          return `Hello ${args.foo} from ${directory} (worktree: ${worktree})`        },      }),    },  }}
+```
+
+The tool helper creates a custom tool that opencode can call. It takes a Zod schema function and returns a tool definition with:
+
+- description: What the tool does
+- args: Zod schema for the tool’s arguments
+- execute: Function that runs when the tool is called
+
+Your custom tools will be available to opencode alongside built-in tools.
+
+---
+
+### Logging
+
+Use client.app.log() instead of console.log for structured logging:
+
+```
+export const MyPlugin = async ({ client }) => {  await client.app.log({    body: {      service: "my-plugin",      level: "info",      message: "Plugin initialized",      extra: { foo: "bar" },    },  })}
+```
+
+Levels: debug, info, warn, error. See SDK documentation for details.
+
+---
+
+### Compaction hooks
+
+Customize the context included when a session is compacted:
+
+```
+import type { Plugin } from "@opencode-ai/plugin"
+export const CompactionPlugin: Plugin = async (ctx) => {  return {    "experimental.session.compacting": async (input, output) => {      // Inject additional context into the compaction prompt      output.context.push(`## Custom Context
+Include any state that should persist across compaction:- Current task status- Important decisions made- Files being actively worked on`)    },  }}
+```
+
+The experimental.session.compacting hook fires before the LLM generates a continuation summary. Use it to inject domain-specific context that the default compaction prompt would miss.
+
+You can also replace the compaction prompt entirely by setting output.prompt:
+
+```
+import type { Plugin } from "@opencode-ai/plugin"
+export const CustomCompactionPlugin: Plugin = async (ctx) => {  return {    "experimental.session.compacting": async (input, output) => {      // Replace the entire compaction prompt      output.prompt = `You are generating a continuation prompt for a multi-agent swarm session.
+Summarize:1. The current task and its status2. Which files are being modified and by whom3. Any blockers or dependencies between agents4. The next steps to complete the work
+Format as a structured prompt that a new agent can use to resume work.`    },  }}
+```
+
+When output.prompt is set, it completely replaces the default compaction prompt. The output.context array is ignored in this case.

homelab/raw/articles/opencode/docs/providers.md

@@ -0,0 +1,727 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/providers/
+scraped: 2026-04-28T21:02:13.229640+00:00
+content_hash: 4cbc40bd
+---
+# Providers
+
+Using any LLM provider in OpenCode.
+
+OpenCode uses the AI SDK and Models.dev to support 75+ LLM providers and it supports running local models.
+
+To add a provider you need to:
+
+1. Add the API keys for the provider using the /connect command.
+2. Configure the provider in your OpenCode config.
+
+---
+
+### Credentials
+
+When you add a provider’s API keys with the /connect command, they are stored in ~/.local/share/opencode/auth.json.
+
+---
+
+### Config
+
+You can customize the providers through the provider section in your OpenCode config.
+
+---
+
+#### Base URL
+
+You can customize the base URL for any provider by setting the baseURL option. This is useful when using proxy services or custom endpoints.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "anthropic": {      "options": {        "baseURL": "https://api.anthropic.com/v1"      }    }  }}
+```
+
+---
+
+## OpenCode Zen
+
+OpenCode Zen is a list of models provided by the OpenCode team that have been tested and verified to work well with OpenCode. Learn more.
+
+1. Run the /connect command in the TUI, select OpenCode Zen, and head to opencode.ai/auth. /connect
+2. Sign in, add your billing details, and copy your API key.
+3. Paste your API key. ┌ API key││└ enter
+4. Run /models in the TUI to see the list of models we recommend. /models
+
+It works like any other provider in OpenCode and is completely optional to use.
+
+---
+
+## OpenCode Go
+
+OpenCode Go is a low cost subscription plan that provides reliable access to popular open coding models provided by the OpenCode team that have been tested and verified to work well with OpenCode.
+
+1. Run the /connect command in the TUI, select OpenCode Go, and head to opencode.ai/auth. /connect
+2. Sign in, add your billing details, and copy your API key.
+3. Paste your API key. ┌ API key││└ enter
+4. Run /models in the TUI to see the list of models we recommend. /models
+
+It works like any other provider in OpenCode and is completely optional to use.
+
+---
+
+## Directory
+
+Let’s look at some of the providers in detail. If you’d like to add a provider to the list, feel free to open a PR.
+
+---
+
+### 302.AI
+
+1. Head over to the 302.AI console, create an account, and generate an API key.
+2. Run the /connect command and search for 302.AI. /connect
+3. Enter your 302.AI API key. ┌ API key││└ enter
+4. Run the /models command to select a model. /models
+
+---
+
+### Amazon Bedrock
+
+To use Amazon Bedrock with OpenCode:
+
+1. Head over to the Model catalog in the Amazon Bedrock console and request access to the models you want.
+2. Configure authentication using one of the following methods: Environment Variables (Quick Start) Set one of these environment variables while running opencode: Terminal window# Option 1: Using AWS access keysAWS_ACCESS_KEY_ID=XXX AWS_SECRET_ACCESS_KEY=YYY opencode # Option 2: Using named AWS profileAWS_PROFILE=my-profile opencode # Option 3: Using Bedrock bearer tokenAWS_BEARER_TOKEN_BEDROCK=XXX opencode Or add them to your bash profile: ~/.bash_profileexport AWS_PROFILE=my-dev-profileexport AWS_REGION=us-east-1 Configuration File (Recommended) For project-specific or persistent configuration, use opencode.json: opencode.json{ "$schema": "https://opencode.ai/config.json", "provider": { "amazon-bedrock": { "options": { "region": "us-east-1", "profile": "my-aws-profile" } } }} Available options: region - AWS region (e.g., us-east-1, eu-west-1) profile - AWS named profile from ~/.aws/credentials endpoint - Custom endpoint URL for VPC endpoints (alias for generic baseURL option) Advanced: VPC Endpoints If you’re using VPC endpoints for Bedrock: opencode.json{ "$schema": "https://opencode.ai/config.json", "provider": { "amazon-bedrock": { "options": { "region": "us-east-1", "profile": "production", "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com" } } }} Authentication Methods AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY: Create an IAM user and generate access keys in the AWS Console AWS_PROFILE: Use named profiles from ~/.aws/credentials. First configure with aws configure --profile my-profile or aws sso login AWS_BEARER_TOKEN_BEDROCK: Generate long-term API keys from the Amazon Bedrock console AWS_WEB_IDENTITY_TOKEN_FILE / AWS_ROLE_ARN: For EKS IRSA (IAM Roles for Service Accounts) or other Kubernetes environments with OIDC federation. These environment variables are automatically injected by Kubernetes when using service account annotations. Authentication Precedence Amazon Bedrock uses the following authentication priority: Bearer Token - AWS_BEARER_TOKEN_BEDROCK environment variable or token from /connect command AWS Credential Chain - Profile, access keys, shared credentials, IAM roles, Web Identity Tokens (EKS IRSA), instance metadata
+3. Run the /models command to select the model you want. /models
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "amazon-bedrock": {      // ...      "models": {        "anthropic-claude-sonnet-4.5": {          "id": "arn:aws:bedrock:us-east-1:xxx:application-inference-profile/yyy"        }      }    }  }}
+```
+
+---
+
+### Anthropic
+
+1. Once you’ve signed up, run the /connect command and select Anthropic. /connect
+2. Here you can select the Claude Pro/Max option and it’ll open your browser and ask you to authenticate. ┌ Select auth method││ Manually enter API Key└
+3. Now all the Anthropic models should be available when you use the /models command. /models
+
+There are plugins that allow you to use your Claude Pro/Max models with OpenCode. Anthropic explicitly prohibits this.
+
+Previous versions of OpenCode came bundled with these plugins but that is no longer the case as of 1.3.0
+
+Other companies support freedom of choice with developer tooling - you can use the following subscriptions in OpenCode with zero setup:
+
+- ChatGPT Plus
+- Github Copilot
+- Gitlab Duo
+
+---
+
+### Azure OpenAI
+
+1. Head over to the Azure portal and create an Azure OpenAI resource. You’ll need: Resource name: This becomes part of your API endpoint (https://RESOURCE_NAME.openai.azure.com/) API key: Either KEY 1 or KEY 2 from your resource
+2. Go to Azure AI Foundry and deploy a model.
+3. Run the /connect command and search for Azure. /connect
+4. Enter your API key. ┌ API key││└ enter
+5. Set your resource name as an environment variable: Terminal windowAZURE_RESOURCE_NAME=XXX opencode Or add it to your bash profile: ~/.bash_profileexport AZURE_RESOURCE_NAME=XXX
+6. Run the /models command to select your deployed model. /models
+
+---
+
+### Azure Cognitive Services
+
+1. Head over to the Azure portal and create an Azure OpenAI resource. You’ll need: Resource name: This becomes part of your API endpoint (https://AZURE_COGNITIVE_SERVICES_RESOURCE_NAME.cognitiveservices.azure.com/) API key: Either KEY 1 or KEY 2 from your resource
+2. Go to Azure AI Foundry and deploy a model.
+3. Run the /connect command and search for Azure Cognitive Services. /connect
+4. Enter your API key. ┌ API key││└ enter
+5. Set your resource name as an environment variable: Terminal windowAZURE_COGNITIVE_SERVICES_RESOURCE_NAME=XXX opencode Or add it to your bash profile: ~/.bash_profileexport AZURE_COGNITIVE_SERVICES_RESOURCE_NAME=XXX
+6. Run the /models command to select your deployed model. /models
+
+---
+
+### Baseten
+
+1. Head over to the Baseten, create an account, and generate an API key.
+2. Run the /connect command and search for Baseten. /connect
+3. Enter your Baseten API key. ┌ API key││└ enter
+4. Run the /models command to select a model. /models
+
+---
+
+### Cerebras
+
+1. Head over to the Cerebras console, create an account, and generate an API key.
+2. Run the /connect command and search for Cerebras. /connect
+3. Enter your Cerebras API key. ┌ API key││└ enter
+4. Run the /models command to select a model like Qwen 3 Coder 480B. /models
+
+---
+
+### Cloudflare AI Gateway
+
+Cloudflare AI Gateway lets you access models from OpenAI, Anthropic, Workers AI, and more through a unified endpoint. With Unified Billing you don’t need separate API keys for each provider.
+
+1. Head over to the Cloudflare dashboard, navigate to AI > AI Gateway, and create a new gateway. Note your Account ID and Gateway ID.
+2. Run the /connect command and search for Cloudflare AI Gateway. /connect
+3. Enter your Account ID when prompted. ┌ Enter your Cloudflare Account ID││└ enter
+4. Enter your Gateway ID when prompted. ┌ Enter your Cloudflare AI Gateway ID││└ enter
+5. Enter your Cloudflare API token. ┌ Gateway API token││└ enter
+6. Run the /models command to select a model. /models You can also add models through your opencode config. opencode.json{ "$schema": "https://opencode.ai/config.json", "provider": { "cloudflare-ai-gateway": { "models": { "openai/gpt-4o": {}, "anthropic/claude-sonnet-4": {} } } }} Alternatively, you can set environment variables instead of using /connect. ~/.bash_profileexport CLOUDFLARE_ACCOUNT_ID=your-32-character-account-idexport CLOUDFLARE_GATEWAY_ID=your-gateway-idexport CLOUDFLARE_API_TOKEN=your-api-token
+
+---
+
+### Cloudflare Workers AI
+
+Cloudflare Workers AI lets you run AI models on Cloudflare’s global network directly via REST API, with no separate provider accounts needed for supported models.
+
+1. Head over to the Cloudflare dashboard, navigate to Workers AI, and select Use REST API to get your Account ID and create an API token.
+2. Run the /connect command and search for Cloudflare Workers AI. /connect
+3. Enter your Account ID when prompted. ┌ Enter your Cloudflare Account ID││└ enter
+4. Enter your Cloudflare API key. ┌ API key││└ enter
+5. Run the /models command to select a model. /models Alternatively, you can set environment variables instead of using /connect. ~/.bash_profileexport CLOUDFLARE_ACCOUNT_ID=your-32-character-account-idexport CLOUDFLARE_API_KEY=your-api-token
+
+---
+
+### Cortecs
+
+1. Head over to the Cortecs console, create an account, and generate an API key.
+2. Run the /connect command and search for Cortecs. /connect
+3. Enter your Cortecs API key. ┌ API key││└ enter
+4. Run the /models command to select a model like Kimi K2 Instruct. /models
+
+---
+
+### DeepSeek
+
+1. Head over to the DeepSeek console, create an account, and click Create new API key.
+2. Run the /connect command and search for DeepSeek. /connect
+3. Enter your DeepSeek API key. ┌ API key││└ enter
+4. Run the /models command to select a DeepSeek model like DeepSeek V4 Pro. /models
+
+---
+
+### Deep Infra
+
+1. Head over to the Deep Infra dashboard, create an account, and generate an API key.
+2. Run the /connect command and search for Deep Infra. /connect
+3. Enter your Deep Infra API key. ┌ API key││└ enter
+4. Run the /models command to select a model. /models
+
+---
+
+### Firmware
+
+1. Head over to the Firmware dashboard, create an account, and generate an API key.
+2. Run the /connect command and search for Firmware. /connect
+3. Enter your Firmware API key. ┌ API key││└ enter
+4. Run the /models command to select a model. /models
+
+---
+
+### Fireworks AI
+
+1. Head over to the Fireworks AI console, create an account, and click Create API Key.
+2. Run the /connect command and search for Fireworks AI. /connect
+3. Enter your Fireworks AI API key. ┌ API key││└ enter
+4. Run the /models command to select a model like Kimi K2 Instruct. /models
+
+---
+
+### GitLab Duo
+
+OpenCode integrates with the GitLab Duo Agent Platform, providing AI-powered agentic chat with native tool calling capabilities.
+
+1. Run the /connect command and select GitLab. /connect
+2. Choose your authentication method: ┌ Select auth method││ OAuth (Recommended)│ Personal Access Token└ Using OAuth (Recommended) Select OAuth and your browser will open for authorization. Using Personal Access Token Go to GitLab User Settings > Access Tokens Click Add new token Name: OpenCode, Scopes: api Copy the token (starts with glpat-) Enter it in the terminal
+3. Run the /models command to see available models. /models Three Claude-based models are available: duo-chat-haiku-4-5 (Default) - Fast responses for quick tasks duo-chat-sonnet-4-5 - Balanced performance for most workflows duo-chat-opus-4-5 - Most capable for complex analysis
+
+##### Self-Hosted GitLab
+
+For self-hosted GitLab instances:
+
+```
+export GITLAB_INSTANCE_URL=https://gitlab.company.comexport GITLAB_TOKEN=glpat-...
+```
+
+If your instance runs a custom AI Gateway:
+
+```
+GITLAB_AI_GATEWAY_URL=https://ai-gateway.company.com
+```
+
+Or add to your bash profile:
+
+```
+export GITLAB_INSTANCE_URL=https://gitlab.company.comexport GITLAB_AI_GATEWAY_URL=https://ai-gateway.company.comexport GITLAB_TOKEN=glpat-...
+```
+
+##### OAuth for Self-Hosted instances
+
+In order to make Oauth working for your self-hosted instance, you need to create a new application (Settings → Applications) with the callback URL http://127.0.0.1:8080/callback and following scopes:
+
+- api (Access the API on your behalf)
+- read_user (Read your personal information)
+- read_repository (Allows read-only access to the repository)
+
+Then expose application ID as environment variable:
+
+```
+export GITLAB_OAUTH_CLIENT_ID=your_application_id_here
+```
+
+More documentation on opencode-gitlab-auth homepage.
+
+##### Configuration
+
+Customize through opencode.json:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "gitlab": {      "options": {        "instanceUrl": "https://gitlab.com"      }    }  }}
+```
+
+##### GitLab Duo Agent Platform (DAP) Workflow Models
+
+DAP workflow models provide an alternative execution path that routes tool calls through GitLab’s Duo Workflow Service (DWS) instead of the standard agentic chat. When a duo-workflow-* model is selected, OpenCode will:
+
+1. Discover available models from your GitLab namespace
+2. Present a selection picker if multiple models are available
+3. Cache the selected model to disk for fast subsequent startups
+4. Route tool execution requests through OpenCode’s permission-gated tool system
+
+Available DAP workflow models follow the duo-workflow-* naming convention and are dynamically discovered from your GitLab instance.
+
+##### GitLab API Tools (Optional, but highly recommended)
+
+To access GitLab tools (merge requests, issues, pipelines, CI/CD, etc.):
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "plugin": ["opencode-gitlab-plugin"]}
+```
+
+This plugin provides comprehensive GitLab repository management capabilities including MR reviews, issue tracking, pipeline monitoring, and more.
+
+---
+
+### GitHub Copilot
+
+To use your GitHub Copilot subscription with opencode:
+
+1. Run the /connect command and search for GitHub Copilot. /connect
+2. Navigate to github.com/login/device and enter the code. ┌ Login with GitHub Copilot││ https://github.com/login/device││ Enter code: 8F43-6FCF│└ Waiting for authorization...
+3. Now run the /models command to select the model you want. /models
+
+---
+
+### Google Vertex AI
+
+To use Google Vertex AI with OpenCode:
+
+1. Head over to the Model Garden in the Google Cloud Console and check the models available in your region.
+2. Set the required environment variables: GOOGLE_CLOUD_PROJECT: Your Google Cloud project ID VERTEX_LOCATION (optional): The region for Vertex AI (defaults to global) Authentication (choose one): GOOGLE_APPLICATION_CREDENTIALS: Path to your service account JSON key file Authenticate using gcloud CLI: gcloud auth application-default login Set them while running opencode. Terminal windowGOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json GOOGLE_CLOUD_PROJECT=your-project-id opencode Or add them to your bash profile. ~/.bash_profileexport GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.jsonexport GOOGLE_CLOUD_PROJECT=your-project-idexport VERTEX_LOCATION=global
+
+1. Run the /models command to select the model you want. /models
+
+---
+
+### Groq
+
+1. Head over to the Groq console, click Create API Key, and copy the key.
+2. Run the /connect command and search for Groq. /connect
+3. Enter the API key for the provider. ┌ API key││└ enter
+4. Run the /models command to select the one you want. /models
+
+---
+
+### Hugging Face
+
+Hugging Face Inference Providers provides access to open models supported by 17+ providers.
+
+1. Head over to Hugging Face settings to create a token with permission to make calls to Inference Providers.
+2. Run the /connect command and search for Hugging Face. /connect
+3. Enter your Hugging Face token. ┌ API key││└ enter
+4. Run the /models command to select a model like Kimi-K2-Instruct or GLM-4.6. /models
+
+---
+
+### Helicone
+
+Helicone is an LLM observability platform that provides logging, monitoring, and analytics for your AI applications. The Helicone AI Gateway routes your requests to the appropriate provider automatically based on the model.
+
+1. Head over to Helicone, create an account, and generate an API key from your dashboard.
+2. Run the /connect command and search for Helicone. /connect
+3. Enter your Helicone API key. ┌ API key││└ enter
+4. Run the /models command to select a model. /models
+
+For more providers and advanced features like caching and rate limiting, check the Helicone documentation.
+
+#### Optional Configs
+
+In the event you see a feature or model from Helicone that isn’t configured automatically through opencode, you can always configure it yourself.
+
+Here’s Helicone’s Model Directory, you’ll need this to grab the IDs of the models you want to add.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "helicone": {      "npm": "@ai-sdk/openai-compatible",      "name": "Helicone",      "options": {        "baseURL": "https://ai-gateway.helicone.ai",      },      "models": {        "gpt-4o": {          // Model ID (from Helicone's model directory page)          "name": "GPT-4o", // Your own custom name for the model        },        "claude-sonnet-4-20250514": {          "name": "Claude Sonnet 4",        },      },    },  },}
+```
+
+#### Custom Headers
+
+Helicone supports custom headers for features like caching, user tracking, and session management. Add them to your provider config using options.headers:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "helicone": {      "npm": "@ai-sdk/openai-compatible",      "name": "Helicone",      "options": {        "baseURL": "https://ai-gateway.helicone.ai",        "headers": {          "Helicone-Cache-Enabled": "true",          "Helicone-User-Id": "opencode",        },      },    },  },}
+```
+
+##### Session tracking
+
+Helicone’s Sessions feature lets you group related LLM requests together. Use the opencode-helicone-session plugin to automatically log each OpenCode conversation as a session in Helicone.
+
+```
+npm install -g opencode-helicone-session
+```
+
+Add it to your config.
+
+```
+{  "plugin": ["opencode-helicone-session"]}
+```
+
+The plugin injects Helicone-Session-Id and Helicone-Session-Name headers into your requests. In Helicone’s Sessions page, you’ll see each OpenCode conversation listed as a separate session.
+
+##### Common Helicone headers
+
+| Header | Description |
+|---|---|
+| Helicone-Cache-Enabled | Enable response caching (true/false) |
+| Helicone-User-Id | Track metrics by user |
+| Helicone-Property-[Name] | Add custom properties (e.g., Helicone-Property-Environment) |
+| Helicone-Prompt-Id | Associate requests with prompt versions |
+
+See the Helicone Header Directory for all available headers.
+
+---
+
+### llama.cpp
+
+You can configure opencode to use local models through llama.cpp’s llama-server utility
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "llama.cpp": {      "npm": "@ai-sdk/openai-compatible",      "name": "llama-server (local)",      "options": {        "baseURL": "http://127.0.0.1:8080/v1"      },      "models": {        "qwen3-coder:a3b": {          "name": "Qwen3-Coder: a3b-30b (local)",          "limit": {            "context": 128000,            "output": 65536          }        }      }    }  }}
+```
+
+In this example:
+
+- llama.cpp is the custom provider ID. This can be any string you want.
+- npm specifies the package to use for this provider. Here, @ai-sdk/openai-compatible is used for any OpenAI-compatible API.
+- name is the display name for the provider in the UI.
+- options.baseURL is the endpoint for the local server.
+- models is a map of model IDs to their configurations. The model name will be displayed in the model selection list.
+
+---
+
+### IO.NET
+
+IO.NET offers 17 models optimized for various use cases:
+
+1. Head over to the IO.NET console, create an account, and generate an API key.
+2. Run the /connect command and search for IO.NET. /connect
+3. Enter your IO.NET API key. ┌ API key││└ enter
+4. Run the /models command to select a model. /models
+
+---
+
+### LM Studio
+
+You can configure opencode to use local models through LM Studio.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "lmstudio": {      "npm": "@ai-sdk/openai-compatible",      "name": "LM Studio (local)",      "options": {        "baseURL": "http://127.0.0.1:1234/v1"      },      "models": {        "google/gemma-3n-e4b": {          "name": "Gemma 3n-e4b (local)"        }      }    }  }}
+```
+
+In this example:
+
+- lmstudio is the custom provider ID. This can be any string you want.
+- npm specifies the package to use for this provider. Here, @ai-sdk/openai-compatible is used for any OpenAI-compatible API.
+- name is the display name for the provider in the UI.
+- options.baseURL is the endpoint for the local server.
+- models is a map of model IDs to their configurations. The model name will be displayed in the model selection list.
+
+---
+
+### Moonshot AI
+
+To use Kimi K2 from Moonshot AI:
+
+1. Head over to the Moonshot AI console, create an account, and click Create API key.
+2. Run the /connect command and search for Moonshot AI. /connect
+3. Enter your Moonshot API key. ┌ API key││└ enter
+4. Run the /models command to select Kimi K2. /models
+
+---
+
+### MiniMax
+
+1. Head over to the MiniMax API Console, create an account, and generate an API key.
+2. Run the /connect command and search for MiniMax. /connect
+3. Enter your MiniMax API key. ┌ API key││└ enter
+4. Run the /models command to select a model like M2.1. /models
+
+---
+
+### NVIDIA
+
+NVIDIA provides access to Nemotron models and many other open models through build.nvidia.com for free.
+
+1. Head over to build.nvidia.com, create an account, and generate an API key.
+2. Run the /connect command and search for NVIDIA. /connect
+3. Enter your NVIDIA API key. ┌ API key││└ enter
+4. Run the /models command to select a model like nemotron-3-super-120b-a12b. /models
+
+#### On-Prem / NIM
+
+You can also use NVIDIA models locally via NVIDIA NIM by setting a custom base URL.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "nvidia": {      "options": {        "baseURL": "http://localhost:8000/v1"      }    }  }}
+```
+
+#### Environment Variable
+
+Alternatively, set your API key as an environment variable.
+
+```
+export NVIDIA_API_KEY=nvapi-your-key-here
+```
+
+---
+
+### Nebius Token Factory
+
+1. Head over to the Nebius Token Factory console, create an account, and click Add Key.
+2. Run the /connect command and search for Nebius Token Factory. /connect
+3. Enter your Nebius Token Factory API key. ┌ API key││└ enter
+4. Run the /models command to select a model like Kimi K2 Instruct. /models
+
+---
+
+### Ollama
+
+You can configure opencode to use local models through Ollama.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "ollama": {      "npm": "@ai-sdk/openai-compatible",      "name": "Ollama (local)",      "options": {        "baseURL": "http://localhost:11434/v1"      },      "models": {        "llama2": {          "name": "Llama 2"        }      }    }  }}
+```
+
+In this example:
+
+- ollama is the custom provider ID. This can be any string you want.
+- npm specifies the package to use for this provider. Here, @ai-sdk/openai-compatible is used for any OpenAI-compatible API.
+- name is the display name for the provider in the UI.
+- options.baseURL is the endpoint for the local server.
+- models is a map of model IDs to their configurations. The model name will be displayed in the model selection list.
+
+---
+
+### Ollama Cloud
+
+To use Ollama Cloud with OpenCode:
+
+1. Head over to https://ollama.com/ and sign in or create an account.
+2. Navigate to Settings > Keys and click Add API Key to generate a new API key.
+3. Copy the API key for use in OpenCode.
+4. Run the /connect command and search for Ollama Cloud. /connect
+5. Enter your Ollama Cloud API key. ┌ API key││└ enter
+6. Important: Before using cloud models in OpenCode, you must pull the model information locally: Terminal windowollama pull gpt-oss:20b-cloud
+7. Run the /models command to select your Ollama Cloud model. /models
+
+---
+
+### OpenAI
+
+We recommend signing up for ChatGPT Plus or Pro.
+
+1. Once you’ve signed up, run the /connect command and select OpenAI. /connect
+2. Here you can select the ChatGPT Plus/Pro option and it’ll open your browser and ask you to authenticate. ┌ Select auth method││ ChatGPT Plus/Pro│ Manually enter API Key└
+3. Now all the OpenAI models should be available when you use the /models command. /models
+
+##### Using API keys
+
+If you already have an API key, you can select Manually enter API Key and paste it in your terminal.
+
+---
+
+OpenCode Zen is a list of tested and verified models provided by the OpenCode team. Learn more.
+
+1. Sign in to OpenCode Zen and click Create API Key.
+2. Run the /connect command and search for OpenCode Zen. /connect
+3. Enter your OpenCode API key. ┌ API key││└ enter
+4. Run the /models command to select a model like Qwen 3 Coder 480B. /models
+
+---
+
+### OpenRouter
+
+1. Head over to the OpenRouter dashboard, click Create API Key, and copy the key.
+2. Run the /connect command and search for OpenRouter. /connect
+3. Enter the API key for the provider. ┌ API key││└ enter
+4. Many OpenRouter models are preloaded by default, run the /models command to select the one you want. /models You can also add additional models through your opencode config. opencode.json{ "$schema": "https://opencode.ai/config.json", "provider": { "openrouter": { "models": { "somecoolnewmodel": {} } } }}
+5. You can also customize them through your opencode config. Here’s an example of specifying a provider opencode.json{ "$schema": "https://opencode.ai/config.json", "provider": { "openrouter": { "models": { "moonshotai/kimi-k2": { "options": { "provider": { "order": ["baseten"], "allow_fallbacks": false } } } } } }}
+
+---
+
+### LLM Gateway
+
+1. Head over to the LLM Gateway dashboard, click Create API Key, and copy the key.
+2. Run the /connect command and search for LLM Gateway. /connect
+3. Enter the API key for the provider. ┌ API key││└ enter
+4. Many LLM Gateway models are preloaded by default, run the /models command to select the one you want. /models You can also add additional models through your opencode config. opencode.json{ "$schema": "https://opencode.ai/config.json", "provider": { "llmgateway": { "models": { "somecoolnewmodel": {} } } }}
+5. You can also customize them through your opencode config. Here’s an example of specifying a provider opencode.json{ "$schema": "https://opencode.ai/config.json", "provider": { "llmgateway": { "models": { "glm-4.7": { "name": "GLM 4.7" }, "gpt-5.2": { "name": "GPT-5.2" }, "gemini-2.5-pro": { "name": "Gemini 2.5 Pro" }, "claude-3-5-sonnet-20241022": { "name": "Claude 3.5 Sonnet" } } } }}
+
+---
+
+### SAP AI Core
+
+SAP AI Core provides access to 40+ models from OpenAI, Anthropic, Google, Amazon, Meta, Mistral, and AI21 through a unified platform.
+
+1. Go to your SAP BTP Cockpit, navigate to your SAP AI Core service instance, and create a service key.
+2. Run the /connect command and search for SAP AI Core. /connect
+3. Enter your service key JSON. ┌ Service key││└ enter Or set the AICORE_SERVICE_KEY environment variable: Terminal windowAICORE_SERVICE_KEY='{"clientid":"...","clientsecret":"...","url":"...","serviceurls":{"AI_API_URL":"..."}}' opencode Or add it to your bash profile: ~/.bash_profileexport AICORE_SERVICE_KEY='{"clientid":"...","clientsecret":"...","url":"...","serviceurls":{"AI_API_URL":"..."}}'
+4. Optionally set deployment ID and resource group: Terminal windowAICORE_DEPLOYMENT_ID=your-deployment-id AICORE_RESOURCE_GROUP=your-resource-group opencode
+5. Run the /models command to select from 40+ available models. /models
+
+---
+
+### STACKIT
+
+STACKIT AI Model Serving provides fully managed soverign hosting environment for AI models, focusing on LLMs like Llama, Mistral, and Qwen, with maximum data sovereignty on European infrastructure.
+
+1. Head over to STACKIT Portal, navigate to AI Model Serving, and create an auth token for your project.
+2. Run the /connect command and search for STACKIT. /connect
+3. Enter your STACKIT AI Model Serving auth token. ┌ API key││└ enter
+4. Run the /models command to select from available models like Qwen3-VL 235B or Llama 3.3 70B. /models
+
+---
+
+### OVHcloud AI Endpoints
+
+1. Head over to the OVHcloud panel. Navigate to the Public Cloud section, AI & Machine Learning > AI Endpoints and in API Keys tab, click Create a new API key.
+2. Run the /connect command and search for OVHcloud AI Endpoints. /connect
+3. Enter your OVHcloud AI Endpoints API key. ┌ API key││└ enter
+4. Run the /models command to select a model like gpt-oss-120b. /models
+
+---
+
+### Scaleway
+
+To use Scaleway Generative APIs with Opencode:
+
+1. Head over to the Scaleway Console IAM settings to generate a new API key.
+2. Run the /connect command and search for Scaleway. /connect
+3. Enter your Scaleway API key. ┌ API key││└ enter
+4. Run the /models command to select a model like devstral-2-123b-instruct-2512 or gpt-oss-120b. /models
+
+---
+
+### Together AI
+
+1. Head over to the Together AI console, create an account, and click Add Key.
+2. Run the /connect command and search for Together AI. /connect
+3. Enter your Together AI API key. ┌ API key││└ enter
+4. Run the /models command to select a model like Kimi K2 Instruct. /models
+
+---
+
+### Venice AI
+
+1. Head over to the Venice AI console, create an account, and generate an API key.
+2. Run the /connect command and search for Venice AI. /connect
+3. Enter your Venice AI API key. ┌ API key││└ enter
+4. Run the /models command to select a model like Llama 3.3 70B. /models
+
+---
+
+### Vercel AI Gateway
+
+Vercel AI Gateway lets you access models from OpenAI, Anthropic, Google, xAI, and more through a unified endpoint. Models are offered at list price with no markup.
+
+1. Head over to the Vercel dashboard, navigate to the AI Gateway tab, and click API keys to create a new API key.
+2. Run the /connect command and search for Vercel AI Gateway. /connect
+3. Enter your Vercel AI Gateway API key. ┌ API key││└ enter
+4. Run the /models command to select a model. /models
+
+You can also customize models through your opencode config. Here’s an example of specifying provider routing order.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "vercel": {      "models": {        "anthropic/claude-sonnet-4": {          "options": {            "order": ["anthropic", "vertex"]          }        }      }    }  }}
+```
+
+Some useful routing options:
+
+| Option | Description |
+|---|---|
+| order | Provider sequence to try |
+| only | Restrict to specific providers |
+| zeroDataRetention | Only use providers with zero data retention policies |
+
+---
+
+### xAI
+
+1. Head over to the xAI console, create an account, and generate an API key.
+2. Run the /connect command and search for xAI. /connect
+3. Enter your xAI API key. ┌ API key││└ enter
+4. Run the /models command to select a model like Grok Beta. /models
+
+---
+
+### Z.AI
+
+1. Head over to the Z.AI API console, create an account, and click Create a new API key.
+2. Run the /connect command and search for Z.AI. /connect If you are subscribed to the GLM Coding Plan, select Z.AI Coding Plan.
+3. Enter your Z.AI API key. ┌ API key││└ enter
+4. Run the /models command to select a model like GLM-4.7. /models
+
+---
+
+### ZenMux
+
+1. Head over to the ZenMux dashboard, click Create API Key, and copy the key.
+2. Run the /connect command and search for ZenMux. /connect
+3. Enter the API key for the provider. ┌ API key││└ enter
+4. Many ZenMux models are preloaded by default, run the /models command to select the one you want. /models You can also add additional models through your opencode config. opencode.json{ "$schema": "https://opencode.ai/config.json", "provider": { "zenmux": { "models": { "somecoolnewmodel": {} } } }}
+
+---
+
+## Custom provider
+
+To add any OpenAI-compatible provider that’s not listed in the /connect command:
+
+1. Run the /connect command and scroll down to Other. Terminal window$ /connect ┌ Add credential│◆ Select provider│ ...│ ● Other└
+2. Enter a unique ID for the provider. Terminal window$ /connect ┌ Add credential│◇ Enter provider id│ myprovider└
+3. Enter your API key for the provider. Terminal window$ /connect ┌ Add credential│▲ This only stores a credential for myprovider - you will need to configure it in opencode.json, check the docs for examples.│◇ Enter your API key│ sk-...└
+4. Create or update your opencode.json file in your project directory: opencode.json{ "$schema": "https://opencode.ai/config.json", "provider": { "myprovider": { "npm": "@ai-sdk/openai-compatible", "name": "My AI ProviderDisplay Name", "options": { "baseURL": "https://api.myprovider.com/v1" }, "models": { "my-model-name": { "name": "My Model Display Name" } } } }} Here are the configuration options: npm: AI SDK package to use, @ai-sdk/openai-compatible for OpenAI-compatible providers (for /v1/chat/completions). If your provider/model uses /v1/responses, use @ai-sdk/openai. name: Display name in UI. models: Available models. options.baseURL: API endpoint URL. options.apiKey: Optionally set the API key, if not using auth. options.headers: Optionally set custom headers. More on the advanced options in the example below.
+5. Run the /models command and your custom provider and models will appear in the selection list.
+
+---
+
+##### Example
+
+Here’s an example setting the apiKey, headers, and model limit options.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "provider": {    "myprovider": {      "npm": "@ai-sdk/openai-compatible",      "name": "My AI ProviderDisplay Name",      "options": {        "baseURL": "https://api.myprovider.com/v1",        "apiKey": "{env:ANTHROPIC_API_KEY}",        "headers": {          "Authorization": "Bearer custom-token"        }      },      "models": {        "my-model-name": {          "name": "My Model Display Name",          "limit": {            "context": 200000,            "output": 65536          }        }      }    }  }}
+```
+
+Configuration details:
+
+- apiKey: Set using env variable syntax, learn more.
+- headers: Custom headers sent with each request.
+- limit.context: Maximum input tokens the model accepts.
+- limit.output: Maximum tokens the model can generate.
+
+The limit fields allow OpenCode to understand how much context you have left. Standard providers pull these from models.dev automatically.
+
+---
+
+## Troubleshooting
+
+If you are having trouble with configuring a provider, check the following:
+
+1. Check the auth setup: Run opencode auth list to see if the credentials for the provider are added to your config. This doesn’t apply to providers like Amazon Bedrock, that rely on environment variables for their auth.
+2. For custom providers, check the opencode config and: Make sure the provider ID used in the /connect command matches the ID in your opencode config. The right npm package is used for the provider. For example, use @ai-sdk/cerebras for Cerebras. And for all other OpenAI-compatible providers, use @ai-sdk/openai-compatible (for /v1/chat/completions); if a model uses /v1/responses, use @ai-sdk/openai. For mixed setups under one provider, you can override per model via provider.npm. Check correct API endpoint is used in the options.baseURL field.

homelab/raw/articles/opencode/docs/rules.md

@@ -0,0 +1,141 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/rules/
+scraped: 2026-04-28T21:02:08.822844+00:00
+content_hash: c6c861a0
+---
+# Rules
+
+Set custom instructions for opencode.
+
+You can provide custom instructions to opencode by creating an AGENTS.md file. This is similar to Cursor’s rules. It contains instructions that will be included in the LLM’s context to customize its behavior for your specific project.
+
+---
+
+## Initialize
+
+To create a new AGENTS.md file, you can run the /init command in opencode.
+
+/init scans the important files in your repo, may ask a couple of targeted questions when the codebase cannot answer them, and then creates or updates AGENTS.md with concise project-specific guidance.
+
+It focuses on the things future agent sessions are most likely to need:
+
+- build, lint, and test commands
+- command order and focused verification steps when they matter
+- architecture and repo structure that are not obvious from filenames alone
+- project-specific conventions, setup quirks, and operational gotchas
+- references to existing instruction sources like Cursor or Copilot rules
+
+If you already have an AGENTS.md, /init will improve it in place instead of blindly replacing it.
+
+---
+
+## Example
+
+You can also just create this file manually. Here’s an example of some things you can put into an AGENTS.md file.
+
+```
+# SST v3 Monorepo Project
+This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.
+## Project Structure
+- `packages/` - Contains all workspace packages (functions, core, web, etc.)- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)- `sst.config.ts` - Main SST configuration with dynamic imports
+## Code Standards
+- Use TypeScript with strict mode enabled- Shared code goes in `packages/core/` with proper exports configuration- Functions go in `packages/functions/`- Infrastructure should be split into logical files in `infra/`
+## Monorepo Conventions
+- Import shared modules using workspace names: `@my-app/core/example`
+```
+
+We are adding project-specific instructions here and this will be shared across your team.
+
+---
+
+## Types
+
+opencode also supports reading the AGENTS.md file from multiple locations. And this serves different purposes.
+
+### Project
+
+Place an AGENTS.md in your project root for project-specific rules. These only apply when you are working in this directory or its sub-directories.
+
+### Global
+
+You can also have global rules in a ~/.config/opencode/AGENTS.md file. This gets applied across all opencode sessions.
+
+Since this isn’t committed to Git or shared with your team, we recommend using this to specify any personal rules that the LLM should follow.
+
+### Claude Code Compatibility
+
+For users migrating from Claude Code, OpenCode supports Claude Code's file conventions as fallbacks:
+
+- Project rules: CLAUDE.md in your project directory (used if no AGENTS.md exists)
+
+---
+
+## Precedence
+
+When opencode starts, it looks for rule files in this order:
+
+1. Local files by traversing up from the current directory (AGENTS.md, CLAUDE.md)
+2. Global file at ~/.config/opencode/AGENTS.md
+
+The first matching file wins in each category. For example, if you have both AGENTS.md and CLAUDE.md, only AGENTS.md is used.
+
+---
+
+## Custom Instructions
+
+You can specify custom instruction files in your opencode.json or the global ~/.config/opencode/opencode.json. This allows you and your team to reuse existing rules rather than having to duplicate them to AGENTS.md.
+
+Example:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]}
+```
+
+You can also use remote URLs to load instructions from the web.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]}
+```
+
+Remote instructions are fetched with a 5 second timeout.
+
+All instruction files are combined with your AGENTS.md files.
+
+---
+
+## Referencing External Files
+
+While opencode doesn’t automatically parse file references in AGENTS.md, you can achieve similar functionality in two ways:
+
+### Using opencode.json
+
+The recommended approach is to use the instructions field in opencode.json:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"]}
+```
+
+### Manual Instructions in AGENTS.md
+
+You can teach opencode to read external files by providing explicit instructions in your AGENTS.md. Here’s a practical example:
+
+```
+# TypeScript Project Rules
+## External File Loading
+CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.
+Instructions:
+- Do NOT preemptively load all references - use lazy loading based on actual need- When loaded, treat content as mandatory instructions that override defaults- Follow references recursively when needed
+## Development Guidelines
+For TypeScript code style and best practices: @docs/typescript-guidelines.mdFor React component architecture and hooks patterns: @docs/react-patterns.mdFor REST API design and error handling: @docs/api-standards.mdFor testing strategies and coverage requirements: @test/testing-guidelines.md
+## General Guidelines
+Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.
+```
+
+This approach allows you to:
+
+- Create modular, reusable rule files
+- Share rules across projects via symlinks or git submodules
+- Keep AGENTS.md concise while referencing detailed guidelines
+- Ensure opencode loads files only when needed for the specific task

homelab/raw/articles/opencode/docs/sdk.md

@@ -0,0 +1,339 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/sdk/
+scraped: 2026-04-28T21:02:14.594110+00:00
+content_hash: 4720c626
+---
+# SDK
+
+Type-safe JS client for opencode server.
+
+The opencode JS/TS SDK provides a type-safe client for interacting with the server. Use it to build integrations and control opencode programmatically.
+
+Learn more about how the server works. For examples, check out the projects built by the community.
+
+---
+
+## Install
+
+Install the SDK from npm:
+
+```
+npm install @opencode-ai/sdk
+```
+
+---
+
+## Create client
+
+Create an instance of opencode:
+
+```
+import { createOpencode } from "@opencode-ai/sdk"
+const { client } = await createOpencode()
+```
+
+This starts both a server and a client
+
+#### Options
+
+| Option | Type | Description | Default |
+|---|---|---|---|
+| hostname | string | Server hostname | 127.0.0.1 |
+| port | number | Server port | 4096 |
+| signal | AbortSignal | Abort signal for cancellation | undefined |
+| timeout | number | Timeout in ms for server start | 5000 |
+| config | Config | Configuration object | {} |
+
+---
+
+## Config
+
+You can pass a configuration object to customize behavior. The instance still picks up your opencode.json, but you can override or add configuration inline:
+
+```
+import { createOpencode } from "@opencode-ai/sdk"
+const opencode = await createOpencode({  hostname: "127.0.0.1",  port: 4096,  config: {    model: "anthropic/claude-3-5-sonnet-20241022",  },})
+console.log(`Server running at ${opencode.server.url}`)
+opencode.server.close()
+```
+
+## Client only
+
+If you already have a running instance of opencode, you can create a client instance to connect to it:
+
+```
+import { createOpencodeClient } from "@opencode-ai/sdk"
+const client = createOpencodeClient({  baseUrl: "http://localhost:4096",})
+```
+
+| Option | Type | Description | Default |
+|---|---|---|---|
+| baseUrl | string | URL of the server | http://localhost:4096 |
+| fetch | function | Custom fetch implementation | globalThis.fetch |
+| parseAs | string | Response parsing method | auto |
+| responseStyle | string | Return style: data or fields | fields |
+| throwOnError | boolean | Throw errors instead of return | false |
+
+---
+
+## Types
+
+The SDK includes TypeScript definitions for all API types. Import them directly:
+
+```
+import type { Session, Message, Part } from "@opencode-ai/sdk"
+```
+
+All types are generated from the server’s OpenAPI specification and available in the types file.
+
+---
+
+## Errors
+
+The SDK can throw errors that you can catch and handle:
+
+```
+try {  await client.session.get({ path: { id: "invalid-id" } })} catch (error) {  console.error("Failed to get session:", (error as Error).message)}
+```
+
+---
+
+## Structured Output
+
+You can request structured JSON output from the model by specifying an format with a JSON schema. The model will use a StructuredOutput tool to return validated JSON matching your schema.
+
+### Basic Usage
+
+```
+const result = await client.session.prompt({  path: { id: sessionId },  body: {    parts: [{ type: "text", text: "Research Anthropic and provide company info" }],    format: {      type: "json_schema",      schema: {        type: "object",        properties: {          company: { type: "string", description: "Company name" },          founded: { type: "number", description: "Year founded" },          products: {            type: "array",            items: { type: "string" },            description: "Main products",          },        },        required: ["company", "founded"],      },    },  },})
+// Access the structured outputconsole.log(result.data.info.structured_output)// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }
+```
+
+### Output Format Types
+
+| Type | Description |
+|---|---|
+| text | Default. Standard text response (no structured output) |
+| json_schema | Returns validated JSON matching the provided schema |
+
+### JSON Schema Format
+
+When using type: 'json_schema', provide:
+
+| Field | Type | Description |
+|---|---|---|
+| type | 'json_schema' | Required. Specifies JSON schema mode |
+| schema | object | Required. JSON Schema object defining the output structure |
+| retryCount | number | Optional. Number of validation retries (default: 2) |
+
+### Error Handling
+
+If the model fails to produce valid structured output after all retries, the response will include a StructuredOutputError:
+
+```
+if (result.data.info.error?.name === "StructuredOutputError") {  console.error("Failed to produce structured output:", result.data.info.error.message)  console.error("Attempts:", result.data.info.error.retries)}
+```
+
+### Best Practices
+
+1. Provide clear descriptions in your schema properties to help the model understand what data to extract
+2. Use required to specify which fields must be present
+3. Keep schemas focused - complex nested schemas may be harder for the model to fill correctly
+4. Set appropriate retryCount - increase for complex schemas, decrease for simple ones
+
+---
+
+## APIs
+
+The SDK exposes all server APIs through a type-safe client.
+
+---
+
+### Global
+
+| Method | Description | Response |
+|---|---|---|
+| global.health() | Check server health and version | { healthy: true, version: string } |
+
+---
+
+#### Examples
+
+```
+const health = await client.global.health()console.log(health.data.version)
+```
+
+---
+
+### App
+
+| Method | Description | Response |
+|---|---|---|
+| app.log() | Write a log entry | boolean |
+| app.agents() | List all available agents | Agent[] |
+
+---
+
+```
+// Write a log entryawait client.app.log({  body: {    service: "my-app",    level: "info",    message: "Operation completed",  },})
+// List available agentsconst agents = await client.app.agents()
+```
+
+---
+
+### Project
+
+| Method | Description | Response |
+|---|---|---|
+| project.list() | List all projects | Project[] |
+| project.current() | Get current project | Project |
+
+---
+
+```
+// List all projectsconst projects = await client.project.list()
+// Get current projectconst currentProject = await client.project.current()
+```
+
+---
+
+### Path
+
+| Method | Description | Response |
+|---|---|---|
+| path.get() | Get current path | Path |
+
+---
+
+```
+// Get current path informationconst pathInfo = await client.path.get()
+```
+
+---
+
+| Method | Description | Response |
+|---|---|---|
+| config.get() | Get config info | Config |
+| config.providers() | List providers and default models | { providers: Provider[], default: { [key: string]: string } } |
+
+---
+
+```
+const config = await client.config.get()
+const { providers, default: defaults } = await client.config.providers()
+```
+
+---
+
+### Sessions
+
+| Method | Description | Notes |
+|---|---|---|
+| session.list() | List sessions | Returns Session[] |
+| session.get({ path }) | Get session | Returns Session |
+| session.children({ path }) | List child sessions | Returns Session[] |
+| session.create({ body }) | Create session | Returns Session |
+| session.delete({ path }) | Delete session | Returns boolean |
+| session.update({ path, body }) | Update session properties | Returns Session |
+| session.init({ path, body }) | Analyze app and create AGENTS.md | Returns boolean |
+| session.abort({ path }) | Abort a running session | Returns boolean |
+| session.share({ path }) | Share session | Returns Session |
+| session.unshare({ path }) | Unshare session | Returns Session |
+| session.summarize({ path, body }) | Summarize session | Returns boolean |
+| session.messages({ path }) | List messages in a session | Returns { info: Message, parts: Part[]}[] |
+| session.message({ path }) | Get message details | Returns { info: Message, parts: Part[]} |
+| session.prompt({ path, body }) | Send prompt message | body.noReply: true returns UserMessage (context only). Default returns AssistantMessage with AI response. Supports body.outputFormat for structured output |
+| session.command({ path, body }) | Send command to session | Returns { info: AssistantMessage, parts: Part[]} |
+| session.shell({ path, body }) | Run a shell command | Returns AssistantMessage |
+| session.revert({ path, body }) | Revert a message | Returns Session |
+| session.unrevert({ path }) | Restore reverted messages | Returns Session |
+| postSessionByIdPermissionsByPermissionId({ path, body }) | Respond to a permission request | Returns boolean |
+
+---
+
+```
+// Create and manage sessionsconst session = await client.session.create({  body: { title: "My session" },})
+const sessions = await client.session.list()
+// Send a prompt messageconst result = await client.session.prompt({  path: { id: session.id },  body: {    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" },    parts: [{ type: "text", text: "Hello!" }],  },})
+// Inject context without triggering AI response (useful for plugins)await client.session.prompt({  path: { id: session.id },  body: {    noReply: true,    parts: [{ type: "text", text: "You are a helpful assistant." }],  },})
+```
+
+---
+
+### Files
+
+| Method | Description | Response |
+|---|---|---|
+| find.text({ query }) | Search for text in files | Array of match objects with path, lines, line_number, absolute_offset, submatches |
+| find.files({ query }) | Find files and directories by name | string[] (paths) |
+| find.symbols({ query }) | Find workspace symbols | Symbol[] |
+| file.read({ query }) | Read a file | { type: "raw" | "patch", content: string } |
+| file.status({ query? }) | Get status for tracked files | File[] |
+
+find.files supports a few optional query fields:
+
+- type: "file" or "directory"
+- directory: override the project root for the search
+- limit: max results (1–200)
+
+---
+
+```
+// Search and read filesconst textResults = await client.find.text({  query: { pattern: "function.*opencode" },})
+const files = await client.find.files({  query: { query: "*.ts", type: "file" },})
+const directories = await client.find.files({  query: { query: "packages", type: "directory", limit: 20 },})
+const content = await client.file.read({  query: { path: "src/index.ts" },})
+```
+
+---
+
+### TUI
+
+| Method | Description | Response |
+|---|---|---|
+| tui.appendPrompt({ body }) | Append text to the prompt | boolean |
+| tui.openHelp() | Open the help dialog | boolean |
+| tui.openSessions() | Open the session selector | boolean |
+| tui.openThemes() | Open the theme selector | boolean |
+| tui.openModels() | Open the model selector | boolean |
+| tui.submitPrompt() | Submit the current prompt | boolean |
+| tui.clearPrompt() | Clear the prompt | boolean |
+| tui.executeCommand({ body }) | Execute a command | boolean |
+| tui.showToast({ body }) | Show toast notification | boolean |
+
+---
+
+```
+// Control TUI interfaceawait client.tui.appendPrompt({  body: { text: "Add this to prompt" },})
+await client.tui.showToast({  body: { message: "Task completed", variant: "success" },})
+```
+
+---
+
+### Auth
+
+| Method | Description | Response |
+|---|---|---|
+| auth.set({ ... }) | Set authentication credentials | boolean |
+
+---
+
+```
+await client.auth.set({  path: { id: "anthropic" },  body: { type: "api", key: "your-api-key" },})
+```
+
+---
+
+### Events
+
+| Method | Description | Response |
+|---|---|---|
+| event.subscribe() | Server-sent events stream | Server-sent events stream |
+
+---
+
+```
+// Listen to real-time eventsconst events = await client.event.subscribe()for await (const event of events.stream) {  console.log("Event:", event.type, event.properties)}
+```

homelab/raw/articles/opencode/docs/server.md

@@ -0,0 +1,283 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/server/
+scraped: 2026-04-28T21:02:07.364049+00:00
+content_hash: b341586d
+---
+# Server
+
+Interact with opencode server over HTTP.
+
+The opencode serve command runs a headless HTTP server that exposes an OpenAPI endpoint that an opencode client can use.
+
+---
+
+### Usage
+
+```
+opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]
+```
+
+#### 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 domain name for mDNS service | opencode.local |
+| --cors | Additional browser origins to allow | [] |
+
+--cors can be passed multiple times:
+
+```
+opencode serve --cors http://localhost:5173 --cors https://app.example.com
+```
+
+---
+
+### Authentication
+
+Set OPENCODE_SERVER_PASSWORD to protect the server with HTTP basic auth. The username defaults to opencode, or set OPENCODE_SERVER_USERNAME to override it. This applies to both opencode serve and opencode web.
+
+```
+OPENCODE_SERVER_PASSWORD=your-password opencode serve
+```
+
+---
+
+### How it works
+
+When you run opencode it starts a TUI and a server. Where the TUI is the client that talks to the server. The server exposes an OpenAPI 3.1 spec endpoint. This endpoint is also used to generate an SDK.
+
+This architecture lets opencode support multiple clients and allows you to interact with opencode programmatically.
+
+You can run opencode serve to start a standalone server. If you have the opencode TUI running, opencode serve will start a new server.
+
+---
+
+#### Connect to an existing server
+
+When you start the TUI it randomly assigns a port and hostname. You can instead pass in the --hostname and --port flags. Then use this to connect to its server.
+
+The /tui endpoint can be used to drive the TUI through the server. For example, you can prefill or run a prompt. This setup is used by the OpenCode IDE plugins.
+
+---
+
+## Spec
+
+The server publishes an OpenAPI 3.1 spec that can be viewed at:
+
+```
+http://<hostname>:<port>/doc
+```
+
+For example, http://localhost:4096/doc. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer.
+
+---
+
+## APIs
+
+The opencode server exposes the following APIs.
+
+---
+
+### Global
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| GET | /global/health | Get server health and version | { healthy: true, version: string } |
+| GET | /global/event | Get global events (SSE stream) | Event stream |
+
+---
+
+### Project
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| GET | /project | List all projects | Project[] |
+| GET | /project/current | Get the current project | Project |
+
+---
+
+### Path & VCS
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| GET | /path | Get the current path | Path |
+| GET | /vcs | Get VCS info for the current project | VcsInfo |
+
+---
+
+### Instance
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| POST | /instance/dispose | Dispose the current instance | boolean |
+
+---
+
+### Config
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| GET | /config | Get config info | Config |
+| PATCH | /config | Update config | Config |
+| GET | /config/providers | List providers and default models | { providers: Provider[], default: { [key: string]: string } } |
+
+---
+
+### Provider
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| GET | /provider | List all providers | { all: Provider[], default: {...}, connected: string[] } |
+| GET | /provider/auth | Get provider authentication methods | { [providerID: string]: ProviderAuthMethod[] } |
+| POST | /provider/{id}/oauth/authorize | Authorize a provider using OAuth | ProviderAuthAuthorization |
+| POST | /provider/{id}/oauth/callback | Handle OAuth callback for a provider | boolean |
+
+---
+
+### Sessions
+
+| Method | Path | Description | Notes |
+|---|---|---|---|
+| GET | /session | List all sessions | Returns Session[] |
+| POST | /session | Create a new session | body: { parentID?, title? }, returns Session |
+| GET | /session/status | Get session status for all sessions | Returns { [sessionID: string]: SessionStatus } |
+| GET | /session/:id | Get session details | Returns Session |
+| DELETE | /session/:id | Delete a session and all its data | Returns boolean |
+| PATCH | /session/:id | Update session properties | body: { title? }, returns Session |
+| GET | /session/:id/children | Get a session’s child sessions | Returns Session[] |
+| GET | /session/:id/todo | Get the todo list for a session | Returns Todo[] |
+| POST | /session/:id/init | Analyze app and create AGENTS.md | body: { messageID, providerID, modelID }, returns boolean |
+| POST | /session/:id/fork | Fork an existing session at a message | body: { messageID? }, returns Session |
+| POST | /session/:id/abort | Abort a running session | Returns boolean |
+| POST | /session/:id/share | Share a session | Returns Session |
+| DELETE | /session/:id/share | Unshare a session | Returns Session |
+| GET | /session/:id/diff | Get the diff for this session | query: messageID?, returns FileDiff[] |
+| POST | /session/:id/summarize | Summarize the session | body: { providerID, modelID }, returns boolean |
+| POST | /session/:id/revert | Revert a message | body: { messageID, partID? }, returns boolean |
+| POST | /session/:id/unrevert | Restore all reverted messages | Returns boolean |
+| POST | /session/:id/permissions/:permissionID | Respond to a permission request | body: { response, remember? }, returns boolean |
+
+---
+
+### Messages
+
+| Method | Path | Description | Notes |
+|---|---|---|---|
+| GET | /session/:id/message | List messages in a session | query: limit?, returns { info: Message, parts: Part[]}[] |
+| POST | /session/:id/message | Send a message and wait for response | body: { messageID?, model?, agent?, noReply?, system?, tools?, parts }, returns { info: Message, parts: Part[]} |
+| GET | /session/:id/message/:messageID | Get message details | Returns { info: Message, parts: Part[]} |
+| POST | /session/:id/prompt_async | Send a message asynchronously (no wait) | body: same as /session/:id/message, returns 204 No Content |
+| POST | /session/:id/command | Execute a slash command | body: { messageID?, agent?, model?, command, arguments }, returns { info: Message, parts: Part[]} |
+| POST | /session/:id/shell | Run a shell command | body: { agent, model?, command }, returns { info: Message, parts: Part[]} |
+
+---
+
+### Commands
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| GET | /command | List all commands | Command[] |
+
+---
+
+### Files
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| GET | /find?pattern=<pat> | Search for text in files | Array of match objects with path, lines, line_number, absolute_offset, submatches |
+| GET | /find/file?query=<q> | Find files and directories by name | string[] (paths) |
+| GET | /find/symbol?query=<q> | Find workspace symbols | Symbol[] |
+| GET | /file?path=<path> | List files and directories | FileNode[] |
+| GET | /file/content?path=<p> | Read a file | FileContent |
+| GET | /file/status | Get status for tracked files | File[] |
+
+#### /find/file query parameters
+
+- query (required) — search string (fuzzy match)
+- type (optional) — limit results to "file" or "directory"
+- directory (optional) — override the project root for the search
+- limit (optional) — max results (1–200)
+- dirs (optional) — legacy flag ("false" returns only files)
+
+---
+
+### Tools (Experimental)
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| GET | /experimental/tool/ids | List all tool IDs | ToolIDs |
+| GET | /experimental/tool?provider=<p>&model=<m> | List tools with JSON schemas for a model | ToolList |
+
+---
+
+### LSP, Formatters & MCP
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| GET | /lsp | Get LSP server status | LSPStatus[] |
+| GET | /formatter | Get formatter status | FormatterStatus[] |
+| GET | /mcp | Get MCP server status | { [name: string]: MCPStatus } |
+| POST | /mcp | Add MCP server dynamically | body: { name, config }, returns MCP status object |
+
+---
+
+### Agents
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| GET | /agent | List all available agents | Agent[] |
+
+---
+
+### Logging
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| POST | /log | Write log entry. Body: { service, level, message, extra? } | boolean |
+
+---
+
+### TUI
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| POST | /tui/append-prompt | Append text to the prompt | boolean |
+| POST | /tui/open-help | Open the help dialog | boolean |
+| POST | /tui/open-sessions | Open the session selector | boolean |
+| POST | /tui/open-themes | Open the theme selector | boolean |
+| POST | /tui/open-models | Open the model selector | boolean |
+| POST | /tui/submit-prompt | Submit the current prompt | boolean |
+| POST | /tui/clear-prompt | Clear the prompt | boolean |
+| POST | /tui/execute-command | Execute a command ({ command }) | boolean |
+| POST | /tui/show-toast | Show toast ({ title?, message, variant }) | boolean |
+| GET | /tui/control/next | Wait for the next control request | Control request object |
+| POST | /tui/control/response | Respond to a control request ({ body }) | boolean |
+
+---
+
+### Auth
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| PUT | /auth/:id | Set authentication credentials. Body must match provider schema | boolean |
+
+---
+
+### Events
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| GET | /event | Server-sent events stream. First event is server.connected, then bus events | Server-sent events stream |
+
+---
+
+### Docs
+
+| Method | Path | Description | Response |
+|---|---|---|---|
+| GET | /doc | OpenAPI 3.1 specification | HTML page with OpenAPI spec |

homelab/raw/articles/opencode/docs/share.md

@@ -0,0 +1,120 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/share/
+scraped: 2026-04-28T21:02:13.851786+00:00
+content_hash: 51d04546
+---
+# Share
+
+Share your OpenCode conversations.
+
+OpenCode’s share feature allows you to create public links to your OpenCode conversations, so you can collaborate with teammates or get help from others.
+
+---
+
+## How it works
+
+When you share a conversation, OpenCode:
+
+1. Creates a unique public URL for your session
+2. Syncs your conversation history to our servers
+3. Makes the conversation accessible via the shareable link — opncd.ai/s/<share-id>
+
+---
+
+## Sharing
+
+OpenCode supports three sharing modes that control how conversations are shared:
+
+---
+
+### Manual (default)
+
+By default, OpenCode uses manual sharing mode. Sessions are not shared automatically, but you can manually share them using the /share command:
+
+```
+/share
+```
+
+This will generate a unique URL that’ll be copied to your clipboard.
+
+To explicitly set manual mode in your config file:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "share": "manual"}
+```
+
+---
+
+### Auto-share
+
+You can enable automatic sharing for all new conversations by setting the share option to "auto" in your config file:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "share": "auto"}
+```
+
+With auto-share enabled, every new conversation will automatically be shared and a link will be generated.
+
+---
+
+### Disabled
+
+You can disable sharing entirely by setting the share option to "disabled" in your config file:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "share": "disabled"}
+```
+
+To enforce this across your team for a given project, add it to the opencode.json in your project and check into Git.
+
+---
+
+## Un-sharing
+
+To stop sharing a conversation and remove it from public access:
+
+```
+/unshare
+```
+
+This will remove the share link and delete the data related to the conversation.
+
+---
+
+## Privacy
+
+There are a few things to keep in mind when sharing a conversation.
+
+---
+
+### Data retention
+
+Shared conversations remain accessible until you explicitly unshare them. This includes:
+
+- Full conversation history
+- All messages and responses
+- Session metadata
+
+---
+
+### Recommendations
+
+- Only share conversations that don’t contain sensitive information.
+- Review conversation content before sharing.
+- Unshare conversations when collaboration is complete.
+- Avoid sharing conversations with proprietary code or confidential data.
+- For sensitive projects, disable sharing entirely.
+
+---
+
+## For enterprises
+
+For enterprise deployments, the share feature can be:
+
+- Disabled entirely for security compliance
+- Restricted to users authenticated through SSO only
+- Self-hosted on your own infrastructure
+
+Learn more about using opencode in your organization.

homelab/raw/articles/opencode/docs/skills.md

@@ -0,0 +1,167 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/skills/
+scraped: 2026-04-28T21:02:06.096255+00:00
+content_hash: d4968081
+---
+# Agent Skills
+
+Define reusable behavior via SKILL.md definitions
+
+Agent skills let OpenCode discover reusable instructions from your repo or home directory. Skills are loaded on-demand via the native skill tool—agents see available skills and can load the full content when needed.
+
+---
+
+## Place files
+
+Create one folder per skill name and put a SKILL.md inside it. OpenCode searches these locations:
+
+- Project config: .opencode/skills/<name>/SKILL.md
+- Global config: ~/.config/opencode/skills/<name>/SKILL.md
+
+- Project agent-compatible: .agents/skills/<name>/SKILL.md
+- Global agent-compatible: ~/.agents/skills/<name>/SKILL.md
+
+---
+
+## Understand discovery
+
+For project-local paths, OpenCode walks up from your current working directory until it reaches the git worktree. It loads any matching skills/*/SKILL.md in .opencode/ and any matching .agents/skills/*/SKILL.md along the way.
+
+Global definitions are also loaded from ~/.config/opencode/skills/*/SKILL.md and ~/.agents/skills/*/SKILL.md.
+
+---
+
+## Write frontmatter
+
+Each SKILL.md must start with YAML frontmatter. Only these fields are recognized:
+
+- name (required)
+- description (required)
+- license (optional)
+- compatibility (optional)
+- metadata (optional, string-to-string map)
+
+Unknown frontmatter fields are ignored.
+
+---
+
+## Validate names
+
+name must:
+
+- Be 1–64 characters
+- Be lowercase alphanumeric with single hyphen separators
+- Not start or end with -
+- Not contain consecutive --
+- Match the directory name that contains SKILL.md
+
+Equivalent regex:
+
+```
+^[a-z0-9]+(-[a-z0-9]+)*$
+```
+
+---
+
+## Follow length rules
+
+description must be 1-1024 characters. Keep it specific enough for the agent to choose correctly.
+
+---
+
+## Use an example
+
+Create .opencode/skills/git-release/SKILL.md like this:
+
+```
+---name: git-releasedescription: Create consistent releases and changelogslicense: MITcompatibility: opencodemetadata:  audience: maintainers  workflow: github---
+## What I do
+- Draft release notes from merged PRs- Propose a version bump- Provide a copy-pasteable `gh release create` command
+## When to use me
+Use this when you are preparing a tagged release.Ask clarifying questions if the target versioning scheme is unclear.
+```
+
+---
+
+## Recognize tool description
+
+OpenCode lists available skills in the skill tool description. Each entry includes the skill name and description:
+
+```
+<available_skills>  <skill>    <name>git-release</name>    <description>Create consistent releases and changelogs</description>  </skill></available_skills>
+```
+
+The agent loads a skill by calling the tool:
+
+```
+skill({ name: "git-release" })
+```
+
+---
+
+## Configure permissions
+
+Control which skills agents can access using pattern-based permissions in opencode.json:
+
+```
+{  "permission": {    "skill": {      "*": "allow",      "pr-review": "allow",      "internal-*": "deny",      "experimental-*": "ask"    }  }}
+```
+
+| Permission | Behavior |
+|---|---|
+| allow | Skill loads immediately |
+| deny | Skill hidden from agent, access rejected |
+| ask | User prompted for approval before loading |
+
+Patterns support wildcards: internal-* matches internal-docs, internal-tools, etc.
+
+---
+
+## Override per agent
+
+Give specific agents different permissions than the global defaults.
+
+For custom agents (in agent frontmatter):
+
+```
+---permission:  skill:    "documents-*": "allow"---
+```
+
+For built-in agents (in opencode.json):
+
+```
+{  "agent": {    "plan": {      "permission": {        "skill": {          "internal-*": "allow"        }      }    }  }}
+```
+
+---
+
+## Disable the skill tool
+
+Completely disable skills for agents that shouldn’t use them:
+
+For custom agents:
+
+```
+---tools:  skill: false---
+```
+
+For built-in agents:
+
+```
+{  "agent": {    "plan": {      "tools": {        "skill": false      }    }  }}
+```
+
+When disabled, the <available_skills> section is omitted entirely.
+
+---
+
+## Troubleshoot loading
+
+If a skill does not show up:
+
+1. Verify SKILL.md is spelled in all caps
+2. Check that frontmatter includes name and description
+3. Ensure skill names are unique across all locations
+4. Check permissions—skills with deny are hidden from agents

homelab/raw/articles/opencode/docs/themes.md

@@ -0,0 +1,148 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/themes/
+scraped: 2026-04-28T21:02:11.770527+00:00
+content_hash: 8133ac2c
+---
+# Themes
+
+Select a built-in theme or define your own.
+
+With OpenCode you can select from one of several built-in themes, use a theme that adapts to your terminal theme, or define your own custom theme.
+
+By default, OpenCode uses our own opencode theme.
+
+---
+
+## Terminal requirements
+
+For themes to display correctly with their full color palette, your terminal must support truecolor (24-bit color). Most modern terminals support this by default, but you may need to enable it:
+
+- Check support: Run echo $COLORTERM - it should output truecolor or 24bit
+- Enable truecolor: Set the environment variable COLORTERM=truecolor in your shell profile
+- Terminal compatibility: Ensure your terminal emulator supports 24-bit color (most modern terminals like iTerm2, Alacritty, Kitty, Windows Terminal, and recent versions of GNOME Terminal do)
+
+Without truecolor support, themes may appear with reduced color accuracy or fall back to the nearest 256-color approximation.
+
+---
+
+## Built-in themes
+
+OpenCode comes with several built-in themes.
+
+| Name | Description |
+|---|---|
+| system | Adapts to your terminal’s background color |
+| tokyonight | Based on the Tokyonight theme |
+| everforest | Based on the Everforest theme |
+| ayu | Based on the Ayu dark theme |
+| catppuccin | Based on the Catppuccin theme |
+| catppuccin-macchiato | Based on the Catppuccin theme |
+| gruvbox | Based on the Gruvbox theme |
+| kanagawa | Based on the Kanagawa theme |
+| nord | Based on the Nord theme |
+| matrix | Hacker-style green on black theme |
+| one-dark | Based on the Atom One Dark theme |
+
+And more, we are constantly adding new themes.
+
+---
+
+## System theme
+
+The system theme is designed to automatically adapt to your terminal’s color scheme. Unlike traditional themes that use fixed colors, the system theme:
+
+- Generates gray scale: Creates a custom gray scale based on your terminal’s background color, ensuring optimal contrast.
+- Uses ANSI colors: Leverages standard ANSI colors (0-15) for syntax highlighting and UI elements, which respect your terminal’s color palette.
+- Preserves terminal defaults: Uses none for text and background colors to maintain your terminal’s native appearance.
+
+The system theme is for users who:
+
+- Want OpenCode to match their terminal’s appearance
+- Use custom terminal color schemes
+- Prefer a consistent look across all terminal applications
+
+---
+
+## Using a theme
+
+You can select a theme by bringing up the theme select with the /theme command. Or you can specify it in tui.json.
+
+```
+{  "$schema": "https://opencode.ai/tui.json",  "theme": "tokyonight"}
+```
+
+---
+
+## Custom themes
+
+OpenCode supports a flexible JSON-based theme system that allows users to create and customize themes easily.
+
+---
+
+### Hierarchy
+
+Themes are loaded from multiple directories in the following order where later directories override earlier ones:
+
+1. Built-in themes - These are embedded in the binary
+2. User config directory - Defined in ~/.config/opencode/themes/*.json or $XDG_CONFIG_HOME/opencode/themes/*.json
+3. Project root directory - Defined in the <project-root>/.opencode/themes/*.json
+4. Current working directory - Defined in ./.opencode/themes/*.json
+
+If multiple directories contain a theme with the same name, the theme from the directory with higher priority will be used.
+
+---
+
+### Creating a theme
+
+To create a custom theme, create a JSON file in one of the theme directories.
+
+For user-wide themes:
+
+```
+mkdir -p ~/.config/opencode/themesvim ~/.config/opencode/themes/my-theme.json
+```
+
+And for project-specific themes.
+
+```
+mkdir -p .opencode/themesvim .opencode/themes/my-theme.json
+```
+
+---
+
+### JSON format
+
+Themes use a flexible JSON format with support for:
+
+- Hex colors: "#ffffff"
+- ANSI colors: 3 (0-255)
+- Color references: "primary" or custom definitions
+- Dark/light variants: {"dark": "#000", "light": "#fff"}
+- No color: "none" - Uses the terminal’s default color or transparent
+
+---
+
+### Color definitions
+
+The defs section is optional and it allows you to define reusable colors that can be referenced in the theme.
+
+---
+
+### Terminal defaults
+
+The special value "none" can be used for any color to inherit the terminal’s default color. This is particularly useful for creating themes that blend seamlessly with your terminal’s color scheme:
+
+- "text": "none" - Uses terminal’s default foreground color
+- "background": "none" - Uses terminal’s default background color
+
+---
+
+### Example
+
+Here’s an example of a custom theme:
+
+```
+{  "$schema": "https://opencode.ai/theme.json",  "defs": {    "nord0": "#2E3440",    "nord1": "#3B4252",    "nord2": "#434C5E",    "nord3": "#4C566A",    "nord4": "#D8DEE9",    "nord5": "#E5E9F0",    "nord6": "#ECEFF4",    "nord7": "#8FBCBB",    "nord8": "#88C0D0",    "nord9": "#81A1C1",    "nord10": "#5E81AC",    "nord11": "#BF616A",    "nord12": "#D08770",    "nord13": "#EBCB8B",    "nord14": "#A3BE8C",    "nord15": "#B48EAD"  },  "theme": {    "primary": {      "dark": "nord8",      "light": "nord10"    },    "secondary": {      "dark": "nord9",      "light": "nord9"    },    "accent": {      "dark": "nord7",      "light": "nord7"    },    "error": {      "dark": "nord11",      "light": "nord11"    },    "warning": {      "dark": "nord12",      "light": "nord12"    },    "success": {      "dark": "nord14",      "light": "nord14"    },    "info": {      "dark": "nord8",      "light": "nord10"    },    "text": {      "dark": "nord4",      "light": "nord0"    },    "textMuted": {      "dark": "nord3",      "light": "nord1"    },    "background": {      "dark": "nord0",      "light": "nord6"    },    "backgroundPanel": {      "dark": "nord1",      "light": "nord5"    },    "backgroundElement": {      "dark": "nord1",      "light": "nord4"    },    "border": {      "dark": "nord2",      "light": "nord3"    },    "borderActive": {      "dark": "nord3",      "light": "nord2"    },    "borderSubtle": {      "dark": "nord2",      "light": "nord3"    },    "diffAdded": {      "dark": "nord14",      "light": "nord14"    },    "diffRemoved": {      "dark": "nord11",      "light": "nord11"    },    "diffContext": {      "dark": "nord3",      "light": "nord3"    },    "diffHunkHeader": {      "dark": "nord3",      "light": "nord3"    },    "diffHighlightAdded": {      "dark": "nord14",      "light": "nord14"    },    "diffHighlightRemoved": {      "dark": "nord11",      "light": "nord11"    },    "diffAddedBg": {      "dark": "#3B4252",      "light": "#E5E9F0"    },    "diffRemovedBg": {      "dark": "#3B4252",      "light": "#E5E9F0"    },    "diffContextBg": {      "dark": "nord1",      "light": "nord5"    },    "diffLineNumber": {      "dark": "nord2",      "light": "nord4"    },    "diffAddedLineNumberBg": {      "dark": "#3B4252",      "light": "#E5E9F0"    },    "diffRemovedLineNumberBg": {      "dark": "#3B4252",      "light": "#E5E9F0"    },    "markdownText": {      "dark": "nord4",      "light": "nord0"    },    "markdownHeading": {      "dark": "nord8",      "light": "nord10"    },    "markdownLink": {      "dark": "nord9",      "light": "nord9"    },    "markdownLinkText": {      "dark": "nord7",      "light": "nord7"    },    "markdownCode": {      "dark": "nord14",      "light": "nord14"    },    "markdownBlockQuote": {      "dark": "nord3",      "light": "nord3"    },    "markdownEmph": {      "dark": "nord12",      "light": "nord12"    },    "markdownStrong": {      "dark": "nord13",      "light": "nord13"    },    "markdownHorizontalRule": {      "dark": "nord3",      "light": "nord3"    },    "markdownListItem": {      "dark": "nord8",      "light": "nord10"    },    "markdownListEnumeration": {      "dark": "nord7",      "light": "nord7"    },    "markdownImage": {      "dark": "nord9",      "light": "nord9"    },    "markdownImageText": {      "dark": "nord7",      "light": "nord7"    },    "markdownCodeBlock": {      "dark": "nord4",      "light": "nord0"    },    "syntaxComment": {      "dark": "nord3",      "light": "nord3"    },    "syntaxKeyword": {      "dark": "nord9",      "light": "nord9"    },    "syntaxFunction": {      "dark": "nord8",      "light": "nord8"    },    "syntaxVariable": {      "dark": "nord7",      "light": "nord7"    },    "syntaxString": {      "dark": "nord14",      "light": "nord14"    },    "syntaxNumber": {      "dark": "nord15",      "light": "nord15"    },    "syntaxType": {      "dark": "nord7",      "light": "nord7"    },    "syntaxOperator": {      "dark": "nord9",      "light": "nord9"    },    "syntaxPunctuation": {      "dark": "nord4",      "light": "nord0"    }  }}
+```

homelab/raw/articles/opencode/docs/tools.md

@@ -0,0 +1,241 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/tools/
+scraped: 2026-04-28T21:02:08.612134+00:00
+content_hash: 64e17edc
+---
+# Tools
+
+Manage the tools an LLM can use.
+
+Tools allow the LLM to perform actions in your codebase. OpenCode comes with a set of built-in tools, but you can extend it with custom tools or MCP servers.
+
+By default, all tools are enabled and don’t need permission to run. You can control tool behavior through permissions.
+
+---
+
+## Configure
+
+Use the permission field to control tool behavior. You can allow, deny, or require approval for each tool.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "edit": "deny",    "bash": "ask",    "webfetch": "allow"  }}
+```
+
+You can also use wildcards to control multiple tools at once. For example, to require approval for all tools from an MCP server:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "mymcp_*": "ask"  }}
+```
+
+Learn more about configuring permissions.
+
+---
+
+## Built-in
+
+Here are all the built-in tools available in OpenCode.
+
+---
+
+### bash
+
+Execute shell commands in your project environment.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "bash": "allow"  }}
+```
+
+This tool allows the LLM to run terminal commands like npm install, git status, or any other shell command.
+
+---
+
+### edit
+
+Modify existing files using exact string replacements.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "edit": "allow"  }}
+```
+
+This tool performs precise edits to files by replacing exact text matches. It’s the primary way the LLM modifies code.
+
+---
+
+### write
+
+Create new files or overwrite existing ones.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "edit": "allow"  }}
+```
+
+Use this to allow the LLM to create new files. It will overwrite existing files if they already exist.
+
+---
+
+### read
+
+Read file contents from your codebase.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "read": "allow"  }}
+```
+
+This tool reads files and returns their contents. It supports reading specific line ranges for large files.
+
+---
+
+### grep
+
+Search file contents using regular expressions.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "grep": "allow"  }}
+```
+
+Fast content search across your codebase. Supports full regex syntax and file pattern filtering.
+
+---
+
+### glob
+
+Find files by pattern matching.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "glob": "allow"  }}
+```
+
+Search for files using glob patterns like **/*.js or src/**/*.ts. Returns matching file paths sorted by modification time.
+
+---
+
+### lsp (experimental)
+
+Interact with your configured LSP servers to get code intelligence features like definitions, references, hover info, and call hierarchy.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "lsp": "allow"  }}
+```
+
+Supported operations include goToDefinition, findReferences, hover, documentSymbol, workspaceSymbol, goToImplementation, prepareCallHierarchy, incomingCalls, and outgoingCalls.
+
+To configure which LSP servers are available for your project, see LSP Servers.
+
+---
+
+### apply_patch
+
+Apply patches to files.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "edit": "allow"  }}
+```
+
+This tool applies patch files to your codebase. Useful for applying diffs and patches from various sources.
+
+When handling tool.execute.before or tool.execute.after hooks, check input.tool === "apply_patch" (not "patch").
+
+apply_patch uses output.args.patchText instead of output.args.filePath. Paths are embedded in marker lines within patchText and are relative to the project root (for example: *** Add File: src/new-file.ts, *** Update File: src/existing.ts, *** Move to: src/renamed.ts, *** Delete File: src/obsolete.ts).
+
+---
+
+### skill
+
+Load a skill (a SKILL.md file) and return its content in the conversation.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "skill": "allow"  }}
+```
+
+---
+
+### todowrite
+
+Manage todo lists during coding sessions.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "todowrite": "allow"  }}
+```
+
+Creates and updates task lists to track progress during complex operations. The LLM uses this to organize multi-step tasks.
+
+---
+
+### webfetch
+
+Fetch web content.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "webfetch": "allow"  }}
+```
+
+Allows the LLM to fetch and read web pages. Useful for looking up documentation or researching online resources.
+
+---
+
+### websearch
+
+Search the web for information.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "websearch": "allow"  }}
+```
+
+Performs web searches using Exa AI to find relevant information online. Useful for researching topics, finding current events, or gathering information beyond the training data cutoff.
+
+No API key is required — the tool connects directly to Exa AI’s hosted MCP service without authentication.
+
+---
+
+### question
+
+Ask the user questions during execution.
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "permission": {    "question": "allow"  }}
+```
+
+This tool allows the LLM to ask the user questions during a task. It’s useful for:
+
+- Gathering user preferences or requirements
+- Clarifying ambiguous instructions
+- Getting decisions on implementation choices
+- Offering choices about what direction to take
+
+Each question includes a header, the question text, and a list of options. Users can select from the provided options or type a custom answer. When there are multiple questions, users can navigate between them before submitting all answers.
+
+---
+
+## Custom tools
+
+Custom tools let you define your own functions that the LLM can call. These are defined in your config file and can execute arbitrary code.
+
+Learn more about creating custom tools.
+
+---
+
+## MCP servers
+
+MCP (Model Context Protocol) servers allow you to integrate external tools and services. This includes database access, API integrations, and third-party services.
+
+Learn more about configuring MCP servers.
+
+---
+
+## Internals
+
+Internally, tools like grep and glob use ripgrep under the hood. By default, ripgrep respects .gitignore patterns, which means files and directories listed in your .gitignore will be excluded from searches and listings.
+
+---
+
+### Ignore patterns
+
+To include files that would normally be ignored, create a .ignore file in your project root. This file can explicitly allow certain paths.
+
+```
+!node_modules/!dist/!build/
+```
+
+For example, this .ignore file allows ripgrep to search within node_modules/, dist/, and build/ directories even if they’re listed in .gitignore.

homelab/raw/articles/opencode/docs/troubleshooting.md

@@ -0,0 +1,272 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/troubleshooting/
+scraped: 2026-04-28T21:02:13.425323+00:00
+content_hash: 424a7eef
+---
+# Troubleshooting
+
+Common issues and how to resolve them.
+
+To debug issues with OpenCode, start by checking the logs and local data it stores on disk.
+
+---
+
+## Logs
+
+Log files are written to:
+
+- macOS/Linux: ~/.local/share/opencode/log/
+- Windows: Press WIN+R and paste %USERPROFILE%\.local\share\opencode\log
+
+Log files are named with timestamps (e.g., 2025-01-09T123456.log) and the most recent 10 log files are kept.
+
+You can set the log level with the --log-level command-line option to get more detailed debug information. For example, opencode --log-level DEBUG.
+
+---
+
+## Storage
+
+opencode stores session data and other application data on disk at:
+
+- macOS/Linux: ~/.local/share/opencode/
+- Windows: Press WIN+R and paste %USERPROFILE%\.local\share\opencode
+
+This directory contains:
+
+- auth.json - Authentication data like API keys, OAuth tokens
+- log/ - Application logs
+- project/ - Project-specific data like session and message data If the project is within a Git repo, it is stored in ./<project-slug>/storage/ If it is not a Git repo, it is stored in ./global/storage/
+- If the project is within a Git repo, it is stored in ./<project-slug>/storage/
+- If it is not a Git repo, it is stored in ./global/storage/
+
+---
+
+## Desktop app
+
+OpenCode Desktop runs a local OpenCode server (the opencode-cli sidecar) in the background. Most issues are caused by a misbehaving plugin, a corrupted cache, or a bad server setting.
+
+### Quick checks
+
+- Fully quit and relaunch the app.
+- If the app shows an error screen, click Restart and copy the error details.
+- macOS only: OpenCode menu -> Reload Webview (helps if the UI is blank/frozen).
+
+---
+
+### Disable plugins
+
+If the desktop app is crashing on launch, hanging, or behaving strangely, start by disabling plugins.
+
+#### Check the global config
+
+Open your global config file and look for a plugin key.
+
+- macOS/Linux: ~/.config/opencode/opencode.jsonc (or ~/.config/opencode/opencode.json)
+- macOS/Linux (older installs): ~/.local/share/opencode/opencode.jsonc
+- Windows: Press WIN+R and paste %USERPROFILE%\.config\opencode\opencode.jsonc
+
+If you have plugins configured, temporarily disable them by removing the key or setting it to an empty array:
+
+```
+{  "$schema": "https://opencode.ai/config.json",  "plugin": [],}
+```
+
+#### Check plugin directories
+
+OpenCode can also load local plugins from disk. Temporarily move these out of the way (or rename the folder) and restart the desktop app:
+
+- Global plugins macOS/Linux: ~/.config/opencode/plugins/ Windows: Press WIN+R and paste %USERPROFILE%\.config\opencode\plugins
+- macOS/Linux: ~/.config/opencode/plugins/
+- Windows: Press WIN+R and paste %USERPROFILE%\.config\opencode\plugins
+
+- Project plugins (only if you use per-project config) <your-project>/.opencode/plugins/
+- <your-project>/.opencode/plugins/
+
+If the app starts working again, re-enable plugins one at a time to find which one is causing the issue.
+
+---
+
+### Clear the cache
+
+If disabling plugins doesn’t help (or a plugin install is stuck), clear the cache so OpenCode can rebuild it.
+
+1. Quit OpenCode Desktop completely.
+2. Delete the cache directory:
+
+- macOS: Finder -> Cmd+Shift+G -> paste ~/.cache/opencode
+- Linux: delete ~/.cache/opencode (or run rm -rf ~/.cache/opencode)
+- Windows: Press WIN+R and paste %USERPROFILE%\.cache\opencode
+
+1. Restart OpenCode Desktop.
+
+---
+
+### Fix server connection issues
+
+OpenCode Desktop can either start its own local server (default) or connect to a server URL you configured.
+
+If you see a “Connection Failed” dialog (or the app never gets past the splash screen), check for a custom server URL.
+
+#### Clear the desktop default server URL
+
+From the Home screen, click the server name (with the status dot) to open the Server picker. In the Default server section, click Clear.
+
+#### Remove server.port / server.hostname from your config
+
+If your opencode.json(c) contains a server section, temporarily remove it and restart the desktop app.
+
+#### Check environment variables
+
+If you have OPENCODE_PORT set in your environment, the desktop app will try to use that port for the local server.
+
+- Unset OPENCODE_PORT (or pick a free port) and restart.
+
+---
+
+### Linux: Wayland / X11 issues
+
+On Linux, some Wayland setups can cause blank windows or compositor errors.
+
+- If you’re on Wayland and the app is blank/crashing, try launching with OC_ALLOW_WAYLAND=1.
+- If that makes things worse, remove it and try launching under an X11 session instead.
+
+---
+
+### Windows: WebView2 runtime
+
+On Windows, OpenCode Desktop requires the Microsoft Edge WebView2 Runtime. If the app opens to a blank window or won’t start, install/update WebView2 and try again.
+
+---
+
+### Windows: General performance issues
+
+If you’re experiencing slow performance, file access issues, or terminal problems on Windows, try using WSL (Windows Subsystem for Linux). WSL provides a Linux environment that works more seamlessly with OpenCode’s features.
+
+---
+
+### Notifications not showing
+
+OpenCode Desktop only shows system notifications when:
+
+- notifications are enabled for OpenCode in your OS settings, and
+- the app window is not focused.
+
+---
+
+### Reset desktop app storage (last resort)
+
+If the app won’t start and you can’t clear settings from inside the UI, reset the desktop app’s saved state.
+
+1. Quit OpenCode Desktop.
+2. Find and delete these files (they live in the OpenCode Desktop app data directory):
+
+- opencode.settings.dat (desktop default server URL)
+- opencode.global.dat and opencode.workspace.*.dat (UI state like recent servers/projects)
+
+To find the directory quickly:
+
+- macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (then search for the filenames above)
+- Linux: search under ~/.local/share for the filenames above
+- Windows: Press WIN+R -> %APPDATA% (then search for the filenames above)
+
+---
+
+## Getting help
+
+If you’re experiencing issues with OpenCode:
+
+1. Report issues on GitHub The best way to report bugs or request features is through our GitHub repository: github.com/anomalyco/opencode/issues Before creating a new issue, search existing issues to see if your problem has already been reported.
+2. Join our Discord For real-time help and community discussion, join our Discord server: opencode.ai/discord
+
+---
+
+## Common issues
+
+Here are some common issues and how to resolve them.
+
+---
+
+### OpenCode won’t start
+
+1. Check the logs for error messages
+2. Try running with --print-logs to see output in the terminal
+3. Ensure you have the latest version with opencode upgrade
+
+---
+
+### Authentication issues
+
+1. Try re-authenticating with the /connect command in the TUI
+2. Check that your API keys are valid
+3. Ensure your network allows connections to the provider’s API
+
+---
+
+### Model not available
+
+1. Check that you’ve authenticated with the provider
+2. Verify the model name in your config is correct
+3. Some models may require specific access or subscriptions
+
+If you encounter ProviderModelNotFoundError you are most likely incorrectly referencing a model somewhere. Models should be referenced like so: <providerId>/<modelId>
+
+Examples:
+
+- openai/gpt-4.1
+- openrouter/google/gemini-2.5-flash
+- opencode/kimi-k2
+
+To figure out what models you have access to, run opencode models
+
+---
+
+### ProviderInitError
+
+If you encounter a ProviderInitError, you likely have an invalid or corrupted configuration.
+
+To resolve this:
+
+1. First, verify your provider is set up correctly by following the providers guide
+2. If the issue persists, try clearing your stored configuration: Terminal windowrm -rf ~/.local/share/opencode On Windows, press WIN+R and delete: %USERPROFILE%\.local\share\opencode
+3. Re-authenticate with your provider using the /connect command in the TUI.
+
+---
+
+### AI_APICallError and provider package issues
+
+If you encounter API call errors, this may be due to outdated provider packages. opencode dynamically installs provider packages (OpenAI, Anthropic, Google, etc.) as needed and caches them locally.
+
+To resolve provider package issues:
+
+1. Clear the provider package cache: Terminal windowrm -rf ~/.cache/opencode On Windows, press WIN+R and delete: %USERPROFILE%\.cache\opencode
+2. Restart opencode to reinstall the latest provider packages
+
+This will force opencode to download the most recent versions of provider packages, which often resolves compatibility issues with model parameters and API changes.
+
+---
+
+### Copy/paste not working on Linux
+
+Linux users need to have one of the following clipboard utilities installed for copy/paste functionality to work:
+
+For X11 systems:
+
+```
+apt install -y xclip# orapt install -y xsel
+```
+
+For Wayland systems:
+
+```
+apt install -y wl-clipboard
+```
+
+For headless environments:
+
+```
+apt install -y xvfb# and run:Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &export DISPLAY=:99.0
+```
+
+opencode will detect if you’re using Wayland and prefer wl-clipboard, otherwise it will try to find clipboard tools in order of: xclip and xsel.

homelab/raw/articles/opencode/docs/tui.md

@@ -0,0 +1,338 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/tui/
+scraped: 2026-04-28T21:02:07.042364+00:00
+content_hash: 8275383c
+---
+# TUI
+
+Using the OpenCode terminal user interface.
+
+OpenCode provides an interactive terminal interface or TUI for working on your projects with an LLM.
+
+Running OpenCode starts the TUI for the current directory.
+
+```
+opencode
+```
+
+Or you can start it for a specific working directory.
+
+```
+opencode /path/to/project
+```
+
+Once you’re in the TUI, you can prompt it with a message.
+
+```
+Give me a quick summary of the codebase.
+```
+
+---
+
+## File references
+
+You can reference files in your messages using @. This does a fuzzy file search in the current working directory.
+
+```
+How is auth handled in @packages/functions/src/api/index.ts?
+```
+
+The content of the file is added to the conversation automatically.
+
+---
+
+## Bash commands
+
+Start a message with ! to run a shell command.
+
+```
+!ls -la
+```
+
+The output of the command is added to the conversation as a tool result.
+
+---
+
+## Commands
+
+When using the OpenCode TUI, you can type / followed by a command name to quickly execute actions. For example:
+
+```
+/help
+```
+
+Most commands also have keybind using ctrl+x as the leader key, where ctrl+x is the default leader key. Learn more.
+
+Here are all available slash commands:
+
+---
+
+### connect
+
+Add a provider to OpenCode. Allows you to select from available providers and add their API keys.
+
+```
+/connect
+```
+
+---
+
+### compact
+
+Compact the current session. Alias: /summarize
+
+```
+/compact
+```
+
+Keybind: ctrl+x c
+
+---
+
+### details
+
+Toggle tool execution details.
+
+```
+/details
+```
+
+Keybind: ctrl+x d
+
+---
+
+### editor
+
+Open external editor for composing messages. Uses the editor set in your EDITOR environment variable. Learn more.
+
+```
+/editor
+```
+
+Keybind: ctrl+x e
+
+---
+
+### exit
+
+Exit OpenCode. Aliases: /quit, /q
+
+```
+/exit
+```
+
+Keybind: ctrl+x q
+
+---
+
+### export
+
+Export current conversation to Markdown and open in your default editor. Uses the editor set in your EDITOR environment variable. Learn more.
+
+```
+/export
+```
+
+Keybind: ctrl+x x
+
+---
+
+### help
+
+Show the help dialog.
+
+```
+/help
+```
+
+Keybind: ctrl+x h
+
+---
+
+### init
+
+Guided setup for creating or updating AGENTS.md. Learn more.
+
+```
+/init
+```
+
+Keybind: ctrl+x i
+
+---
+
+### models
+
+List available models.
+
+```
+/models
+```
+
+Keybind: ctrl+x m
+
+---
+
+### new
+
+Start a new session. Alias: /clear
+
+```
+/new
+```
+
+Keybind: ctrl+x n
+
+---
+
+### redo
+
+Redo a previously undone message. Only available after using /undo.
+
+Internally, this uses Git to manage the file changes. So your project needs to be a Git repository.
+
+```
+/redo
+```
+
+Keybind: ctrl+x r
+
+---
+
+### sessions
+
+List and switch between sessions. Aliases: /resume, /continue
+
+```
+/sessions
+```
+
+Keybind: ctrl+x l
+
+---
+
+### share
+
+Share current session. Learn more.
+
+```
+/share
+```
+
+Keybind: ctrl+x s
+
+---
+
+### themes
+
+List available themes.
+
+```
+/themes
+```
+
+Keybind: ctrl+x t
+
+---
+
+### thinking
+
+Toggle the visibility of thinking/reasoning blocks in the conversation. When enabled, you can see the model’s reasoning process for models that support extended thinking.
+
+```
+/thinking
+```
+
+---
+
+### undo
+
+Undo last message in the conversation. Removes the most recent user message, all subsequent responses, and any file changes.
+
+Internally, this uses Git to manage the file changes. So your project needs to be a Git repository.
+
+```
+/undo
+```
+
+Keybind: ctrl+x u
+
+---
+
+### unshare
+
+Unshare current session. Learn more.
+
+```
+/unshare
+```
+
+---
+
+## Editor setup
+
+Both the /editor and /export commands use the editor specified in your EDITOR environment variable.
+
+- Linux/macOS
+- Windows (CMD)
+- Windows (PowerShell)
+
+```
+# Example for nano or vimexport EDITOR=nanoexport EDITOR=vim
+# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.# include --waitexport EDITOR="code --wait"
+```
+
+To make it permanent, add this to your shell profile; ~/.bashrc, ~/.zshrc, etc.
+
+Popular editor options include:
+
+- code - Visual Studio Code
+- cursor - Cursor
+- windsurf - Windsurf
+- nvim - Neovim editor
+- vim - Vim editor
+- nano - Nano editor
+- notepad - Windows Notepad
+- subl - Sublime Text
+
+Some editors need command-line arguments to run in blocking mode. The --wait flag makes the editor process block until closed.
+
+---
+
+## Configure
+
+You can 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",  "mouse": true}
+```
+
+This is separate from opencode.json, which configures server/runtime behavior.
+
+### Options
+
+- theme - Sets your UI theme. Learn more.
+- keybinds - Customizes keyboard shortcuts. Learn more.
+- scroll_acceleration.enabled - Enable macOS-style scroll acceleration for smooth, natural scrolling. When enabled, scroll speed increases with rapid scrolling gestures and stays precise for slower movements. This setting takes precedence over scroll_speed and overrides it when enabled.
+- scroll_speed - Controls how fast the TUI scrolls when using scroll commands (minimum: 0.001, supports decimal values). Defaults to 3. Note: This is ignored if scroll_acceleration.enabled is set to true.
+- diff_style - Controls diff rendering. "auto" adapts to terminal width, "stacked" always shows a single-column layout.
+- mouse - Enable or disable mouse capture in the TUI (default: true). When disabled, the terminal’s native mouse selection/scrolling behavior is preserved.
+
+Use OPENCODE_TUI_CONFIG to load a custom TUI config path.
+
+---
+
+## Customization
+
+You can customize various aspects of the TUI view using the command palette (ctrl+x h or /help). These settings persist across restarts.
+
+---
+
+#### Username display
+
+Toggle whether your username appears in chat messages. Access this through:
+
+- Command palette: Search for “username” or “hide username”
+- The setting persists automatically and will be remembered across TUI sessions

homelab/raw/articles/opencode/docs/web.md

@@ -0,0 +1,123 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/web/
+scraped: 2026-04-28T21:02:15.096190+00:00
+content_hash: 24c746a2
+---
+# Web
+
+Using OpenCode in your browser.
+
+OpenCode can run as a web application in your browser, providing the same powerful AI coding experience without needing a terminal.
+
+## Getting Started
+
+Start the web interface by running:
+
+```
+opencode web
+```
+
+This starts a local server on 127.0.0.1 with a random available port and automatically opens OpenCode in your default browser.
+
+---
+
+## Configuration
+
+You can configure the web server using command line flags or in your config file.
+
+### Port
+
+By default, OpenCode picks an available port. You can specify a port:
+
+```
+opencode web --port 4096
+```
+
+### Hostname
+
+By default, the server binds to 127.0.0.1 (localhost only). To make OpenCode accessible on your network:
+
+```
+opencode web --hostname 0.0.0.0
+```
+
+When using 0.0.0.0, OpenCode will display both local and network addresses:
+
+```
+  Local access:       http://localhost:4096  Network access:     http://192.168.1.100:4096
+```
+
+### mDNS Discovery
+
+Enable mDNS to make your server discoverable on the local network:
+
+```
+opencode web --mdns
+```
+
+This automatically sets the hostname to 0.0.0.0 and advertises the server as opencode.local.
+
+You can customize the mDNS domain name to run multiple instances on the same network:
+
+```
+opencode web --mdns --mdns-domain myproject.local
+```
+
+### CORS
+
+To allow additional domains for CORS (useful for custom frontends):
+
+```
+opencode web --cors https://example.com
+```
+
+### Authentication
+
+To protect access, set a password using the OPENCODE_SERVER_PASSWORD environment variable:
+
+```
+OPENCODE_SERVER_PASSWORD=secret opencode web
+```
+
+The username defaults to opencode but can be changed with OPENCODE_SERVER_USERNAME.
+
+---
+
+## Using the Web Interface
+
+Once started, the web interface provides access to your OpenCode sessions.
+
+### Sessions
+
+View and manage your sessions from the homepage. You can see active sessions and start new ones.
+
+### Server Status
+
+Click “See Servers” to view connected servers and their status.
+
+---
+
+## Attaching a Terminal
+
+You can attach a terminal TUI to a running web server:
+
+```
+# Start the web serveropencode web --port 4096
+# In another terminal, attach the TUIopencode attach http://localhost:4096
+```
+
+This allows you to use both the web interface and terminal simultaneously, sharing the same sessions and state.
+
+---
+
+## Config File
+
+You can also configure server settings in your opencode.json config file:
+
+```
+{  "server": {    "port": 4096,    "hostname": "0.0.0.0",    "mdns": true,    "cors": ["https://example.com"]  }}
+```
+
+Command line flags take precedence over config file settings.

homelab/raw/articles/opencode/docs/windows-wsl.md

@@ -0,0 +1,68 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/windows-wsl
+scraped: 2026-04-28T21:02:09.247845+00:00
+content_hash: f30c83ba
+---
+# Windows (WSL)
+
+Run OpenCode on Windows using WSL for the best experience.
+
+While OpenCode can run directly on Windows, we recommend using Windows Subsystem for Linux (WSL) for the best experience. WSL provides a Linux environment that works seamlessly with OpenCode’s features.
+
+---
+
+## Setup
+
+1. Install WSL If you haven’t already, install WSL using the official Microsoft guide.
+2. Install OpenCode in WSL Once WSL is set up, open your WSL terminal and install OpenCode using one of the installation methods. Terminal windowcurl -fsSL https://opencode.ai/install | bash
+3. Use OpenCode from WSL Navigate to your project directory (access Windows files via /mnt/c/, /mnt/d/, etc.) and run OpenCode. Terminal windowcd /mnt/c/Users/YourName/projectopencode
+
+---
+
+## Desktop App + WSL Server
+
+If you prefer using the OpenCode Desktop app but want to run the server in WSL:
+
+1. Start the server in WSL with --hostname 0.0.0.0 to allow external connections: Terminal windowopencode serve --hostname 0.0.0.0 --port 4096
+2. Connect the Desktop app to http://localhost:4096
+
+```
+OPENCODE_SERVER_PASSWORD=your-password opencode serve --hostname 0.0.0.0
+```
+
+---
+
+## Web Client + WSL
+
+For the best web experience on Windows:
+
+1. Run opencode web in the WSL terminal rather than PowerShell: Terminal windowopencode web --hostname 0.0.0.0
+2. Access from your Windows browser at http://localhost:<port> (OpenCode prints the URL)
+
+Running opencode web from WSL ensures proper file system access and terminal integration while still being accessible from your Windows browser.
+
+---
+
+## Accessing Windows Files
+
+WSL can access all your Windows files through the /mnt/ directory:
+
+- C: drive → /mnt/c/
+- D: drive → /mnt/d/
+- And so on…
+
+Example:
+
+```
+cd /mnt/c/Users/YourName/Documents/projectopencode
+```
+
+---
+
+## Tips
+
+- Keep OpenCode running in WSL for projects stored on Windows drives - file access is seamless
+- Use VS Code’s WSL extension alongside OpenCode for an integrated development workflow
+- Your OpenCode config and sessions are stored within the WSL environment at ~/.local/share/opencode/

homelab/raw/articles/opencode/docs/zen.md

@@ -0,0 +1,270 @@
+---
+type: agent-doc
+agent: OpenCode
+source: https://opencode.ai/docs/zen/
+scraped: 2026-04-28T21:02:12.091338+00:00
+content_hash: 93264cba
+---
+# Zen
+
+Curated list of models provided by OpenCode.
+
+OpenCode Zen is a list of tested and verified models provided by the OpenCode team.
+
+Zen works like any other provider in OpenCode. You login to OpenCode Zen and get your API key. It’s completely optional and you don’t need to use it to use OpenCode.
+
+---
+
+## Background
+
+There are a large number of models out there but only a few of these models work well as coding agents. Additionally, most providers are configured very differently; so you get very different performance and quality.
+
+So if you are using a model through something like OpenRouter, you can never be sure if you are getting the best version of the model you want.
+
+To fix this, we did a couple of things:
+
+1. We tested a select group of models and talked to their teams about how to best run them.
+2. We then worked with a few providers to make sure these were being served correctly.
+3. Finally, we benchmarked the combination of the model/provider and came up with a list that we feel good recommending.
+
+OpenCode Zen is an AI gateway that gives you access to these models.
+
+---
+
+## How it works
+
+OpenCode Zen works like any other provider in OpenCode.
+
+1. You sign in to OpenCode Zen, add your billing details, and copy your API key.
+2. You run the /connect command in the TUI, select OpenCode Zen, and paste your API key.
+3. Run /models in the TUI to see the list of models we recommend.
+
+You are charged per request and you can add credits to your account.
+
+---
+
+## Endpoints
+
+You can also access our models through the following API endpoints.
+
+| Model | Model ID | Endpoint | AI SDK Package |
+|---|---|---|---|
+| GPT 5.5 | gpt-5.5 | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5.5 Pro | gpt-5.5-pro | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5.4 | gpt-5.4 | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5.4 Pro | gpt-5.4-pro | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5.4 Mini | gpt-5.4-mini | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5.4 Nano | gpt-5.4-nano | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5.3 Codex | gpt-5.3-codex | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5.3 Codex Spark | gpt-5.3-codex-spark | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5.2 | gpt-5.2 | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5.2 Codex | gpt-5.2-codex | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5.1 | gpt-5.1 | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5.1 Codex | gpt-5.1-codex | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5.1 Codex Max | gpt-5.1-codex-max | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5.1 Codex Mini | gpt-5.1-codex-mini | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5 | gpt-5 | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5 Codex | gpt-5-codex | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| GPT 5 Nano | gpt-5-nano | https://opencode.ai/zen/v1/responses | @ai-sdk/openai |
+| Claude Opus 4.7 | claude-opus-4-7 | https://opencode.ai/zen/v1/messages | @ai-sdk/anthropic |
+| Claude Opus 4.6 | claude-opus-4-6 | https://opencode.ai/zen/v1/messages | @ai-sdk/anthropic |
+| Claude Opus 4.5 | claude-opus-4-5 | https://opencode.ai/zen/v1/messages | @ai-sdk/anthropic |
+| Claude Opus 4.1 | claude-opus-4-1 | https://opencode.ai/zen/v1/messages | @ai-sdk/anthropic |
+| Claude Sonnet 4.6 | claude-sonnet-4-6 | https://opencode.ai/zen/v1/messages | @ai-sdk/anthropic |
+| Claude Sonnet 4.5 | claude-sonnet-4-5 | https://opencode.ai/zen/v1/messages | @ai-sdk/anthropic |
+| Claude Sonnet 4 | claude-sonnet-4 | https://opencode.ai/zen/v1/messages | @ai-sdk/anthropic |
+| Claude Haiku 4.5 | claude-haiku-4-5 | https://opencode.ai/zen/v1/messages | @ai-sdk/anthropic |
+| Claude Haiku 3.5 | claude-3-5-haiku | https://opencode.ai/zen/v1/messages | @ai-sdk/anthropic |
+| Gemini 3.1 Pro | gemini-3.1-pro | https://opencode.ai/zen/v1/models/gemini-3.1-pro | @ai-sdk/google |
+| Gemini 3 Flash | gemini-3-flash | https://opencode.ai/zen/v1/models/gemini-3-flash | @ai-sdk/google |
+| Qwen3.6 Plus | qwen3.6-plus | https://opencode.ai/zen/v1/chat/completions | @ai-sdk/openai-compatible |
+| Qwen3.5 Plus | qwen3.5-plus | https://opencode.ai/zen/v1/chat/completions | @ai-sdk/openai-compatible |
+| MiniMax M2.7 | minimax-m2.7 | https://opencode.ai/zen/v1/chat/completions | @ai-sdk/openai-compatible |
+| MiniMax M2.5 | minimax-m2.5 | https://opencode.ai/zen/v1/chat/completions | @ai-sdk/openai-compatible |
+| MiniMax M2.5 Free | minimax-m2.5-free | https://opencode.ai/zen/v1/chat/completions | @ai-sdk/openai-compatible |
+| GLM 5.1 | glm-5.1 | https://opencode.ai/zen/v1/chat/completions | @ai-sdk/openai-compatible |
+| GLM 5 | glm-5 | https://opencode.ai/zen/v1/chat/completions | @ai-sdk/openai-compatible |
+| Kimi K2.5 | kimi-k2.5 | https://opencode.ai/zen/v1/chat/completions | @ai-sdk/openai-compatible |
+| Kimi K2.6 | kimi-k2.6 | https://opencode.ai/zen/v1/chat/completions | @ai-sdk/openai-compatible |
+| Big Pickle | big-pickle | https://opencode.ai/zen/v1/chat/completions | @ai-sdk/openai-compatible |
+| Ling 2.6 Flash | ling-2.6-flash | https://opencode.ai/zen/v1/chat/completions | @ai-sdk/openai-compatible |
+| Hy3 Preview Free | hy3-preview-free | https://opencode.ai/zen/v1/chat/completions | @ai-sdk/openai-compatible |
+| Nemotron 3 Super Free | nemotron-3-super-free | https://opencode.ai/zen/v1/chat/completions | @ai-sdk/openai-compatible |
+
+The model id in your OpenCode config uses the format opencode/<model-id>. For example, for GPT 5.5, you would use opencode/gpt-5.5 in your config.
+
+---
+
+### Models
+
+You can fetch the full list of available models and their metadata from:
+
+```
+https://opencode.ai/zen/v1/models
+```
+
+---
+
+## Pricing
+
+We support a pay-as-you-go model. Below are the prices per 1M tokens.
+
+| Model | Input | Output | Cached Read | Cached Write |
+|---|---|---|---|---|
+| Big Pickle | Free | Free | Free | - |
+| MiniMax M2.5 Free | Free | Free | Free | - |
+| Ling 2.6 Flash Free | Free | Free | Free | - |
+| Hy3 Preview Free | Free | Free | Free | - |
+| Nemotron 3 Super Free | Free | Free | Free | - |
+| MiniMax M2.7 | $0.30 | $1.20 | $0.06 | $0.375 |
+| MiniMax M2.5 | $0.30 | $1.20 | $0.06 | $0.375 |
+| GLM 5.1 | $1.40 | $4.40 | $0.26 | - |
+| GLM 5 | $1.00 | $3.20 | $0.20 | - |
+| Kimi K2.5 | $0.60 | $3.00 | $0.10 | - |
+| Kimi K2.6 | $0.95 | $4.00 | $0.16 | - |
+| Qwen3.6 Plus | $0.50 | $3.00 | $0.05 | $0.625 |
+| Qwen3.5 Plus | $0.20 | $1.20 | $0.02 | $0.25 |
+| Claude Opus 4.7 | $5.00 | $25.00 | $0.50 | $6.25 |
+| Claude Opus 4.6 | $5.00 | $25.00 | $0.50 | $6.25 |
+| Claude Opus 4.5 | $5.00 | $25.00 | $0.50 | $6.25 |
+| Claude Opus 4.1 | $15.00 | $75.00 | $1.50 | $18.75 |
+| Claude Sonnet 4.6 | $3.00 | $15.00 | $0.30 | $3.75 |
+| Claude Sonnet 4.5 (≤ 200K tokens) | $3.00 | $15.00 | $0.30 | $3.75 |
+| Claude Sonnet 4.5 (> 200K tokens) | $6.00 | $22.50 | $0.60 | $7.50 |
+| Claude Sonnet 4 (≤ 200K tokens) | $3.00 | $15.00 | $0.30 | $3.75 |
+| Claude Sonnet 4 (> 200K tokens) | $6.00 | $22.50 | $0.60 | $7.50 |
+| Claude Haiku 4.5 | $1.00 | $5.00 | $0.10 | $1.25 |
+| Gemini 3.1 Pro (≤ 200K tokens) | $2.00 | $12.00 | $0.20 | - |
+| Gemini 3.1 Pro (> 200K tokens) | $4.00 | $18.00 | $0.40 | - |
+| Gemini 3 Flash | $0.50 | $3.00 | $0.05 | - |
+| GPT 5.5 (≤ 272K tokens) | $5.00 | $30.00 | $0.50 | - |
+| GPT 5.5 (> 272K tokens) | $10.00 | $45.00 | $1.00 | - |
+| GPT 5.5 Pro | $30.00 | $180.00 | $30.00 | - |
+| GPT 5.4 (≤ 272K tokens) | $2.50 | $15.00 | $0.25 | - |
+| GPT 5.4 (> 272K tokens) | $5.00 | $22.50 | $0.50 | - |
+| GPT 5.4 Pro | $30.00 | $180.00 | $30.00 | - |
+| GPT 5.4 Mini | $0.75 | $4.50 | $0.075 | - |
+| GPT 5.4 Nano | $0.20 | $1.25 | $0.02 | - |
+| GPT 5.3 Codex Spark | $1.75 | $14.00 | $0.175 | - |
+| GPT 5.3 Codex | $1.75 | $14.00 | $0.175 | - |
+| GPT 5.2 | $1.75 | $14.00 | $0.175 | - |
+| GPT 5.2 Codex | $1.75 | $14.00 | $0.175 | - |
+| GPT 5.1 | $1.07 | $8.50 | $0.107 | - |
+| GPT 5.1 Codex | $1.07 | $8.50 | $0.107 | - |
+| GPT 5.1 Codex Max | $1.25 | $10.00 | $0.125 | - |
+| GPT 5.1 Codex Mini | $0.25 | $2.00 | $0.025 | - |
+| GPT 5 | $1.07 | $8.50 | $0.107 | - |
+| GPT 5 Codex | $1.07 | $8.50 | $0.107 | - |
+| GPT 5 Nano | Free | Free | Free | - |
+
+You might notice Claude Haiku 3.5 in your usage history. This is a low cost model that’s used to generate the titles of your sessions.
+
+The free models:
+
+- MiniMax M2.5 Free is available on OpenCode for a limited time. The team is using this time to collect feedback and improve the model.
+- Ling 2.6 Flash Free is available on OpenCode for a limited time. The team is using this time to collect feedback and improve the model.
+- Hy3 Preview Flash Free is available on OpenCode for a limited time. The team is using this time to collect feedback and improve the model.
+- Nemotron 3 Super Free is available on OpenCode for a limited time. The team is using this time to collect feedback and improve the model.
+- Big Pickle is a stealth model that’s free on OpenCode for a limited time. The team is using this time to collect feedback and improve the model.
+
+Contact us if you have any questions.
+
+---
+
+### Auto-reload
+
+If your balance goes below $5, Zen will automatically reload $20.
+
+You can change the auto-reload amount. You can also disable auto-reload entirely.
+
+---
+
+### Monthly limits
+
+You can also set a monthly usage limit for the entire workspace and for each member of your team.
+
+For example, let’s say you set a monthly usage limit to $20, Zen will not use more than $20 in a month. But if you have auto-reload enabled, Zen might end up charging you more than $20 if your balance goes below $5.
+
+---
+
+### Deprecated models
+
+| Model | Deprecation date |
+|---|---|
+| GPT 5.2 Codex | July 23, 2026 |
+| GPT 5.1 Codex | July 23, 2026 |
+| GPT 5.1 Codex Max | July 23, 2026 |
+| GPT 5.1 Codex Mini | July 23, 2026 |
+| GPT 5 Codex | July 23, 2026 |
+| Claude Sonnet 4 | June 15, 2026 |
+| GLM 5 | May 14, 2026 |
+| MiniMax M2.1 | March 15, 2026 |
+| GLM 4.7 | March 15, 2026 |
+| GLM 4.6 | March 15, 2026 |
+| Gemini 3 Pro | March 9, 2026 |
+| Kimi K2 Thinking | March 6, 2026 |
+| Kimi K2 | March 6, 2026 |
+| Claude Haiku 3.5 | Feb 16, 2026 |
+| Qwen3 Coder 480B | Feb 6, 2026 |
+
+---
+
+## Privacy
+
+All our models are hosted in the US. Our providers follow a zero-retention policy and do not use your data for model training, with the following exceptions:
+
+- Big Pickle: During its free period, collected data may be used to improve the model.
+- MiniMax M2.5 Free: During its free period, collected data may be used to improve the model.
+- Ling 2.6 Flash Free: During its free period, collected data may be used to improve the model.
+- Hy3 Preview Free: During its free period, collected data may be used to improve the model.
+- Nemotron 3 Super Free (NVIDIA free endpoints): Provided under the NVIDIA API Trial Terms of Service. Trial use only — not for production or sensitive data. Prompts and outputs are logged by NVIDIA to improve its models and services. Do not submit personal or confidential data.
+- OpenAI APIs: Requests are retained for 30 days in accordance with OpenAI’s Data Policies.
+- Anthropic APIs: Requests are retained for 30 days in accordance with Anthropic’s Data Policies.
+
+---
+
+## For Teams
+
+Zen also works great for teams. You can invite teammates, assign roles, curate the models your team uses, and more.
+
+Managing your workspace is currently free for teams as a part of the beta. We’ll be sharing more details on the pricing soon.
+
+---
+
+### Roles
+
+You can invite teammates to your workspace and assign roles:
+
+- Admin: Manage models, members, API keys, and billing
+- Member: Manage only their own API keys
+
+Admins can also set monthly spending limits for each member to keep costs under control.
+
+---
+
+### Model access
+
+Admins can enable or disable specific models for the workspace. Requests made to a disabled model will return an error.
+
+This is useful for cases where you want to disable the use of a model that collects data.
+
+---
+
+### Bring your own key
+
+You can use your own OpenAI or Anthropic API keys while still accessing other models in Zen.
+
+When you use your own keys, tokens are billed directly by the provider, not by Zen.
+
+For example, your organization might already have a key for OpenAI or Anthropic and you want to use that instead of the one that Zen provides.
+
+---
+
+## Goals
+
+We created OpenCode Zen to:
+
+1. Benchmark the best models/providers for coding agents.
+2. Have access to the highest quality options and not downgrade performance or route to cheaper providers.
+3. Pass along any price drops by selling at cost; so the only markup is to cover our processing fees.
+4. Have no lock-in by allowing you to use it with any other coding agent. And always let you use any other provider with OpenCode as well.