How to update and merge OAC? #208

gagbo · 2026-02-15T20:50:45Z

gagbo
Feb 15, 2026

Hello!

Thanks for this framework, I’m reluctantly looking into using AI more and having a clearly introspectable system to see and learn about prompting and setting up agents is really awesome!

I see that the development is still very active (which is cool), but I’m just wondering if there’s a recommended way of updating the setup after the initial install and few user tweaks? I haven’t found anything yet, so my current idea is to ask the "System Builder" agent to run the "OAC update workflow" which I added in a md file (the footer of the message)

It currently relies on chezmoi, and the fact that I can use git diff in my chezmoi directory to review changes 1 by 1, but I don’t know if there’s a better way. (Note: I haven’t tested the workflow yet)

Cheers,
Gerry

OAC Self-Update Workflow

Quick Reference

Purpose: Update OpenAgentsControl configuration from upstream while preserving user customizations

Key Principle: Human-in-the-loop at every critical step - no silent overwrites

Tools Required: chezmoi, git, curl, bash

Safety: ALWAYS show scripts before execution, ALWAYS confirm before destructive operations

Stage 1: Fetch and Review Upstream Installer

Prerequisites

chezmoi is installed and configured
git is available
Network access to GitHub

Process

Fetch installation script from upstream

curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh -o /tmp/oac-install.sh

CRITICAL: Display script for user review
- Read and display the full script content to user
- Use read tool on /tmp/oac-install.sh
- Summarize key actions the script will perform
- Highlight any potentially destructive operations
- MANDATORY: Wait for explicit user approval before proceeding
- Ask: "I've reviewed the install script. Do you approve running it? [y/N]"

Run installer non-interactively after approval

bash /tmp/oac-install.sh developer --install-dir ~/.config/opencode

Verify installation completed

ls -la ~/.config/opencode/agent/
ls -la ~/.config/opencode/context/

Checkpoint

Script fetched successfully
Script content shown to user
User explicitly approved execution
Installer completed without errors
~/.config/opencode contains updated files

Error Recovery

If curl fails: check network, try wget as fallback
If script approval denied: abort workflow, no changes made
If installer fails: check error output, may need to clear target directory first

Stage 2: Sync Target State to Source State

Process

Re-add opencode config to chezmoi source state
```
chezmoi re-add ~/.config/opencode
```
Navigate to chezmoi source directory
```
cd ~/.local/share/chezmoi
```
Verify changes were detected
```
git status --porcelain home/dot_config/opencode
```
Expected output shows:
- M = Modified files (upstream changes to existing files)
- A = Added files (new upstream files)
- D = Deleted files (files removed in upstream OR user customizations)
- ?? = Untracked files (new files not yet in git)

Get summary of changes

git diff --stat home/dot_config/opencode

Checkpoint

chezmoi re-add completed successfully
git status shows changes in home/dot_config/opencode
Change summary reviewed

Error Recovery

If chezmoi re-add fails: verify chezmoi is initialized, check permissions
If no changes detected: upstream may be identical to current config, workflow complete

Stage 3: Merge User Customizations with Upstream

Critical Understanding

IMPORTANT: Deleted files in git status include BOTH:

Old upstream code that was removed/renamed (safe to delete)
User customizations that should be preserved (must keep!)

The agent MUST help the user distinguish between these cases.

Process

Make paths portable across machines

Replace hardcoded home paths with portable ~/ notation:

cd ~/.local/share/chezmoi
find home/dot_config/opencode -type f \( -name "*.md" -o -name "*.jsonc*" \) -exec sed -i 's#/home/[^/]\+/#~/#g' {} \;

List all changed files for review

git diff --name-only home/dot_config/opencode

Interactive chunk-by-chunk review

For EACH file with changes, perform interactive review:

a. Show file-level summary first:
```
git diff --stat home/dot_config/opencode/<file>
```
b. For each diff hunk, present options:
- Display the hunk with context
- Explain what the change does (upstream addition, removal, modification)
- Ask user to choose:
  - [k]eep - Revert this chunk to HEAD (preserve user customization)
  - [a]ccept - Keep working tree change (accept upstream)
  - [s]kip - Defer decision on this file for later
  - [v]iew - Show more context around this change
c. Apply user decisions:
- For keep: Use git checkout -p or manual edit to restore HEAD version
- For accept: Leave working tree as-is
- Track skipped files for final review
Handle deleted files explicitly

List files marked as deleted:
```
git diff --name-only --diff-filter=D home/dot_config/opencode
```
For EACH deleted file:
- Show the file that would be deleted
- Determine if it's likely user customization (check for user-specific content)
- Ask: "File <filename> was removed upstream. This appears to be [user customization / old upstream code]. Keep your version? [y/N]"
- If keeping: git checkout HEAD -- home/dot_config/opencode/<file>

Decision Framework for Users

Help users decide with these guidelines:

Change Type	Likely Action	Reasoning
New agent files	Accept	New upstream features
Modified workflow files	Review carefully	May contain both improvements and user tweaks
Deleted navigation.md entries	Check if user-added	User additions should be kept
Path changes in context files	Accept	Upstream reorganization
Model configurations	Keep user version	User's model preferences
Custom commands	Keep	User customizations
AGENTS.md changes	Merge manually	Contains user-specific rules

Checkpoint

All files reviewed chunk-by-chunk
User customizations identified and preserved
Upstream improvements accepted where appropriate
Deleted files handled explicitly
No unreviewed changes remain

Error Recovery

If merge gets confusing: git checkout HEAD -- home/dot_config/opencode/ to start over
If specific file needs full reset: git checkout HEAD -- <specific-file>

Stage 4: Update Agent Model Configuration

Trigger Condition

Run this stage if ANY of these are true:

New agent files were added in upstream
User requests model configuration review
opencode.jsonc.tmpl was modified by upstream

Process

Detect new agents

cd ~/.local/share/chezmoi
git diff --name-only --diff-filter=A HEAD home/dot_config/opencode/agent/

For each new agent, extract metadata

Read the agent file to determine:
- Agent name (from filename and frontmatter)
- Agent mode (primary vs subagent)
- Agent purpose (from description)
- Recommended temperature (from frontmatter or content)

Present each new agent for approval

Display:

New Agent Detected: [AgentName]
Purpose: [description from file]
Mode: [primary/subagent]

Suggested model configuration:
- Work mode (useWorkModels=true): [suggested-model]
- Personal mode (useWorkModels=false): [suggested-model]

Add this agent to opencode.jsonc.tmpl? [y/N/custom]

Model selection guidelines

For Work Mode (useWorkModels=true):

Agent Mode	Recommended Models	Reasoning
Primary (orchestration)	`anthropic/claude-opus-4-6`	Highest accuracy for complex decisions
Primary (coding)	`anthropic/claude-opus-4-6`, `github/gpt-5`	Strong code generation
Subagent (fast tasks)	`anthropic/claude-haiku-4-5-latest`	Cost-effective for simple tasks
Subagent (code review)	`anthropic/claude-sonnet-4-5-latest`	Balance of speed and quality
Subagent (complex)	`github/gpt-5`	Good for multi-step reasoning

For Personal Mode (useWorkModels=false):

Agent Mode	Recommended Models	Reasoning
Primary (orchestration)	`anthropic/claude-opus-4-6`	Keep high accuracy for main agents
Primary (coding)	`mistral/devstral-2`	Cost-effective coding specialist
Subagent (fast tasks)	`mistral/mistral-small-latest`	Cheapest option
Subagent (code review)	`anthropic/claude-sonnet-4-5-latest`	Quality matters for reviews
Subagent (complex)	`anthropic/claude-haiku-4-5-latest`	Balance cost and capability

Research current model info if needed

If user asks or models seem outdated:
- Use WebFetch to check https://opencode.ai/models for current availability
- Check provider pricing pages for cost comparison
- Consider free tiers available on opencode platform

Update opencode.jsonc.tmpl

For each approved agent, add entries in BOTH template branches:

{{- if .flags.useWorkModels }}
    "[AgentName]": {
      "mode": "[primary/subagent]",
      "model": "[work-model]",
      "temperature": [0.0-0.4]
    },
{{- else }}
    "[AgentName]": {
      "mode": "[primary/subagent]",
      "model": "[personal-model]",
      "temperature": [0.0-0.4]
    },
{{- end }}

Checkpoint

All new agents identified
Each new agent reviewed with user
Model assignments confirmed
opencode.jsonc.tmpl updated correctly
Template syntax validated (no JSON errors)

Error Recovery

If template syntax breaks: restore from git HEAD, retry carefully
If model not available: use fallback from same provider tier

Stage 5: Final Review and Commit

Process

Show final change summary

cd ~/.local/share/chezmoi
git diff --stat home/dot_config/opencode

Show full diff for final review
```
git diff home/dot_config/opencode
```
Summarize for user:
- Number of files modified
- Number of files added
- Number of files deleted
- Key changes in each category
Confirm commit

Ask: "Ready to commit these changes to chezmoi? [y/N]"

Stage and commit

git add home/dot_config/opencode/
git commit -m "feat(opencode): update OAC configuration from upstream

- Updated from OpenAgentsControl upstream
- Preserved user customizations in: [list key preserved files]
- Added new agents: [list if any]
- Updated model configurations: [list if any]"

Optional: Apply to target immediately

Ask: "Apply changes to ~/.config/opencode now? [y/N]"
```
chezmoi apply
```

Checkpoint

Final diff reviewed by user
User approved commit
Changes committed successfully
Optional: Changes applied to target

Rollback Procedure

If the update causes issues after completion:

Revert Uncommitted Changes

cd ~/.local/share/chezmoi
git checkout HEAD -- home/dot_config/opencode/

Revert Committed Changes

cd ~/.local/share/chezmoi
git revert HEAD  # Creates new commit that undoes changes
# OR
git reset --hard HEAD~1  # Removes commit entirely (use with caution)

Re-apply Clean State

chezmoi apply

Full Reset to Known Good State

If all else fails:

Backup current ~/.config/opencode
Delete ~/.config/opencode
Re-run installer with desired profile
Manually restore critical customizations from backup

Automation Hints for Agents

Stage 1 Automation

Fetch script automatically
MUST show script content and wait for approval
Parse installer output for success/failure

Stage 2 Automation

Run chezmoi commands automatically
Parse git status output to categorize changes
Present summary to user

Stage 3 Automation

Run sed command automatically (safe transformation)
For each file: show diff, ask for decision, apply
Track decisions for commit message

Stage 4 Automation

Detect new agents automatically
Look up agent metadata from files
Present choices with recommendations
Apply approved changes to template

Stage 5 Automation

Generate commit message from tracked decisions
Stage and commit after approval
Optionally apply changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

How to update and merge OAC? #208

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

How to update and merge OAC? #208

Uh oh!

gagbo Feb 15, 2026

OAC Self-Update Workflow

Quick Reference

Stage 1: Fetch and Review Upstream Installer

Prerequisites

Process

Checkpoint

Error Recovery

Stage 2: Sync Target State to Source State

Process

Checkpoint

Error Recovery

Stage 3: Merge User Customizations with Upstream

Critical Understanding

Process

Decision Framework for Users

Checkpoint

Error Recovery

Stage 4: Update Agent Model Configuration

Trigger Condition

Process

Checkpoint

Error Recovery

Stage 5: Final Review and Commit

Process

Checkpoint

Rollback Procedure

Revert Uncommitted Changes

Revert Committed Changes

Re-apply Clean State

Full Reset to Known Good State

Automation Hints for Agents

Stage 1 Automation

Stage 2 Automation

Stage 3 Automation

Stage 4 Automation

Stage 5 Automation

Related

Replies: 0 comments

gagbo
Feb 15, 2026