The Complete Guide to Maintaining Your Free AI Engineering Stack: OpenCode, OpenHands, ECC & Superpowers Updates

Table of Contents

1. The Hidden Cost of Free Software
2. Update Strategy Overview
3. OpenCode Updates

1. OpenHands Updates

1. ECC (Everything Claude Code) Updates

1. Superpowers Updates

1. OpenRouter: No Updates Needed

1. Update Summary Table
2. Monthly Maintenance Checklist
3. Troubleshooting Common Update Issues
4. Pro Tips for Stress-Free Maintenance

The Hidden Cost of Free Software

There's an old saying: "If the product is free, you are the product." But with open-source software, the cost isn't your data—it's your time.

Maintaining a stack of free, open-source tools requires attention. New features are added, bugs are fixed, and occasionally, breaking changes are introduced. Unlike commercial software with automatic updates and support contracts, you need to manage updates yourself.

But here's the good news: With a little structure and these battle-tested practices, maintenance becomes a 15-minute monthly ritual—not a daily headache.

Update Strategy Overview

Before diving into commands, understand the philosophy:

OpenCode Updates

Standard Update Command

If you installed via npm (which is recommended), updating is straightforward:

bashCopyopencode upgrade

This updates OpenCode to the latest stable version. You can also specify a specific version:

bashCopyopencode upgrade 1.2.0           # specific version
opencode upgrade --method npm    # explicit install method

What the Command Does

The opencode upgrade command:

1. Checks for the latest version from the npm registry
2. Downloads and installs the new version
3. Preserves your configuration and plugins
4. Restarts the CLI

Automatic Update Checks

OpenCode checks for updates on startup by default. You'll see a notification if a new version is available. You can disable this in your config:

jsonCopy{
  "update": {
    "check": false
  }
}

The Plugin Update Problem ⚠️

This is the most important thing to understand about OpenCode updates.

Once you install a plugin (like ECC or Superpowers), OpenCode caches the version and does not automatically check for updates. If you install a plugin today and the plugin developer releases a new version tomorrow, OpenCode will still use the old version.

The workaround (until the feature is implemented):

bashCopy# Clear the specific plugin cache
rm -rf ~/.cache/opencode/node_modules/plugin-name

# Or clear the entire package cache
rm ~/.cache/opencode/package.json

Then restart OpenCode—it will reinstall the latest versions.

Note: The OpenCode team is actively working on a proper opencode update plugins command. For now, manual cache clearing is the most reliable method.

Dependency Management

If you use pnpm or yarn instead of npm, ensure your package manager is up to date:

bashCopy# For pnpm
pnpm add -g opencode-ai@latest

# For yarn
yarn global add opencode-ai@latest

OpenHands Updates

CLI Tool Updates

The OpenHands CLI is now feature-complete and primarily maintained for stability. This means fewer updates, and when they do come, they're focused on bug fixes and compatibility.

If you installed via uv (the recommended method):

bashCopyuv tool upgrade openhands

If you installed via pip:

bashCopypip install --upgrade openhands

Checking Your Version

bashCopyopenhands --version

Main Platform Updates

If you're running the full OpenHands platform (the web UI and agent canvas), check for new releases on their GitHub Releases page.

The project is actively developed:

• v1.0.0 was released in late 2025
• v1.1.0 followed shortly after with significant improvements
• The team maintains a regular release cadence

Docker Users

If you run OpenHands via Docker, update by pulling the latest image:

bashCopydocker pull ghcr.io/openhands/openhands:latest
docker stop openhands
docker rm openhands
docker run -d --name openhands ghcr.io/openhands/openhands:latest

ECC (Everything Claude Code) Updates

Plugin Reinstallation

ECC is installed as an OpenCode plugin via the marketplace:

bashCopy/plugin install ecc@ecc

To update, run the same command—it will fetch the latest version from the marketplace. Since OpenCode has the plugin caching issue mentioned above, you may need to clear the cache first.

Complete update workflow:

bashCopy# 1. Clear the cache
rm ~/.cache/opencode/package.json

# 2. Reinstall ECC
/plugin install ecc@ecc

# 3. Run the setup wizard to ensure everything works
> Use the configure-ecc skill

ECC CLI Tools

ECC now includes a Rust-based control layer (ecc2/) with commands for managing your installation:

bashCopyecc list-installed    # check what's installed
ecc doctor            # diagnose issues
ecc repair            # repair broken installation

Key benefit: If your setup gets wiped (e.g., you clear the cache too aggressively), you don't need to start from scratch. Just run ecc doctor and ecc repair.

Version Tracking

ECC v2.0.0 was released in June 2026 with 261 skills and significant architectural changes. Follow their GitHub repository for release announcements.

Breaking Changes Warning ⚠️

Some ECC updates introduce breaking changes. Before upgrading, check the release notes for:

• Changes to skill syntax
• Deprecated features
• New configuration requirements

Superpowers Updates

Plugin Update Command

Superpowers is also an OpenCode plugin. To update, run:

bashCopy/plugin install superpowers@superpowers-marketplace

Release Cadence

Superpowers has a regular release schedule with a clear versioning strategy:

Automatic Updates

Superpowers updates are somewhat coding-agent dependent but often automatic. However, like other OpenCode plugins, you may need to clear the cache to force an update.

Release Notes

Check the RELEASE-NOTES.md file in the repository for detailed version history.

OpenRouter: No Updates Needed

OpenRouter is a cloud service, not a local installation. You don't need to update anything—new models and features are added server-side automatically.

What Changes

• New models: Added to the catalog without any action on your part
• Pricing: Updated by providers (OpenRouter passes through provider pricing)
• Features: New capabilities added to the API

API Key Rotation (Security Practice)

You should periodically rotate your API keys for security.

Step-by-step key rotation:

bashCopy# 1. Create a new key in your OpenRouter dashboard
# 2. Update your applications with the new key
# 3. Verify the new key works
# 4. Delete the old key

Both keys remain valid during the transition—there's no downtime.

Frequency: Quarterly is standard practice for API keys.

Pro tip: If you use BYOK (Bring Your Own Key) with OpenRouter, you can rotate your OpenRouter keys without touching your provider keys.

Update Summary Table

Monthly Maintenance Checklist

Set aside 15 minutes at the start of each month for maintenance:

Week 1: Check for Updates

• [ ] Visit each GitHub repository to check for new releases

Week 2: Test Updates

• [ ] Run opencode upgrade in a side project
• [ ] Verify that plugins still work
• [ ] Test OpenHands functionality

Week 3: Apply Updates

• [ ] Update plugins (clear cache + reinstall)
• [ ] Run ecc doctor to verify ECC installation
• [ ] Check that Superpowers skills are accessible

Week 4: Security & Cleanup

• [ ] Rotate OpenRouter API key (if quarterly)
• [ ] Clear npm cache if it's grown too large: npm cache clean --force
• [ ] Update your backup of config files

Troubleshooting Common Update Issues

Issue: Plugin Not Updating

Cause: OpenCode's plugin caching

Solution:

bashCopyrm ~/.cache/opencode/package.json
# Then reinstall the plugin
/plugin install ecc@ecc

Issue: "Command not found" After Update

Cause: PATH not updated or installation failed

Solution:

bashCopy# Check where it's installed
which opencode

# Reinstall
npm install -g opencode-ai@latest

Issue: Skills Not Showing

Cause: ECC or Superpowers not properly installed

Solution:

bashCopy# For ECC
/plugin install ecc@ecc
> Use the configure-ecc skill

# For Superpowers
/plugin install superpowers@superpowers-marketplace

Issue: OpenHands Not Responding

Cause: Docker container outdated or crashed

Solution:

bashCopydocker pull ghcr.io/openhands/openhands:latest
docker restart openhands

Issue: OpenRouter Model Not Found

Cause: Model ID changed or removed

Solution:

• Check the OpenRouter Models page
• Update your config with the correct model ID

Pro Tips for Stress-Free Maintenance

1. Subscribe to Release Notifications

Watch the GitHub repositories for each tool to get notified of new releases:

bashCopy# For GitHub CLI
gh repo watch opencode-ai/opencode
gh repo watch OpenHands/OpenHands
gh repo watch affaan-m/ECC
gh repo watch obra/superpowers

2. Test Updates in a Sandbox

Before updating in your main project, create a test directory:

bashCopymkdir ~/update-test
cd ~/update-test
# Run your update commands here first

3. Back Up Your Config

Before major updates, back up your configuration:

bashCopycp ~/.config/opencode/opencode.json ~/backups/opencode-backup-$(date +%Y%m%d).json

4. Join the Communities

Get real-time help and stay informed:

• ECC: Discord community
• OpenHands: Slack
• Superpowers: GitHub Discussions
• OpenCode: GitHub Issues

5. Automate with Scripts

Create a maintenance script (~/update-stack.sh):

bashCopy#!/bin/bash

echo "Updating OpenCode..."
opencode upgrade

echo "Clearing plugin cache..."
rm ~/.cache/opencode/package.json

echo "Reinstalling ECC..."
echo "/plugin install ecc@ecc" | opencode

echo "Reinstalling Superpowers..."
echo "/plugin install superpowers@superpowers-marketplace" | opencode

echo "Done!"

6. Adopt the "Ship and Forget" Mindset

Most of these tools are stable and don't require daily attention. A monthly check-in is sufficient—don't feel compelled to update every time a commit is pushed.

Conclusion

Maintaining a free, open-source AI engineering stack is not a burden—it's a skill. And like any skill, it gets easier with practice and the right tools.

What You've Learned

• ✅ How to update each component with specific commands
• ✅ The plugin caching issue in OpenCode and its workaround
• ✅ When to update (monthly) and when to test first
• ✅ How to troubleshoot common update problems
• ✅ Pro tips for automating and simplifying maintenance

Your 15-Minute Monthly Routine

1. Week 1: Check GitHub for new releases
2. Week 2: Test updates in a side project
3. Week 3: Apply updates to your main environment
4. Week 4: Rotate API keys and clean up

The result: A cutting-edge AI development stack that stays current, secure, and reliable—all for $0.

The future of AI-powered development is open-source. And with proper maintenance, it's sustainable too. 🚀