OpenCodez

A local-first OpenCode fork for flexible System/Tone prompt control, token-saving pruning, and bundled Codex prompts for a Codex-like experience.

OpenCodez is not an official OpenCode project.
It keeps upstream OpenCode recognizable while adding a few practical controls for prompt-heavy work.

OpenCodez Docs · Install & Update · Commands · Upstream README

---

At a Glance

OpenCodez is for people who want OpenCode to stay OpenCode, but with flexible prompt control, a ready-to-use Codex-style prompt set, and less noisy model context.

Area	What OpenCodez adds
Prompt control	TUI commands and web composer controls for System, Tone, Template, and explicit session setup.
Prompt library	Upstream built-ins, bundled Codex presets, and user prompt files in one shared selector.
Model defaults	Configurable System/Tone defaults, with Codex-style defaults only for OpenAI Responses GPT models out of the box.
Session state	Manual System/Tone/Template choices stay with the session and do not reset on /model.
Pruning	Reasoning and tool result payloads can be replaced with clear placeholders before context is sent to the model.
Updates	opencodez update uses GitHub Releases.

Read the full public feature reference in docs/opencodez.md.

What OpenCodez Adds

OpenCodez keeps the normal OpenCode shape, but adds a few practical controls:

• /system selects the active Core/System prompt.
• /tone selects the active Tone preset.
• /template applies a saved System + Tone pair.
• /prompts shows prompt library roots, current selections, and where editable prompt files live.
• /new --system, /new --tone, and /new --template start a new session with explicit prompt settings.
• The web composer has S:, T:, and Template controls for the same session-level prompt choices.
• None in the System or Tone selector explicitly disables that selectable prompt for the current session.
• Model-aware defaults can choose System/Tone presets automatically for OpenAI Responses GPT models, and users can configure defaults for other models too.
• Manual /system, /tone, and /template choices stay active when you switch models.
• The TUI shows the concrete active System prompt id and Tone preset while you work.
• /pruning lets you view and change session-local pruning settings.
• Tool calls stay readable while tool result and reasoning payloads can be replaced with deterministic placeholders.

OpenCodez is meant to be a small fork, not a full rebrand. Upstream internals, docs, workflows, integrations, and package surfaces should stay as close to OpenCode as practical unless a fork-specific change is genuinely needed.

For detailed behavior, defaults, command semantics, pruning rules, and maintenance notes, use OpenCodez Docs.

Install & Update

OpenCodez installs from GitHub Releases. It does not publish to npm and does not install over upstream opencode.

Linux and macOS install:

curl -fsSL https://raw.githubusercontent.com/Krablante/opencodez/main/install.sh | sh

Windows PowerShell install:

irm https://raw.githubusercontent.com/Krablante/opencodez/main/install.ps1 | iex

Public release update:

opencodez update

Check for updates without installing:

opencodez update --check

The update path is intentionally simple: GitHub Releases are the source of truth, the installer downloads the right release artifact for the current OS and architecture, and opencodez update uses the same release channel from inside the app.

Run From Source

For local development, run the source-checkout launcher directly:

./packages/opencode/bin/opencodez --help
./packages/opencode/bin/opencodez

Release builds should set OPENCODEZ_BUILD=1 so the build script emits opencodez-* artifacts with an opencodez binary inside.

Side-by-Side With OpenCode

OpenCodez is expected to live next to upstream OpenCode:

opencode   # upstream OpenCode
opencodez  # this fork

It uses its own config, data, and cache roots:

~/.config/opencodez/
~/.local/share/opencodez/
~/.cache/opencodez/

OpenCodez does not automatically read from or write to ~/.config/opencode/. If you want to reuse upstream OpenCode settings or prompt files, copy only the pieces you want into the OpenCodez config root manually.

OpenCodez Docs

The maintained public reference for OpenCodez-specific behavior is:

docs/opencodez.md

It covers prompt defaults, selectors, templates, pruning, config roots, session behavior, and maintenance expectations for this fork. Upstream OpenCode documentation remains the source for normal OpenCode behavior.

Prompt library paths:

~/.config/opencodez/prompts/core/<name>.md
~/.config/opencodez/prompts/tone/<name>.md
~/.config/opencodez/prompts/templates/<name>.jsonc

Bundled Codex-derived prompt files use the codex_ prefix. User-created prompt files do not need that prefix.

Bundled Core/System prompts:

codex_gpt_5_2
codex_gpt_5_2_codex
codex_gpt_5_3_codex
codex_gpt_5_4
codex_gpt_5_4_mini
codex_gpt_5_5

Bundled Tone presets:

codex_friendly
codex_pragmatic

Out-of-the-box OpenAI Responses GPT System defaults:

gpt-5.2 -> codex_gpt_5_2
gpt-5.2-codex -> codex_gpt_5_2_codex
gpt-5.3-codex -> codex_gpt_5_3_codex
gpt-5.3-codex-spark -> codex_gpt_5_3_codex
gpt-5.4 -> codex_gpt_5_4
gpt-5.4-mini -> codex_gpt_5_4_mini
gpt-5.5 -> codex_gpt_5_5

Model defaults live in ~/.config/opencodez/opencode.jsonc. Values can be one prompt name for all models, or a mapping keyed by model id, family, provider/model, or default:

{
  "opencodez": {
    "responses": {
      "system": {
        "default": "codex_gpt_5_5",
        "gpt-5.2-codex": "codex_gpt_5_2_codex",
        "gpt-5.3-codex-spark": "codex_gpt_5_3_codex",
        "gpt-5.4": "codex_gpt_5_4",
        "gpt-5.4-mini": "codex_gpt_5_4_mini",
        "deepseek": "default"
      },
      "tone": {
        "default": "codex_pragmatic",
        "anthropic": "codex_friendly"
      }
    }
  }
}

Pruning Config

Pruning defaults also live in ~/.config/opencodez/opencode.jsonc:

{
  "opencodez": {
    "pruning": {
      "enabled": true,
      "pruning_size": 20000,
      "prune": {
        "reasoning": true,
        "tool": true
      },
      "preserve_tools": []
    }
  }
}

enabled turns pruning on or off. pruning_size is the payload budget, currently counted in characters. prune.reasoning and prune.tool decide which payload types can be replaced with placeholders. preserve_tools is a list of tool names or glob patterns that should never be pruned.

The /pruning TUI command changes only the current session's enabled state and pruning_size. It does not rewrite opencode.jsonc.

Commands

Command	What it does
/system	Opens the Core/System prompt selector.
/system codex_gpt_5_5	Sets the current session System prompt directly.
/system none	Explicitly disables the selectable System prompt for the current session.
/tone	Opens the Tone selector.
/tone codex_pragmatic	Sets the current session Tone preset directly.
/tone codex_friendly	Sets the current session Tone preset directly.
/tone none	Explicitly disables the Tone preset for the current session.
/template	Opens the Template selector.
/template gpt55	Applies a saved System + Tone template.
/new --system codex_gpt_5_5 --tone codex_pragmatic	Starts a new session with explicit System and Tone values.
/new -s codex_gpt_5_5 -o codex_pragmatic	Short-flag form of the same command.
/new --template gpt55	Starts a new session from a saved template.
/new -t gpt55	Short-flag form of the template command.
/prompts	Shows prompt library paths, current selections, and editable prompt locations.
/pruning	Opens the pruning settings view.
/pruning on	Enables pruning for the current session.
/pruning off	Disables pruning for the current session.
/pruning size 20000	Sets the current session pruning payload budget.

Upstream OpenCode README

The original OpenCode README is kept below for general upstream context. OpenCodez-specific behavior is described in the sections above.

---

The open source AI coding agent.

English | 简体中文 | 繁體中文 | 한국어 | Deutsch | Español | Français | Italiano | Dansk | 日本語 | Polski | Русский | Bosanski | العربية | Norsk | Português (Brasil) | ไทย | Türkçe | Українська | বাংলা | Ελληνικά | Tiếng Việt

---

Installation

# YOLO
curl -fsSL https://opencode.ai/install | bash

# Package managers
npm i -g opencode-ai@latest        # or bun/pnpm/yarn
scoop install opencode             # Windows
choco install opencode             # Windows
brew install anomalyco/tap/opencode # macOS and Linux (recommended, always up to date)
brew install opencode              # macOS and Linux (official brew formula, updated less)
sudo pacman -S opencode            # Arch Linux (Stable)
paru -S opencode-bin               # Arch Linux (Latest from AUR)
mise use -g opencode               # Any OS
nix run nixpkgs#opencode           # or github:anomalyco/opencode for latest dev branch

Tip

Remove versions older than 0.1.x before installing.

Desktop App (BETA)

OpenCode is also available as a desktop application. Download directly from the releases page or opencode.ai/download.

Platform	Download
macOS (Apple Silicon)	opencode-desktop-mac-arm64.dmg
macOS (Intel)	opencode-desktop-mac-x64.dmg
Windows	opencode-desktop-windows-x64.exe
Linux	.deb, .rpm, or .AppImage

# macOS (Homebrew)
brew install --cask opencode-desktop
# Windows (Scoop)
scoop bucket add extras; scoop install extras/opencode-desktop

Installation Directory

The install script respects the following priority order for the installation path:

1. $OPENCODE_INSTALL_DIR - Custom installation directory
2. $XDG_BIN_DIR - XDG Base Directory Specification compliant path
3. $HOME/bin - Standard user binary directory (if it exists or can be created)
4. $HOME/.opencode/bin - Default fallback

# Examples
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

Agents

OpenCode includes two built-in agents you can switch between with the Tab key.

• build - Default, full-access agent for development work
• plan - Read-only agent for analysis and code exploration
  • Denies file edits by default
  • Asks permission before running bash commands
  • Ideal for exploring unfamiliar codebases or planning changes

Also included is a general subagent for complex searches and multistep tasks. This is used internally and can be invoked using @general in messages.

Learn more about agents.

Documentation

For more info on how to configure OpenCode, head over to our docs.

Contributing

If you're interested in contributing to OpenCode, please read our contributing docs before submitting a pull request.

Building on OpenCode

If you are working on a project that's related to OpenCode and is using "opencode" as part of its name, for example "opencode-dashboard" or "opencode-mobile", please add a note to your README to clarify that it is not built by the OpenCode team and is not affiliated with us in any way.

---

Join our community Discord | X.com