OpenWriterControle/docs/getting-started/installation.md

Install Script - Collision Handling

Overview

The install script now intelligently detects and handles file collisions when installing OpenCode components into an existing .opencode/ directory.

How It Works

1. Collision Detection

Before installing any files, the script:

• Scans all components you've selected to install
• Checks if any files already exist in your .opencode/ directory
• Groups collisions by type (agents, subagents, commands, tools, etc.)
• Presents a clear report of what would be overwritten

2. Installation Strategies

When collisions are detected, you get 4 options:

Option 1: Skip Existing (Recommended for Updates)

✅ Only install new files
✅ Keep ALL existing files unchanged
✅ Your customizations are preserved
✅ Safe for incremental updates

Use when:

• You've customized existing agents/commands
• You only want to add new components
• You're updating and want to keep your changes

Example:

Selected: 10 components
Existing: 5 files
Result: 5 new files installed, 5 existing files untouched

---

Option 2: Overwrite All (Use with Caution)

⚠️  Replace ALL existing files with new versions
⚠️  Your customizations will be LOST
⚠️  Requires confirmation (type 'yes')

Use when:

• You want the latest versions of everything
• You haven't made customizations
• You want to reset to defaults

Example:

Selected: 10 components
Existing: 5 files
Result: All 10 files installed (5 overwritten, 5 new)

---

Option 3: Backup & Overwrite (Safe Update)

✅ Backs up existing files to .opencode.backup.{timestamp}/
✅ Then installs new versions
✅ You can restore from backup if needed
✅ Best of both worlds

Use when:

• You want new versions but want to keep a backup
• You're not sure if you've customized files
• You want the ability to restore

Example:

Selected: 10 components
Existing: 5 files
Result: 
  - 5 files backed up to .opencode.backup.20251118-143022/
  - All 10 files installed (5 updated, 5 new)

Restore from backup:

# View backup
ls -la .opencode.backup.*/

# Restore specific file
cp .opencode.backup.20251118-143022/.opencode/agent/my-agent.md .opencode/agent/

# Restore all
rm -rf .opencode
mv .opencode.backup.20251118-143022/.opencode .opencode

---

Option 4: Cancel

❌ Exit without making any changes

Use when:

• You need to review what would be changed
• You want to manually backup first
• You're not ready to proceed

---

Example Session

$ bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/opencode-agents/main/install.sh) --developer

╔════════════════════════════════════════════════════════════════╗
║                                                                ║
║           OpenCode Agents Installer v1.0.0                    ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

▶ Checking dependencies...
✓ All dependencies found

▶ Fetching component registry...
✓ Registry fetched successfully

▶ Installation Preview

Profile: developer

Components to install (22 total):

Agents (4): task-manager codebase-agent image-specialist workflow-orchestrator
Subagents (6): reviewer tester documentation coder-agent build-agent codebase-pattern-analyst
Commands (6): test commit context clean optimize prompt-enhancer
Tools (2): env gemini
Contexts (2): essential-patterns project-context
Config (2): env-example readme

Proceed with installation? [Y/n]: y

▶ Preparing installation...

▶ Checking for file collisions...

⚠ Found 8 file collision(s):

  Agents (2):
    .opencode/agent/task-manager.md
    .opencode/agent/codebase-agent.md
  Subagents (3):
    .opencode/agent/subagents/reviewer.md
    .opencode/agent/subagents/tester.md
    .opencode/agent/subagents/coder-agent.md
  Commands (2):
    .opencode/command/test.md
    .opencode/command/commit.md
  Context (1):
    .opencode/context/core/essential-patterns.md

How would you like to proceed?

  1) Skip existing - Only install new files, keep all existing files unchanged
  2) Overwrite all - Replace existing files with new versions (your changes will be lost)
  3) Backup & overwrite - Backup existing files, then install new versions
  4) Cancel - Exit without making changes

Enter your choice [1-4]: 1

▶ Installing components...

✓ Installed agent: image-specialist
✓ Installed agent: workflow-orchestrator
ℹ Skipped existing: agent:task-manager
ℹ Skipped existing: agent:codebase-agent
ℹ Skipped existing: subagent:reviewer
ℹ Skipped existing: subagent:tester
✓ Installed subagent: documentation
ℹ Skipped existing: subagent:coder-agent
✓ Installed subagent: build-agent
✓ Installed subagent: codebase-pattern-analyst
ℹ Skipped existing: command:test
ℹ Skipped existing: command:commit
✓ Installed command: context
✓ Installed command: clean
✓ Installed command: optimize
✓ Installed command: prompt-enhancer
✓ Installed tool: env
✓ Installed tool: gemini
ℹ Skipped existing: context:essential-patterns
✓ Installed context: project-context
✓ Installed config: env-example
✓ Installed config: readme

✓ Installation complete!
  Installed: 14
  Skipped: 8

▶ Next Steps

1. Review the installed components in .opencode/
2. Copy env.example to .env and configure:
   cp env.example .env
3. Start using OpenCode agents:
   opencode

ℹ Documentation: https://github.com/darrenhinde/opencode-agents

---

Collision Report Details

The collision report groups files by type for easy review:

Category	Location	Description
Agents	.opencode/agent/*.md	Main orchestrator agents
Subagents	.opencode/agent/subagents/*.md	Specialized worker agents
Commands	.opencode/command/*.md	Slash commands
Tools	.opencode/tool/*/	Tool implementations
Plugins	.opencode/plugin/*.ts	Plugin integrations
Context	.opencode/context/**/*.md	Context files
Config	Root level files	Configuration files

---

Best Practices

For First-Time Installation

• No collisions will be detected
• All files install cleanly
• No strategy selection needed

For Updates (Adding New Components)

• Use Option 1 (Skip existing) - Safest choice
• Only new components are added
• Your customizations are preserved

For Full Refresh

• Use Option 3 (Backup & overwrite) - Safest for updates
• Get latest versions of everything
• Keep backup just in case

For Clean Slate

• Use Option 2 (Overwrite all) - Only if you're sure
• Resets everything to defaults
• Requires explicit confirmation

---

Technical Details

What Gets Checked

• All files in the selected components list
• Paths are resolved from registry.json
• Only actual file existence is checked (not content)

What Gets Backed Up (Option 3)

• Only files that would be overwritten
• Preserves directory structure
• Timestamped folder: .opencode.backup.YYYYMMDD-HHMMSS/

What Gets Skipped (Option 1)

• Any file that already exists
• Reported in "Skipped" count
• Logged with component type and ID

---

Troubleshooting

"I chose skip but want to update one file"

# Delete the specific file first
rm .opencode/agent/task-manager.md

# Run installer again with skip mode
# Only the deleted file will be reinstalled

"I chose overwrite by accident"

# If you chose Option 3 (backup), restore from backup:
cp .opencode.backup.*/path/to/file .opencode/path/to/file

# If you chose Option 2 (overwrite), check git history:
git checkout HEAD -- .opencode/

"I want to see what changed"

# If you have a backup:
diff .opencode/agent/my-agent.md .opencode.backup.*/agent/my-agent.md

# If you have git:
git diff .opencode/

"I want to merge changes manually"

# Use Option 3 to create backup
# Then manually merge:
vimdiff .opencode/agent/my-agent.md .opencode.backup.*/agent/my-agent.md

---

Future Enhancements

Potential improvements for future versions:

• Per-file selection (interactive mode)
• Diff preview before overwriting
• Smart merge for specific file types
• Version detection and upgrade paths
• Rollback command
• Dry-run mode (show what would happen)

---

Summary

The collision handling system provides:

✅ Safety - Never overwrites without asking
✅ Flexibility - Multiple strategies for different needs
✅ Transparency - Clear reporting of what will change
✅ Recoverability - Backup option for peace of mind
✅ Simplicity - Easy to understand and use

Choose the strategy that fits your situation, and install with confidence!