Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

programs.opencode.enable

Whether to enable opencode.

Type: boolean

Default:

false

Example:

true

Declared by:

programs.opencode.enableMcpIntegration

Whether to integrate the MCP servers config from programs.mcp.servers into programs.opencode.settings.mcp.

Note: Settings defined in programs.mcp.servers are merged with programs.opencode.settings.mcp, with OpenCode settings taking precedence.

Type: boolean

Default:

false

Declared by:

programs.opencode.package

The opencode package to use.

Type: null or package

Default:

pkgs.opencode

Declared by:

programs.opencode.agents

Custom agents for opencode.

This option can either be:

  • An attribute set defining agents
  • A path to a directory containing multiple agent files

If an attribute set is used, the attribute name becomes the agent filename, and the value is either:

  • Inline content as a string (creates opencode/agents/<name>.md)
  • A path to a file (creates opencode/agents/<name>.md)

If a path is used, it is expected to contain agent files. The directory is symlinked to $XDG_CONFIG_HOME/opencode/agents/.

Type: (attribute set of (strings concatenated with “\n” or absolute path)) or absolute path

Default:

{ }

Example:

{
  code-reviewer = ''
    # Code Reviewer Agent

    You are a senior software engineer specializing in code reviews.
    Focus on code quality, security, and maintainability.

    ## Guidelines
    - Review for potential bugs and edge cases
    - Check for security vulnerabilities
    - Ensure code follows best practices
    - Suggest improvements for readability and performance
  '';
  documentation = ./agents/documentation.md;
}

Declared by:

programs.opencode.commands

Custom commands for opencode.

This option can either be:

  • An attribute set defining commands
  • A path to a directory containing multiple command files

If an attribute set is used, the attribute name becomes the command filename, and the value is either:

  • Inline content as a string (creates opencode/commands/<name>.md)
  • A path to a file (creates opencode/commands/<name>.md)

If a path is used, it is expected to contain command files. The directory is symlinked to $XDG_CONFIG_HOME/opencode/commands/.

Type: (attribute set of (strings concatenated with “\n” or absolute path)) or absolute path

Default:

{ }

Example:

{
  changelog = ''
    # Update Changelog Command

    Update CHANGELOG.md with a new entry for the specified version.
    Usage: /changelog [version] [change-type] [message]
  '';
  fix-issue = ./commands/fix-issue.md;
  commit = ''
    # Commit Command

    Create a git commit with proper message formatting.
    Usage: /commit [message]
  '';
}

Declared by:

programs.opencode.context

Global context for OpenCode.

The value is either:

  • Inline content as a string
  • A path to a file containing the content

The configured content is written to $XDG_CONFIG_HOME/opencode/AGENTS.md.

Type: strings concatenated with “\n” or absolute path

Default:

""

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.md
  For React component architecture and hooks patterns: @docs/react-patterns.md
  For REST API design and error handling: @docs/api-standards.md
  For 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.
''

Declared by:

programs.opencode.extraPackages

Extra packages available to OpenCode.

Type: list of package

Default:

[ ]

Example:

[ pkgs.uv ]

Declared by:

programs.opencode.settings

Configuration written to $XDG_CONFIG_HOME/opencode/opencode.json. See https://opencode.ai/docs/config/ for the documentation.

Attribute sets containing ordered lib.hm.dag.entryBefore or lib.hm.dag.entryAfter values are rendered in topological order, with raw sibling values treated as unordered entries. This is useful for OpenCode permission rules, where the last matching rule wins.

Note, "$schema": "https://opencode.ai/config.json" is automatically added to the configuration.

Type: JSON value

Default:

{ }

Example:

{
  autoshare = false;
  autoupdate = true;
  model = "anthropic/claude-sonnet-4-20250514";
}

Declared by:

programs.opencode.skills

Custom skills for OpenCode.

This option can be either:

  • An attribute set defining skills
  • A path to a directory containing skill folders

If an attribute set is used, the attribute name becomes the skill directory name, and the value is either:

  • Inline content as a string (creates opencode/skills/<name>/SKILL.md)
  • A path to a file (creates opencode/skills/<name>/SKILL.md)
  • A path to a directory (creates opencode/skills/<name>/ with all files)

This also accepts Nix store paths, for example a skill directory from a package.

If a path is used, it is expected to contain one folder per skill name, each containing a SKILL.md. The directory is symlinked to $XDG_CONFIG_HOME/opencode/skills/.

See https://opencode.ai/docs/skills/ for the documentation.

Type: (attribute set of (strings concatenated with “\n” or absolute path or string)) or absolute path

Default:

{ }

Example:

{
  git-release = ''
    ---
    name: git-release
    description: Create consistent releases and changelogs
    ---

    ## What I do

    - Draft release notes from merged PRs
    - Propose a version bump
    - Provide a copy-pasteable `gh release create` command
  '';

  # A skill can also be a directory containing SKILL.md and other files.
  data-analysis = ./skills/data-analysis;

  # A skill can also be a subdirectory within a package source (store path)
  beads = "${pkgs.beads.src}/claude-plugin/skills/beads";
}

Declared by:

programs.opencode.themes

Custom themes for opencode.

This option can either be:

  • An attribute set defining themes
  • A path to a directory containing multiple theme files

If an attribute set is used, the attribute name becomes the theme filename, and the value is either:

  • An attribute set that is converted to a JSON file (creates opencode/themes/<name>.json)
  • A path to a file (creates opencode/themes/<name>.json)

If a path is used, it is expected to contain theme files. The directory is symlinked to $XDG_CONFIG_HOME/opencode/themes/.

Set programs.opencode.tui.theme to enable the custom theme. See https://opencode.ai/docs/themes/ for the documentation.

Type: (attribute set of (JSON value or absolute path)) or absolute path

Default:

{ }

Declared by:

programs.opencode.tools

Custom tools for opencode.

This option can either be:

  • An attribute set defining tools
  • A path to a directory containing multiple tool files

If an attribute set is used, the attribute name becomes the tool filename, and the value is either:

  • Inline content as a string (creates opencode/tools/<name>.ts)
  • A path to a file (creates opencode/tools/<name>.ts or opencode/tools/<name>.js)

If a path is used, it is expected to contain tool files. The directory is symlinked to $XDG_CONFIG_HOME/opencode/tools/.

See https://opencode.ai/docs/tools/ for the documentation.

Type: (attribute set of (strings concatenated with “\n” or absolute path)) or absolute path

Default:

{ }

Example:

{
  database-query = ''
    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}`
      },
    })
  '';

  # Or reference an existing file
  api-client = ./tools/api-client.ts;
}

Declared by:

programs.opencode.tui

TUI-specific configuration written to $XDG_CONFIG_HOME/opencode/tui.json.

This includes theme, keybinds, scroll settings, and other TUI-only options. See https://opencode.ai/docs/tui#configure for the documentation.

Note that "$schema": "https://opencode.ai/tui.json" is automatically added.

Since OpenCode v1.2.15, TUI settings must be in a separate tui.json file. Settings like theme, keybinds, and tui in programs.opencode.settings are deprecated and should be moved here.

Type: JSON value

Default:

{ }

Example:

{
  keybinds = {
    leader = "alt+b";
  };
  theme = "system";
}

Declared by:

programs.opencode.web.enable

Whether to enable opencode web service.

Type: boolean

Default:

false

Example:

true

Declared by:

programs.opencode.web.environmentFile

Path to a file containing environment variables for the opencode web service, in the format of an EnvironmentFile as described by systemd.exec(5) (i.e. KEY=VALUE pairs, one per line).

This is the recommended way to set OPENCODE_SERVER_PASSWORD without exposing the secret value in the Nix store.

Type: null or absolute path

Default:

null

Example:

"/run/secrets/opencode-web"

Declared by:

programs.opencode.web.extraArgs

Extra arguments to pass to the opencode serve command.

These arguments override the “server” options defined in the configuration file. See https://opencode.ai/docs/web/#config-file for available options.

Type: list of string

Default:

[ ]

Example:

[
  "--hostname"
  "0.0.0.0"
  "--port"
  "4096"
  "--mdns"
  "--cors"
  "https://example.com"
  "--cors"
  "http://localhost:3000"
  "--print-logs"
  "--log-level"
  "DEBUG"
]

Declared by: