feat: add worktreeOpencodeConfig for per-loop opencode config (#63)

* feat: add worktreeOpencodeConfig for per-loop opencode config

* refactor: protect forge-written opencode.jsonc from loop commits

Author: chriswritescode-dev

docs/configuration.md

@@ -50,6 +50,7 @@ Default log path: `~/.local/share/opencode/forge/logs/forge.log` or `$XDG_DATA_H
 | `loop.stallTimeoutMs` | `60000` | Stall watchdog timeout in milliseconds. |
 | `loop.maxConsecutiveStalls` | `5` | Consecutive stalls before terminating with `stall_timeout`. `0` disables stall termination. |
 | `loop.allowExternalDirectories` | unset | Absolute host directories that loop, audit, and post-action sessions may read despite worktree isolation. |
+| `loop.worktreeOpencodeConfig` | unset | Inline [opencode config](https://opencode.ai/config.json) written as `opencode.jsonc` into each freshly created loop worktree. Enables per-loop customization (MCP servers, model overrides, etc.). Skip-if-exists — never overwrites a committed `opencode.json`/`opencode.jsonc`. The written file is git-excluded to keep it out of loop commits. |
 
 ### Worktree Logging
 
@@ -86,6 +87,38 @@ Example:
 }
 ```
 
+### Worktree Opencode Config
+
+`loop.worktreeOpencodeConfig` writes an inline opencode config file (`opencode.jsonc`) at the root of each freshly created loop worktree. This enables per-loop customization — primarily MCP servers — without modifying the host config or polluting loop commits.
+
+The config is written only when:
+- The worktree has no existing `opencode.json` or `opencode.jsonc` (committed configs are never overwritten)
+- The value is a non-empty object
+
+The written file is added to the worktree's git exclude so it never appears in `git status` or loop commits.
+
+Notes:
+- The written file is ephemeral. Forge deletes its own `opencode.jsonc` before any teardown commit (and the whole worktree is removed on completion), so it can never land in loop history — even if the git-exclude write failed. A repository-tracked `opencode.jsonc` is never deleted (forge did not write it). Because the file is removed at teardown, a restarted loop is rewritten from the current `loop.worktreeOpencodeConfig`, so edits take effect on the next run.
+- MCP servers declared here run as **host** processes from the worktree directory. When [Sandbox](sandbox.md) is enabled, only `bash`/`glob`/`grep` execute inside the container; the MCP commands themselves are not container-isolated.
+
+Example — expose Chrome DevTools MCP inside every loop:
+
+```jsonc
+{
+  "loop": {
+    "worktreeOpencodeConfig": {
+      "mcp": {
+        "chrome-devtools": {
+          "type": "local",
+          "command": ["npx", "chrome-devtools-mcp@latest", "--isolated"],
+          "enabled": true
+        }
+      }
+    }
+  }
+}
+```
+
 ## Group Launch
 
 `groupLaunch` configures parallel feature orchestration (see the [`launch-group`](tools.md#group-tools) tool).

docs/loop-system.md

@@ -187,6 +187,7 @@ Benefits of worktree isolation:
 - Isolation from ongoing development
 - Safe to experiment without affecting main branch
 - Branch preserved for later review/merge
+- Per-loop customization via `loop.worktreeOpencodeConfig` — inject MCP servers and other [opencode config](https://opencode.ai/config.json) into each worktree without host config changes or commit pollution (see [Configuration Reference](configuration.md#worktree-opencode-config))
 
 ## Sandbox Integration
 

forge-config.jsonc

@@ -63,6 +63,15 @@
     // identical container path so absolute temp paths match host<->container. Created on startup
     // if missing. Defaults to "/tmp/oc-forge".
     // "tmpDir": "/tmp/oc-forge"
+    //
+    // Inline opencode config written as opencode.jsonc into each loop worktree (skip-if-exists;
+    // never overwrites a committed opencode.json/opencode.jsonc). Primarily for enabling per-loop
+    // MCP servers. The written file is git-excluded so it never enters loop commits.
+    // "worktreeOpencodeConfig": {
+    //   "mcp": {
+    //     "my-server": { "type": "local", "command": ["npx", "some-mcp-server"], "enabled": true }
+    //   }
+    // }
   },
 
   // Max loops from one group running concurrently. Also bounds concurrent planning passes. Default 3.

src/index.ts

@@ -300,6 +300,7 @@ export function createForgePlugin(config: PluginConfig): Plugin {
         sandboxManager,
         gitService: defaultGitService,
         getTeardownContext: (loopName) => pendingTeardowns.get(loopName),
+        worktreeOpencodeConfig: config.loop?.worktreeOpencodeConfig,
       }))
       logger.log(`Registered forge workspace adapter (worktrees under ${join(dataDir, 'worktrees')})`)
     }

src/types.ts

@@ -74,6 +74,15 @@ export interface LoopConfig {
    * Defaults to `/tmp/oc-forge`. The directory is created on startup if missing.
    */
   tmpDir?: string
+  /**
+   * Inline opencode config object written verbatim as `opencode.jsonc` at the root of each
+   * freshly created loop worktree, enabling per-loop opencode customization (primarily MCP
+   * servers, e.g. `{ "mcp": { ... } }`). Written only when the worktree has no existing
+   * `opencode.json`/`opencode.jsonc` (committed configs are never overwritten). The written file
+   * is added to the worktree's git exclude so it never enters loop commits. An empty object or
+   * omission disables the behavior.
+   */
+  worktreeOpencodeConfig?: Record<string, unknown>
 }
 
 /**

src/utils/git-service.ts

@@ -9,6 +9,8 @@ export interface GitResult {
 
 export interface GitService {
   addAll(cwd: string): GitResult
+  /** True when `path` (file or directory) is tracked by git in `cwd`. */
+  isPathTracked(cwd: string, path: string): boolean
   statusPorcelain(cwd: string): GitResult
   commit(cwd: string, message: string): GitResult
   isInsideWorkTree(cwd: string): boolean
@@ -34,6 +36,11 @@ export function createGitService(): GitService {
       return runGit(['add', '-A'], cwd)
     },
 
+    isPathTracked(cwd: string, path: string): boolean {
+      const r = runGit(['ls-files', '--', path], cwd)
+      return r.ok && r.stdout.trim().length > 0
+    },
+
     statusPorcelain(cwd: string): GitResult {
       return runGit(['status', '--porcelain'], cwd)
     },

src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.5.0-beta.9'
+export const VERSION = '0.5.0'

src/workspace/forge-adapter.ts

@@ -1,12 +1,13 @@
 import { join } from 'path'
 import { mkdir } from 'fs/promises'
-import { existsSync, readFileSync, appendFileSync } from 'fs'
+import { existsSync, readFileSync, appendFileSync, rmSync } from 'fs'
 import type { WorkspaceAdapter, WorkspaceInfo } from '@opencode-ai/plugin'
 import type { Logger } from '../types'
 import type { SandboxManager } from '../sandbox/manager'
 import { forgeBranchName, forgeWorktreeDir, forgeWorktreeSlug } from './forge-naming'
 import { cleanupLoopWorktree } from '../utils/worktree-cleanup'
 import { defaultGitService, type GitService } from '../utils/git-service'
+import { writeWorktreeOpencodeConfig, WORKTREE_OPENCODE_CONFIG_FILENAME } from './worktree-opencode-config'
 
 
 /**
@@ -38,6 +39,8 @@ export interface ForgeAdapterDeps {
   getTeardownContext?: TeardownContextProvider
   /** Inject a custom GitService (defaults to real git if omitted). */
   gitService?: GitService
+  /** Inline opencode config written as opencode.jsonc into each worktree (skip-if-exists). */
+  worktreeOpencodeConfig?: Record<string, unknown>
 }
 
 const DEFAULT_TEARDOWN_CONTEXT: TeardownContext = {
@@ -48,7 +51,7 @@ const DEFAULT_TEARDOWN_CONTEXT: TeardownContext = {
 }
 
 export function createForgeWorkspaceAdapter(deps: ForgeAdapterDeps): WorkspaceAdapter {
-  const { dataDir, logger, sandboxManager, getTeardownContext, gitService: gitServiceOpt } = deps
+  const { dataDir, logger, sandboxManager, getTeardownContext, gitService: gitServiceOpt, worktreeOpencodeConfig } = deps
   const git = gitServiceOpt ?? defaultGitService
 
   function deriveLoopName(info: WorkspaceInfo): string {
@@ -65,6 +68,24 @@ export function createForgeWorkspaceAdapter(deps: ForgeAdapterDeps): WorkspaceAd
     return dir
   }
 
+  function addToGitExclude(directory: string, patterns: string[]): void {
+    if (patterns.length === 0) return
+    const excludeRes = git.revParseGitPath(directory, 'info/exclude')
+    if (!excludeRes.ok || !excludeRes.stdout) return
+    const excludeFile = excludeRes.stdout.trim()
+    try {
+      const content = existsSync(excludeFile) ? readFileSync(excludeFile, 'utf-8') : ''
+      const present = new Set(content.split('\n').map((l) => l.trim()))
+      const missing = patterns.filter((p) => !present.has(p))
+      if (missing.length > 0) {
+        appendFileSync(excludeFile, `\n${missing.join('\n')}\n`)
+        logger.log(`forge-adapter: added ${missing.join(', ')} to git exclude in ${directory}`)
+      }
+    } catch (err) {
+      logger.log(`forge-adapter: could not update git exclude: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
   function resolveLoopName(info: WorkspaceInfo): string {
     try {
       return deriveLoopName(info)
@@ -73,9 +94,30 @@ export function createForgeWorkspaceAdapter(deps: ForgeAdapterDeps): WorkspaceAd
     }
   }
 
+  /**
+   * Remove the forge-written `opencode.jsonc` before a teardown commit so the
+   * inline per-loop config never enters loop history. Only an untracked file is
+   * removed: when the repository already tracks an `opencode.jsonc`, forge never
+   * wrote it (skip-if-exists), so it is left untouched and its edits still commit.
+   * The worktree itself is torn down at teardown, so the removed file is not lost.
+   */
+  function removeForgeWrittenOpencodeConfig(directory: string): void {
+    const configPath = join(directory, WORKTREE_OPENCODE_CONFIG_FILENAME)
+    if (!existsSync(configPath)) return
+    if (git.isPathTracked(directory, WORKTREE_OPENCODE_CONFIG_FILENAME)) return
+    try {
+      rmSync(configPath, { force: true })
+      logger.log(`forge-adapter: removed forge-written ${WORKTREE_OPENCODE_CONFIG_FILENAME} before commit in ${directory}`)
+    } catch (err) {
+      logger.log(`forge-adapter: could not remove ${WORKTREE_OPENCODE_CONFIG_FILENAME}: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
   async function stepCommitChanges(loopName: string, directory: string, branchLabel: string, ctx: TeardownContext): Promise<void> {
     if (!ctx.doCommit || !existsSync(directory)) return
 
+    removeForgeWrittenOpencodeConfig(directory)
+
     try {
       const addResult = git.addAll(directory)
       if (!addResult.ok) {
@@ -193,23 +235,18 @@ export function createForgeWorkspaceAdapter(deps: ForgeAdapterDeps): WorkspaceAd
       }
       logger.log(`forge-adapter: created worktree ${info.directory} on branch ${info.branch}${branchExists ? ' (reused existing branch)' : ''}${reusedOrphan ? ' (after orphan cleanup)' : ''}`)
 
-      // Idempotently add .forge/ to git exclude so overflow/scratch files
-      // never enter loop commits.
-      if (info.directory) {
-        const excludeRes = git.revParseGitPath(info.directory, 'info/exclude')
-        if (excludeRes.ok && excludeRes.stdout) {
-          const excludeFile = excludeRes.stdout.trim()
-          try {
-            const content = existsSync(excludeFile) ? readFileSync(excludeFile, 'utf-8') : ''
-            if (!content.split('\n').some((l) => l.trim() === '.forge/')) {
-              appendFileSync(excludeFile, '\n.forge/\n')
-              logger.log(`forge-adapter: added .forge/ to git exclude in ${info.directory}`)
-            }
-          } catch (err) {
-            logger.log(`forge-adapter: could not update git exclude: ${err instanceof Error ? err.message : String(err)}`)
-          }
-        }
+      // Idempotently add .forge/ (overflow/scratch) and any forge-written
+      // opencode config to git exclude so they never enter loop commits.
+      const excludePatterns = ['.forge/']
+      const cfgResult = writeWorktreeOpencodeConfig({
+        directory: info.directory,
+        config: worktreeOpencodeConfig,
+        logger,
+      })
+      if (cfgResult.written) {
+        excludePatterns.push(WORKTREE_OPENCODE_CONFIG_FILENAME)
       }
+      addToGitExclude(info.directory, excludePatterns)
 
       if (sandboxManager) {
         try {

src/workspace/worktree-opencode-config.ts

@@ -0,0 +1,56 @@
+import { join } from 'path'
+import { existsSync, writeFileSync } from 'fs'
+import type { Logger } from '../types'
+
+/** Filename forge writes the inline opencode config to inside a worktree. */
+export const WORKTREE_OPENCODE_CONFIG_FILENAME = 'opencode.jsonc'
+
+/** Filenames opencode discovers as a project config; any present means "already configured". */
+const OPENCODE_CONFIG_FILENAMES = ['opencode.jsonc', 'opencode.json'] as const
+
+type WriteWorktreeOpencodeConfigReason = 'no-config' | 'exists' | 'written' | 'error'
+
+export interface WriteWorktreeOpencodeConfigInput {
+  /** Absolute worktree root directory. */
+  directory: string
+  /** Inline config object from `loop.worktreeOpencodeConfig` (may be undefined/empty). */
+  config: Record<string, unknown> | undefined
+  logger: Logger
+}
+
+export interface WriteWorktreeOpencodeConfigResult {
+  written: boolean
+  reason: WriteWorktreeOpencodeConfigReason
+  /** Path written when `written` is true; undefined otherwise. */
+  path?: string
+}
+
+/**
+ * Write the inline opencode config into a worktree as `opencode.jsonc`.
+ * Skip-if-exists (never overwrites a committed opencode config) and non-fatal:
+ * any failure is logged and reported via `reason: 'error'`, never thrown.
+ */
+export function writeWorktreeOpencodeConfig(
+  input: WriteWorktreeOpencodeConfigInput,
+): WriteWorktreeOpencodeConfigResult {
+  const { directory, config, logger } = input
+  if (!config || typeof config !== 'object' || Object.keys(config).length === 0) {
+    return { written: false, reason: 'no-config' }
+  }
+  const existing = OPENCODE_CONFIG_FILENAMES.find((name) => existsSync(join(directory, name)))
+  if (existing) {
+    logger.log(`worktree-opencode-config: ${existing} already present in ${directory}; skipping`)
+    return { written: false, reason: 'exists' }
+  }
+  const target = join(directory, WORKTREE_OPENCODE_CONFIG_FILENAME)
+  try {
+    writeFileSync(target, JSON.stringify(config, null, 2) + '\n', 'utf-8')
+    logger.log(`worktree-opencode-config: wrote ${WORKTREE_OPENCODE_CONFIG_FILENAME} in ${directory}`)
+    return { written: true, reason: 'written', path: target }
+  } catch (err) {
+    logger.log(
+      `worktree-opencode-config: failed to write ${WORKTREE_OPENCODE_CONFIG_FILENAME}: ${err instanceof Error ? err.message : String(err)}`,
+    )
+    return { written: false, reason: 'error' }
+  }
+}

test/helpers/fake-git.ts

@@ -6,6 +6,7 @@ const defaultOk: GitResult = { ok: true, status: 0, stdout: '', stderr: '' }
 export function createFakeGitService(overrides?: Partial<GitService>): GitService {
   return {
     addAll: vi.fn<[string], GitResult>(() => ({ ...defaultOk })),
+    isPathTracked: vi.fn<[string, string], boolean>(() => false),
     statusPorcelain: vi.fn<[string], GitResult>(() => ({ ...defaultOk })),
     commit: vi.fn<[string, string], GitResult>(() => ({ ...defaultOk })),
     isInsideWorkTree: vi.fn<[string], boolean>(() => true),