OpenCode OpenAI Generic Project Config

Reusable OpenCode configuration for general software projects. It is OpenAI-specific, project-agnostic, and conservative around secrets, destructive commands, publishing, deployments, and production access.

What This Includes

• template/.opencode/opencode.jsonc: OpenCode project config.
• template/.opencode/oh-my-opencode-slim.jsonc: generic multi-agent routing for oh-my-opencode-slim.
• template/.opencode/oh-my-opencode-slim/project-instructions.md: project-wide working rules.
• template/.opencode/oh-my-opencode-slim/orchestrator_append.md: generic routing guidance.
• template/.opencode/skills/project-workflow/SKILL.md: reusable workflow skill for any codebase.
• template/opencode-balanced.cmd, template/opencode-performance.cmd, and template/opencode-maxed.cmd: Windows Desktop launchers installed at the destination workspace root.
• template/.opencode/launch-desktop.mjs: shared, workspace-relative profile selection and Desktop launch helper.
• scripts/install.ps1: Windows installer with interactive model selection.
• scripts/install.sh: macOS/Linux installer with interactive model selection.

No API keys, RPC endpoints, private keys, or project-specific paths are included.

Balanced Profile Defaults

• Astra (openai/gpt-6-astra) supplies Oracle at max effort as the highest-capability reasoning and escalation lane. Oracle remains read-only and is reserved for difficult diagnosis, unresolved design questions, and high-risk decisions, not routine implementation.
• Terra (openai/gpt-5.6-terra) handles high-effort orchestration, bounded Fixer implementation, and code review, plus general work, source synthesis, technical summaries, compaction, design, and test strategy at medium effort.
• Sol (openai/gpt-5.6-sol) handles direct build work at medium effort; planning, council synthesis, security review, and architecture at high effort; and the independent deep-review council seat at max effort.
• Luna (openai/gpt-5.6-luna) handles exploration and research at low effort, visual analysis at medium, titles at none, and fast sanity checks at low.
• Core routing uses Terra as the default model and Luna as the small model. Build is Sol medium; native Plan is Sol high; general is Terra medium; Explore is Luna low; title is Luna none; and summary/compaction are Terra medium. Compaction retains 6 tail turns.
• The orchestrator retains OMOS 2.2.17's bundled scheduler-first prompt, with a goal-locking append: it builds the shortest useful dependency graph, delegates bounded non-trivial work, reconciles results, and owns final verification. It works directly only on one isolated, clear, low-risk action where delegation would cost more than execution.
• Runtime model fallback is disabled; provider errors do not trigger model-chain switches. Configured routes are: Orchestrator Terra high; Oracle Astra max; council Sol high; Explorer and Librarian Luna low; Fixer Terra high; Designer Terra medium; Observer Luna medium. OpenCode's same-model retries and explicit user model selection are separate behaviors.
• Council runs three dynamic councillor subagents in parallel. Deep review uses Sol max, fast sanity uses Luna low, and security sanity uses Terra high. Slim retries an empty councillor response once per model entry and handles council timing through its orchestrator prompt rather than obsolete timeout fields.
• Generic specialists route code review to Terra high, architecture to Sol high, test strategy to Terra medium, and security review to Sol high.
• These are template defaults. Customized installations substitute five independent model slots while retaining the documented role-specific effort variants. The separate Oracle slot does not alter Build, Plan, architecture, security review, or council routing.
• The orchestrator is the only implementation lane allowed to delegate. Native Plan may call only the read-only Explorer and Librarian. Fixer and Designer can edit but cannot spawn agents; Explorer, Librarian, Oracle, Observer, and the project review specialists are enforced read-only. subagent_depth is explicitly 1.
• Librarian alone receives OpenCode's built-in web search plus the bundled Context7 and GitHub grep MCPs for external research. Other normal lanes are denied built-in web search and do not receive those MCPs.
• Observer is enabled with automatic image routing so screenshots, images, PDFs, and diagrams can be analyzed outside the orchestrator's main context.
• Slim's periodic orchestrator wake is explicitly disabled to avoid unplanned idle model calls. Background tasks, completion injection, and reconciliation remain enabled.
• Secret-like files are read-gated and edit-denied by default.
• Shell commands ask first by default, including git push, package publish, production deploy, kubectl, terraform apply, live transaction broadcasts, and destructive cleanup. Dedicated file tools remain available for normal repository inspection and edits.

Balanced, Performance, And Maxed Profiles

Balanced is the default four-model profile described above. Performance uses Sol for routine work and Astra for Oracle escalation and selective independent council review. Maxed defaults every route to Astra with role-specific efforts, not max effort everywhere. Select a profile during installation; all three use the same generic-openai runtime preset. Performance and Maxed are capability-focused choices, not claims of measured speed or accuracy superiority.

Agent or route	Balanced model / effort	Performance model / effort	Maxed model / effort
Orchestrator	Terra high	Sol high	Astra high
Oracle	Astra max	Astra max	Astra max
Council	Sol high	Sol high	Astra high
Explorer	Luna low	Sol low	Astra low
Librarian	Luna low	Sol medium	Astra medium
Fixer	Terra high	Sol high	Astra high
Designer	Terra medium	Sol medium	Astra medium
Observer	Luna medium	Sol medium	Astra medium
Code Reviewer	Terra high	Sol high	Astra high
Repo Architect	Sol high	Sol high	Astra high
Test Writer	Terra medium	Sol medium	Astra medium
Security Reviewer	Sol high	Sol high	Astra high
Native Build	Sol medium	Sol medium	Astra high
Native Plan	Sol high	Sol high	Astra high
Native General	Terra medium	Sol medium	Astra medium
Native Explore	Luna low	Sol low	Astra low
Council Deep Review	Sol max	Astra max	Astra max
Council Fast Sanity	Luna low	Sol low	Astra low
Council Security Sanity	Terra high	Sol high	Astra high
Internal Title	Luna none	Sol none	Astra low
Internal Summary	Terra medium	Sol low	Astra low
Internal Compaction	Terra medium	Sol medium	Astra medium

Model IDs are openai/gpt-6-astra, openai/gpt-5.6-sol, openai/gpt-5.6-terra, and openai/gpt-5.6-luna. The detailed rationale below applies to all profiles; model assignments do not change role responsibilities.

Thinking need is a qualitative estimate based on the project role descriptions and routing rules, not a measured minimum or a direct equivalent of API effort. Actual tasks vary; evaluate model capability, accuracy, latency, and quota use together when choosing a profile for a project.

Agent or route	Performance model	Performance effort	Thinking needed and why
orchestrator	Sol	high	High: Sequences dependencies, chooses specialists, reconciles results, and judges whether verification is sufficient.
oracle	Astra	max	Exceptional: Resolves ambiguous diagnoses and high-risk decisions by comparing explanations and questioning hidden assumptions.
council	Sol	high	High: Weighs independent findings and resolves disagreements rather than simply concatenating reviews.
explorer	Sol	low	Low to medium: Retrieves files and symbols; tracing behavior across modules requires additional reasoning.
librarian	Sol	medium	Medium: Selects authoritative sources, checks version compatibility, and reconciles documentation with source behavior.
fixer	Sol	high	Medium to high: Implements acceptance criteria while preserving behavior; state, concurrency, and cross-file changes increase demand.
designer	Sol	medium	Medium to high: Balances visual hierarchy, interaction states, accessibility, responsiveness, and implementation constraints.
observer	Sol	medium	Medium: Interprets visual relationships and separates visible evidence from inference; visual accuracy also matters.
code-reviewer	Sol	high	High: Traces behavioral consequences and edge cases while distinguishing real regressions from speculative concerns.
repo-architect	Sol	high	High: Compares coupling, ownership, compatibility, migration cost, and operational impact across designs.
test-writer	Sol	medium	Medium to high: Derives meaningful assertions and failure cases; complex state transitions and integration boundaries demand more analysis.
security-reviewer	Sol	high	High: Follows trust boundaries and data flow, evaluates defensive controls, and assesses risks in context.
Native build	Sol	medium	Medium to high: Owns implementation and verification without delegation; complex features need more analysis than isolated edits.
Native plan	Sol	high	High: Identifies constraints, compares approaches, and sequences implementation, migration, and verification.
Native general	Sol	medium	Usually medium: Handles varied bounded work; the assignment determines demand more than the generic role name.
Native explore	Sol	low	Low to medium: Locates code and explains structure; behavioral tracing needs more reasoning than symbol lookup.
Council deep-review	Astra	max	High to exceptional: Independently examines correctness and operational risks on selected important changes; routine reviews do not inherently require max effort.
Council fast-sanity	Sol	low	Low: Checks obvious bugs, unclear assumptions, and missing verification using basic judgment.
Council security-sanity	Sol	high	Medium to high: Screens bounded diffs for defensive security risks; context-sensitive risks require more than checklist matching.
Internal title	Sol	none	Minimal: Identifies the main topic and expresses it briefly with little multi-step analysis.
Internal summary	Sol	low	Low to medium: Condenses known information while preserving decisions and qualifications; contradictory conversations are harder.
Internal compaction	Sol	medium	Medium: Preserves constraints, decisions, and unfinished work while removing repetition; omissions can derail later work.

Performance sets installer slots primary, balanced, and utility to Sol, with deep and oracle on Astra. It also changes Librarian from low to medium and internal Summary from medium to low. The balanced slot name is shared by all profiles and is distinct from the Balanced profile name. Profile-level quality, latency, and Codex quota impact have not been comparatively benchmarked; Performance has higher API rates at comparable token usage for the upgraded routes.

Maxed sets all five slots, the core default model, and the small model to Astra. Compared with Performance, it raises Native Build to high for direct implementation and changes Title to low, Astra's lowest supported effort. Other efforts remain unchanged. Manual model overrides create a customized installation, not the stock Astra-only profile. Maxed keeps permission boundaries, selective council use, and disabled fallback unchanged. Council still uses separate prompts and sessions, but no longer has cross-model diversity. Every routine and internal call now uses Astra rates; quality gains, latency, and actual Codex quota impact require workload-specific evaluation rather than assuming Maxed is always better.

Models, Effort, Pricing, And Performance

Standard USD API pricing per 1M tokens, verified on 2026-09-04 against official OpenAI API pricing. These are direct API prices, not ChatGPT subscription credits or third-party hosting rates. Short-context rates apply through 272,000 input tokens:

Model	Input	Cache read	Cache write	Output
Astra (Oracle)	$10.00	$1.00	$12.50	$50.00
Sol	$4.00	$0.40	$5.00	$20.00
Terra	$2.00	$0.20	$2.50	$12.00
Luna	$0.20	$0.02	$0.25	$1.20

OpenAI's current model pages document all four models with a 1,050,000-token context window, a 922,000-token maximum input, and a 128,000-token output limit. Requests above 272,000 input tokens are billed at the following rates for the full request, not just the excess:

Model	Input	Cache read	Cache write	Output
Astra (Oracle)	$20.00	$2.00	$25.00	$75.00
Sol	$8.00	$0.80	$10.00	$30.00
Terra	$4.00	$0.40	$5.00	$18.00
Luna	$0.40	$0.04	$0.50	$1.80

Cache writes cost 1.25x uncached input and cache reads cost 0.1x for these models. The write rate is the total rate for write-classified tokens, not an extra 1.25x surcharge on top of ordinary input. Cache hits are not guaranteed. Reasoning tokens are billed as output, so max is neither a fixed token budget nor a fixed cost multiplier. Sol's current Standard pricing is promotional through at least 2026-11-21; that is not a confirmed end date or a published post-promotion price.

The reviewed OpenCode 1.18.29 catalog reports 400,000 context / 272,000 input / 128,000 output for Sol/Terra/Luna, versus 1,050,000 / 922,000 / 128,000 for Astra. It also reports zero cost for all listed models in this environment; that does not mean inference is free. Use the effective host limits for context planning and official pricing/account billing for cost estimates. Do not raise context limits merely to match a provider headline.

OpenAI's GPT-5.6 launch evaluations support the current tiering. These are historical, versioned benchmarks, not evaluations of this template's exact prompts or workloads:

Published evaluation	Sol	Terra	Luna
Artificial Analysis Coding Agent Index v1.1	80.0	77.4	74.6
SWE-Bench Pro	64.6%	63.4%	62.7%
Terminal-Bench 2.1	88.8%	87.4%	84.7%

OpenCode 1.18.29 exposes GPT-5.6 effort variants none, low, medium, high, xhigh, and max. This template reserves max for rare Oracle and deep-council reasoning rather than applying it globally.

Generated -fast aliases select the same underlying model with Fast service (serviceTier: "priority" in the reviewed host). Fast pricing is 2x every corresponding Standard rate for all four models, including long-context rates. OpenAI advertises up to 2.5x faster service for Sol and up to 2x for Astra, not guaranteed end-to-end task speedups. Astra Fast is unavailable with EU data residency and has no latency SLA. Keep Fast opt-in for latency-sensitive work rather than paying the premium for every background task.

GPT-6 Astra Assessment

Astra's announcement describes a staged rollout. A host catalog entry does not guarantee that an API organization has access. At equal token usage and cache mix, Astra costs 2.5x Sol; actual cost per successful task can differ if Astra needs fewer steps or tokens.

Current evaluation	Astra	Sol
Terminal-Bench 4.0	57.9%	37.3%
DeepSWE v1.1	74.1%	72.7%
Artificial Analysis Coding Agent Index v1.4	67.0	65.1

These are OpenAI-reported maximum scores across efforts, not matched-budget measurements. Do not compare the v1.4 index with the older v1.1 table, or Terminal-Bench 4.0 with 2.1. They justify evaluating Astra for difficult work, not moving all agents to it.

The template assigns Astra to Oracle only by default. The Orchestrator can delegate difficult questions to Oracle during normal orchestration; users do not have to switch to Build to involve Astra. Oracle advises read-only, then Fixer implements. Use repo-architect for normal architecture work instead of dispatching Oracle on every task. The independent oracle installer slot can select another max-capable model without moving the other Sol agents or the deep council seat.

This is a role-based escalation choice, not proof that Astra max always outperforms Sol max. Keep Oracle requests focused and infrequent: at equal token usage, its API token rates are 2.5x Sol's. Subscription credit weights were not measured. Automatic model fallback remains disabled.

A focused 2026-09-04 check using the resolved Oracle prompt and Astra max passed a synthetic inventory-consistency and retry-idempotency review in an isolated session with all tools denied. It took 22.5 seconds of CLI wall time and reported 746 input, 182 visible output, and 307 reasoning tokens through ChatGPT/Codex access. This confirms point-in-time max-effort inference and basic reasoning, not comparative superiority or an end-to-end orchestration benchmark.

Local Coding Evidence

A 2026-09-04 one-shot comparison used OpenCode 1.18.29 with existing ChatGPT/Codex access, no API key supplied by the harness, tools disabled, and fresh sessions. All four models passed low-effort inference checks. Each model then received the same order-ledger implementation and TTL/LRU cache repair tasks twice at high effort, with 33 predefined checks and no test feedback.

Model at high effort	Fully passing coding attempts	Mean successful CLI time
Astra	4/4	32.5 seconds
Terra	4/4	33.7 seconds
Sol	4/4	59.2 seconds
Luna	3/4	82.5 seconds

Luna's remaining attempt hit the 120-second provider timeout; its usage is unknown, not zero, and its latency is excluded from that success-only mean. Every completed implementation passed its checks. Whole CLI times include startup and network/provider waiting. This small sample motivates trying Terra for Fixer, but does not evaluate full OMOS orchestration, difficult-code quality, Sol medium Build, or compare Oracle models at max effort. API-equivalent prices and token counts cannot establish actual Codex credit savings.

OpenCode 1.18.29's built-in OpenAI integration clears the requested output-token limit. Do not treat output settings, agent steps, or a local timeout as hard token, credit, or spending caps.

According to Astra's migration guide, tool calling requires the Responses API; Chat Completions does not support Astra tool calls. Keep effort explicit and do not add temperature or top_p overrides. Provider safety-monitoring blocks must be surfaced, not automatically retried or routed around.

Sources: Astra model, Sol model, Terra model, Luna model, prompt caching, reasoning.

Requirements

• OpenCode installed and available as opencode or opencode.cmd. Configuration resolution is checked with OpenCode 1.18.29.
• The oh-my-opencode-slim OpenCode plugin, pinned by this template to tested version 2.2.17 for both runtime loading and the editor schema.
• OpenAI credentials for the configured openai/... model IDs.
• The macOS/Linux installer requires Node.js or Python 3 and verifies the runtime before copying or overwriting destination files.

OMOS 2.2.18 was available at review time, but this update retains the verified 2.2.17 pin. New model IDs do not require changing that pin. Evaluate plugin upgrades separately with background-task and prompt-loading checks rather than bundling them into a pricing update.

The installer queries opencode models openai for interactive customization. Catalog presence does not guarantee runtime availability or account access. The local inference/coding checks above establish point-in-time access on one ChatGPT/Codex connection, not access for every API organization or a guarantee of current provider health. If your setup uses different model names, select them during install or edit both:

• template/.opencode/opencode.jsonc
• template/.opencode/oh-my-opencode-slim.jsonc

Required Runtime Environment

Launch OpenCode for this project with the two required feature flags and the project-scoped preset override:

OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
OPENCODE_ENABLE_EXA=1
OH_MY_OPENCODE_SLIM_PRESET=generic-openai

The preset variable selects this project's generic-openai preset instead of an inherited preset name. It does not override every other configuration layer. OMOS merges top-level agents.<name> over preset entries, including inherited user-level agent settings; core OpenCode agent.<name> fields can also override plugin-generated routing. Inspect effective configuration rather than assuming the preset wins. The installed .opencode/opencode.env records the values but OpenCode does not load that file automatically. Use the one-shot launch commands below; only the two feature flags are suitable for cross-project shell profiles.

PowerShell one-shot launch:

$env:OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS = "true"
$env:OPENCODE_ENABLE_EXA = "1"
$env:OH_MY_OPENCODE_SLIM_PRESET = "generic-openai"
opencode.cmd

PowerShell persistent user environment for the two cross-project feature flags:

[Environment]::SetEnvironmentVariable("OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS", "true", "User")
[Environment]::SetEnvironmentVariable("OPENCODE_ENABLE_EXA", "1", "User")

Open a new terminal after setting persistent variables. Keep OH_MY_OPENCODE_SLIM_PRESET=generic-openai in this project's one-shot launch command or a project-specific wrapper; setting it globally would override Slim routing in unrelated projects.

macOS/Linux one-shot launch:

OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true OPENCODE_ENABLE_EXA=1 OH_MY_OPENCODE_SLIM_PRESET=generic-openai opencode

For persistent setup, add the two feature flags to the startup file for your shell and open a new terminal:

export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
export OPENCODE_ENABLE_EXA=1

Keep OH_MY_OPENCODE_SLIM_PRESET=generic-openai project-scoped in the one-shot command or a project-specific wrapper.

Install Into A Project

From this repo on Windows:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -ProjectPath C:\path\to\your-project

The installer defaults to Balanced. Pass -Profile Performance or -Profile Maxed on Windows, or --profile performance or --profile maxed on macOS/Linux. Profile names are case-insensitive. There is no additional profile prompt, so existing scripted model-choice input remains valid.

The installer asks whether to customize model routing. Only if you choose yes does it query OpenCode, then show each routing slot, its description, profile-default model, and numbered OpenAI models. Non-interactive installs and declining customization skip the catalog query. Custom choices override profile model defaults, but retain the selected profile's effort settings.

From this repo on macOS/Linux:

bash ./scripts/install.sh /path/to/your-project

For a non-interactive Performance installation:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -ProjectPath C:\path\to\your-project -Profile Performance -NonInteractive

bash ./scripts/install.sh /path/to/your-project --profile performance --non-interactive

For a non-interactive Maxed installation:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -ProjectPath C:\path\to\your-project -Profile Maxed -NonInteractive

bash ./scripts/install.sh /path/to/your-project --profile maxed --non-interactive

If the target project already has .opencode or one of the root launcher files, the installer stops unless you pass force mode. To switch profiles, use a Windows Desktop launcher below or rerun the installer with the desired profile and force mode, then quit and restart OpenCode. Omitting the installer profile selects Balanced again; it does not preserve a previous Performance or Maxed selection. Force installation overwrites matching template files, so review project-specific edits first. Changing only OH_MY_OPENCODE_SLIM_PRESET does not switch profiles or update native agent routing.

Windows force mode:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -ProjectPath C:\path\to\your-project -Force

macOS/Linux force mode:

FORCE=1 bash ./scripts/install.sh /path/to/your-project

Both installers finish prompting and generate the customized configuration in a temporary staging directory before creating or changing the target .opencode. They copy a fixed allowlist of template files and directories, excluding OpenCode-generated node_modules, package manifests, lockfiles, and local .gitignore state. The shipped JSONC files intentionally remain valid strict JSON so PowerShell, Node.js, and Python can customize them without an extra parser dependency. Staging is cleaned on success or error. Force mode then merges and overwrites matching template files; it does not delete extra files in the target .opencode directory.

Both installers also copy the three .cmd launchers to the destination project root, alongside .opencode, and include their helper inside .opencode. Existing root launcher files require force mode; directories or links occupying those paths are refused even in force mode. Root launchers come from this repository's template/; OPENCODE_TEMPLATE_SOURCE, when used, overrides only the .opencode payload and must include its helper.

Force installation stops before target changes if a full Orchestrator prompt exists at .opencode/oh-my-opencode-slim/orchestrator.md or .opencode/oh-my-opencode-slim/generic-openai/orchestrator.md. Older templates shipped the first path, and customized replacements have the same precedence. Review and back up/rename that replacement before retrying; use orchestrator_append.md for project-specific additions to the bundled scheduler prompt. The installer does not delete these user-owned files automatically. User-level and other preset-specific full prompt overrides can also supersede the bundled prompt and must be inspected separately.

Windows Desktop Profile Launchers

After installation, the destination layout is:

your-project/
  opencode-balanced.cmd
  opencode-performance.cmd
  opencode-maxed.cmd
  .opencode/
    launch-desktop.mjs
    opencode.jsonc
    oh-my-opencode-slim.jsonc
    ...

Install a current Node.js LTS release on PATH (the helper requires Node.js 18 or newer) and OpenCode Desktop on Windows. Fully quit Desktop, then double-click the desired root launcher. Once Desktop opens, select that workspace and create a new session; an existing conversation may retain its previous model selection.

Each launcher applies the named profile's stock model and effort assignments to both project configs before starting Desktop. This replaces previous interactive/custom model choices for the template's 22 routes and two defaults. Prompts, skills, MCP settings, permissions, fallback configuration, other presets, and unrelated agents remain unchanged. Missing template routes or a project that explicitly disables OpenAI produce an error rather than a partial rewrite.

Workspace paths are resolved relative to the helper's installed location, not the current terminal directory or the original template checkout. You can move the whole installed workspace, including .opencode and the root launchers. Preset and council keys are read from the target Slim config, so renamed keys work too. The child receives the target's selected runtime preset, background-subagent support, and EXA flags; no user/machine environment or global config is edited.

Desktop is discovered under %LOCALAPPDATA%\Programs\OpenCode or %ProgramFiles%\OpenCode. For a different installation, set OPENCODE_DESKTOP_EXECUTABLE in the launching process to the absolute path of OpenCode.exe. The helper refuses an already-running instance of that executable, never terminates processes, and serializes competing launches within a workspace. Always close all Desktop installations first so single-instance forwarding cannot reuse a different old instance.

Validate the configuration without modifying files or starting Desktop:

.\opencode-balanced.cmd --check
.\opencode-performance.cmd --check
.\opencode-maxed.cmd --check

--check needs Node and the installed configs, but not Desktop. It validates the local routing shape, not provider access or the fully merged live agent registry. On macOS/Linux, the installers also copy these Windows launchers; use the existing CLI launch instructions there. The helper's validation-only mode can be run directly with node .opencode/launch-desktop.mjs Maxed --check.

The helper stages both config outputs before replacing either file. Normal write/spawn errors restore files that still match the helper's output, preserving intervening edits. Abrupt termination is not an atomic two-file transaction: inspect both configs after an interrupted launch. If .opencode/.desktop-launch.lock remains after a crash, verify no launcher is running before removing that stale lock. Global/inline agent or plugin overrides can still affect effective routing; use the checks below and inspect the new Desktop session's actual model and effort.

Interactive Model Routing

The installer prompts for five model slots, in the following order, while preserving the selected profile's role-specific effort variants. The descriptions below list Balanced defaults; Performance uses Sol for the first three slots and Astra for the last two, while Maxed uses Astra for all five:

• primary: Sol for build, Plan, architecture, security, and council synthesis.
• balanced: Terra for orchestration, Fixer implementation, general work, synthesis, summaries, compaction, design, and normal review.
• utility: Luna for exploration, research, visual analysis, titles, and fast sanity checks.
• deep: Sol at max effort for the bounded deep-review council member only. It is a separate slot so customized installs can select another max-capable model.
• oracle: Astra at max effort for rare read-only reasoning and escalation. It is independent of both primary and deep; scripted interactive input must account for this fifth prompt.

Customization accepts only model IDs of the form openai/<model> with no internal whitespace. A custom choice replaces a model slot but retains the selected profile's effort variants, so every selected OpenAI model must support the variants used by that slot. Choosing Sol manually under Balanced does not activate Performance's effort changes.

Slot	Required efforts
primary	medium, high in Balanced/Performance; high in Maxed
balanced	medium, high; also low in Performance/Maxed
utility	none, low, medium in Balanced/Performance; low, medium in Maxed
deep	max
oracle	max

The openai/gpt-6-astra and openai/gpt-6-astra-fast IDs support low, medium, high, xhigh, and max in OpenCode 1.18.29, but not none. They are compatible with the primary, balanced, deep, and oracle slot efforts in every profile. Both installers reject these two Astra IDs for utility in Balanced and Performance before changing target files, including in force mode, because those profiles retain title effort none. Maxed explicitly uses title effort low, so Astra is accepted for its utility slot. Custom model choices do not silently change profile efforts. Other custom IDs still require checking opencode models openai --verbose against the table; the installer is not a general provider-capability validator.

Skip prompts and keep defaults for automation:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -ProjectPath C:\path\to\your-project -NonInteractive

bash ./scripts/install.sh /path/to/your-project --non-interactive

You can set OPENCODE_BIN for either installer if your OpenCode binary has a custom name. When interactive customization is accepted, both installers query that binary for models openai; provider customization is not supported.

Validate After Install

Run the repository's dependency-free config, native-installer, and portable-launcher checks first:

node ./scripts/test.mjs

The launcher suite covers renamed presets, separate and relocated workspaces, paths with spaces and shell punctuation, custom Desktop paths, child-only environment correction, refusal without writes, and spawn-error rollback. It uses a mocked Desktop launch and makes no inference requests. Run it independently with node --test ./scripts/launch-desktop.test.mjs.

To verify all three profiles' effective model/effort assignments, including inherited overrides and host catalog support, run:

node ./scripts/test.mjs --opencode

This optional check requires opencode (opencode.cmd on Windows), loads the pinned plugin with the project preset, and makes no inference requests. It does not print the full resolved configuration. A routing mismatch identifies the affected agent; review inherited OMOS agents and core agent settings rather than changing user-level configuration blindly. Passing does not prove API account access or runtime tool behavior.

On Windows with Git Bash, use node ./scripts/test.mjs --bash to exercise the Bash installer as well. Set BASH_BIN to its executable path if bash is not on PATH. Bash selects Node when available, otherwise Python 3. Use node ./scripts/test.mjs --bash --python to hide Node discovery inside the installer and exercise its Python fallback; Python 3 must be installed. Add --opencode to either command for effective-routing checks. The suites cover all three profiles, custom model choices, invalid profile rejection, Astra utility compatibility, force switching back to Performance and Balanced, and permission preservation.

Run these from the target project:

opencode debug config
opencode debug agent orchestrator
opencode debug skill
npx --yes oh-my-opencode-slim@2.2.17 doctor

In PowerShell, use opencode.cmd and npx.cmd for these commands if execution policy blocks the .ps1 wrappers. Apply the project-scoped environment variables above before plugin-aware checks. Debug commands can expose merged user configuration; inspect locally and redact sensitive values before sharing output.

Run a live model smoke test if desired; it consumes Codex subscription quota or API usage according to the configured connection:

opencode run --agent build -m openai/gpt-5.6-sol "Respond with exactly: ROUTING_OK_SOL"
opencode run --agent build -m openai/gpt-5.6-terra "Respond with exactly: ROUTING_OK_TERRA"
opencode run --agent build -m openai/gpt-5.6-luna "Respond with exactly: ROUTING_OK_LUNA"
opencode run --agent build -m openai/gpt-5.6-sol --variant max "Respond with exactly: ROUTING_OK_SOL_MAX"
opencode run --agent build -m openai/gpt-6-astra --variant max "Respond with exactly: ROUTING_OK_ASTRA_MAX"

Launch with the required environment variables and restart any already-running OpenCode session after copying or editing config files. OpenCode loads config at startup.

Included Agents

• orchestrator: primary project coordinator.
• oracle: highest-capability read-only reasoning and escalation for unresolved high-risk questions; advises rather than implements.
• explorer: read-only repository discovery and code-path mapping.
• librarian: read-only external documentation and source research.
• fixer: bounded implementation without subagent delegation.
• designer: UI/UX implementation and review without subagent delegation.
• observer: read-only image, screenshot, PDF, and diagram analysis.
• council: explicit, higher-cost independent review from multiple perspectives; model diversity depends on the profile.
• code-reviewer: correctness, maintainability, regression, and diff review.
• repo-architect: architecture, module boundaries, migration planning, and tradeoffs.
• test-writer: test strategy, fixtures, edge cases, and regression coverage.
• security-reviewer: defensive review for auth, secrets, injection, unsafe IO, dependencies, and deployment risk.

Planning-Only Work

Use OpenCode's native Plan agent for a stricter planning-only workflow instead of asking the Orchestrator to plan and hoping it does not begin implementation. Plan may inspect the repository and delegate only to the read-only Explorer or Librarian; write-capable agents, OMOS mutators, and nested delegation remain blocked. Direct edits are restricted to OpenCode's native plan-file locations.

The template intentionally omits a global edit: "allow" rule. OpenCode already allows normal edits by default, while a later global allow can override the built-in Plan agent's edit denial. Secret-like file edits remain explicitly denied.

Treat Plan as a workflow guardrail, not a security sandbox. Native plan-file writes remain allowed, shell commands can still be approved, and permission enforcement depends on the installed host and plugins. Use OS-level read-only isolation when a strict filesystem boundary is required; configuration checks alone do not establish that boundary.

Safety Rules

The template defaults to dedicated file tools for normal coding work and asks before shell execution to protect common dangerous surfaces:

• Do not read or summarize secrets unless explicitly authorized in the current turn.
• Do not edit secret-bearing files.
• Do not place secrets or private code in librarian queries because enabled research MCPs send queries to remote services.
• Ask before publishing packages, pushing git branches, deploying infrastructure, touching Kubernetes, running production migrations, or broadcasting transactions.
• Keep security work defensive and scoped to repositories, systems, and targets you are authorized to review.

Upload To GitHub

If this folder is not already a git repo:

git init
git add .
git commit -m "Add generic OpenCode project config"

Create and push a private GitHub repo with GitHub CLI:

gh repo create opencode-openai-config-template --private --source . --remote origin --push

Change --private to --public only if you are sure the repo contains no private notes or project-specific details.

Future repository links should use https://github.com/<owner>/opencode-openai-config-template.