Claude Copilot v2.0.0 Upgrade Guide

Claude Copilot v2.0.0 Upgrade Guide

Overview

This guide walks you through upgrading to Claude Copilot v2.0.0, which introduces parallel stream orchestration, WebSocket event streaming, and a paradigm shift to multi-session agent coordination.

Estimated Time: 15-20 minutes Difficulty: Easy (backwards compatible) Breaking Changes: None

Table of Contents

1. Pre-Upgrade Checklist
2. Standard Upgrade (Recommended)
3. Manual Upgrade
4. Post-Upgrade Verification
5. New Features Configuration
6. Troubleshooting
7. Rollback Instructions

Pre-Upgrade Checklist

Before upgrading, verify your current setup:

1. Check Current Version

cd ~/.claude/copilot
git log --oneline -1

Expected output:

• If on v1.7.0 or v1.7.1: Ready to upgrade
• If on v1.6.x or earlier: Review CHANGELOG.md for intermediate changes

2. Commit Uncommitted Work

# In all project directories
git status
git add .
git commit -m "WIP: Pre-upgrade checkpoint"

3. Backup Current Configuration

# Backup MCP configuration
cp ~/.mcp/config.json ~/.mcp/config.json.backup

# Or backup project-level config
cp ~/your-project/.mcp.json ~/your-project/.mcp.json.backup

4. Check Node Version

node --version

Required: Node.js 18.0.0 or higher

5. Check Disk Space

df -h ~/.claude

Required: At least 500 MB free space

6. List Active Initiatives

# In Claude Code
claude
# Then query memory
initiative_get({ mode: "lean" })

Note any active initiatives - you'll resume these after upgrade.

Standard Upgrade (Recommended)

The standard upgrade uses the built-in /update-copilot and /update-project commands.

Step 1: Update Framework

# Navigate to Claude Copilot installation
cd ~/.claude/copilot

# Start Claude Code
claude

In Claude Code:

/update-copilot

What this does:

• Pulls latest changes from origin/main
• Rebuilds all MCP servers
• Updates global .claude/ directory
• Preserves your custom extensions

Expected output:

Updating Claude Copilot Framework

Current version: v1.7.1
Latest version: v1.8.0

Changes:
- Parallel stream orchestration
- WebSocket bridge
- Context recovery system
- v1.8 harness features

Pulling changes...
✓ Git pull complete

Rebuilding MCP servers...
✓ copilot-memory rebuilt
✓ skills-copilot rebuilt
✓ websocket-bridge installed

Framework updated successfully!

Next: Update your projects with /update-project

Step 2: Update Projects

For each project using Claude Copilot:

cd ~/your-project
claude

In Claude Code:

/update-project

What this does:

• Syncs .claude/ directory with latest framework
• Updates agents with new features
• Adds new commands (/orchestrate)
• Preserves project-specific customizations
• Updates .gitignore with orchestration directories

Expected output:

Updating Project with Claude Copilot v1.8.0

Files updated:
✓ .claude/agents/ (20 agents)
✓ .claude/commands/ (added orchestrate.md)
✓ .gitignore (added .claude/orchestrator/)

New features available:
- /orchestrate command
- Parallel stream execution
- Context recovery system

Update complete!

Step 3: Restart Claude Code

Close and reopen Claude Code to reload MCP server configurations.

# Close Claude Code
# Reopen in your project
cd ~/your-project
claude

Manual Upgrade

If /update-copilot is unavailable, follow these manual steps.

Step 1: Pull Latest Code

cd ~/.claude/copilot
git pull origin main

Expected output:

remote: Enumerating objects: 847, done.
remote: Counting objects: 100% (847/847), done.
remote: Compressing objects: 100% (523/523), done.
remote: Total 847 (delta 324), reused 847 (delta 324)
Receiving objects: 100% (847/847), 1.23 MiB | 2.45 MiB/s, done.
Resolving deltas: 100% (324/324), done.

Step 2: Rebuild MCP Servers

# Memory Copilot
cd ~/.claude/copilot/mcp-servers/copilot-memory
npm install
npm run build

# Skills Copilot
cd ../skills-copilot
npm install
npm run build

# WebSocket Bridge (NEW)
cd ../websocket-bridge
npm install
npm run build

Step 3: Update Project Files

For each project:

cd ~/your-project

# Copy new command
cp ~/.claude/copilot/.claude/commands/orchestrate.md .claude/commands/

# Update agents (all 12 files)
cp -r ~/.claude/copilot/.claude/agents/ .claude/

# Update .gitignore
echo "" >> .gitignore
echo "# Claude Copilot orchestration" >> .gitignore
echo ".claude/orchestrator/" >> .gitignore

Step 4: Verify Installation

# Check MCP servers built successfully
ls -la ~/.claude/copilot/mcp-servers/*/dist/

# Should see dist/ directories for:
# - copilot-memory
# - skills-copilot
# - websocket-bridge

Post-Upgrade Verification

Verify the upgrade completed successfully.

1. Check Framework Version

cd ~/.claude/copilot
git log --oneline -1

Expected: Commit from January 8, 2026 or later

2. Verify MCP Servers

In Claude Code:

claude
# Check available tools

New CLI commands should be available:

• tc stream list --json, tc stream get <id> --json
• tc handoff --from <a> --to <b> --task <id> --context "..." --json
• tc log --task <id> --json

3. Test New Commands

claude

In Claude Code:

/orchestrate

Expected output:

## No Active Initiative

Cannot generate orchestration without an active initiative.

To create an initiative:
1. Run /protocol
2. Work with @agent-ta to create a PRD with tasks
3. Ensure tasks are organized into streams

This confirms the /orchestrate command is installed.

4. Verify Quality Gates

Create a test quality gates config:

cat > .claude/quality-gates.json << 'EOF'
{
  "version": "1.0",
  "defaultGates": ["tests_pass"],
  "gates": {
    "tests_pass": {
      "name": "tests_pass",
      "description": "Tests must pass",
      "command": "echo 'Tests passed'",
      "expectedExitCode": 0
    }
  }
}
EOF

Quality gates should now run automatically on task completion.

5. Test tc CLI (Optional)

If you want to verify task management is working:

tc --help
tc task list --json

New Features Configuration

Configure new features introduced in v1.8.0.

1. Enable Orchestration

Prerequisites:

• tmux installed: brew install tmux (macOS) or apt install tmux (Linux)
• Python 3.8+: python3 --version
• tc CLI installed and in PATH

Usage:

claude
/protocol
# Create a PRD with multiple streams via @agent-ta

/orchestrate generate
# Generates scripts in .claude/orchestrator/

# Outside Claude Code:
python3 .claude/orchestrator/start-streams.py

2. Enable WebSocket Bridge (Optional)

For real-time event streaming to UIs or dashboards:

cd ~/.claude/copilot/mcp-servers/websocket-bridge

# Create .env file
cat > .env << EOF
JWT_SECRET=your-random-secret-key-here
WORKSPACE_ID=your-workspace-id
WS_PORT=8765
POLL_INTERVAL=100
EOF

# Start bridge
npm start

Test connection:

const jwt = require('jsonwebtoken');
const WebSocket = require('ws');

const token = jwt.sign(
  { initiativeId: 'INIT-xxx' },
  'your-random-secret-key-here',
  { expiresIn: '24h' }
);

const ws = new WebSocket(`ws://localhost:8765?token=${token}`);
ws.on('message', (data) => {
  console.log('Event:', JSON.parse(data));
});

3. Configure Quality Gates

Create .claude/quality-gates.json in your project:

Minimal (tests only):

{
  "version": "1.0",
  "defaultGates": ["tests_pass"],
  "gates": {
    "tests_pass": {
      "name": "tests_pass",
      "description": "Tests must pass",
      "command": "npm test",
      "expectedExitCode": 0
    }
  }
}

Comprehensive (tests, lint, build):

{
  "version": "1.0",
  "defaultGates": ["tests_pass", "lint_clean", "build_success"],
  "gates": {
    "tests_pass": {
      "name": "tests_pass",
      "description": "All tests pass",
      "command": "npm test",
      "expectedExitCode": 0,
      "timeout": 300000
    },
    "lint_clean": {
      "name": "lint_clean",
      "description": "No linting errors",
      "command": "npm run lint",
      "expectedExitCode": 0
    },
    "build_success": {
      "name": "build_success",
      "description": "Build succeeds",
      "command": "npm run build",
      "expectedExitCode": 0,
      "timeout": 120000
    }
  }
}

4. Clean Up Legacy Streams (v1.7.1 Migration)

If upgrading from pre-v1.7.1, clean up legacy streams:

# Archive old streams via the tc CLI or by re-running /orchestrate generate
# which automatically archives previous streams
tc stream list --json

What this does:

• Archives all streams from previous initiatives
• Prevents stream pollution when using /continue
• One-time operation only needed after upgrade

5. Configure Context Recovery (Optional)

For orchestration with auto-recovery, edit generated config:

.claude/orchestrator/orchestrate-config.json:

{
  "version": "1.0",
  "generatedAt": "...",
  "initiative": { ... },
  "apiEndpoint": "http://127.0.0.1:9090",
  "streams": [ ... ],
  "executionPlan": { ... },
  "contextRecovery": {
    "stallTimeoutMinutes": 10,
    "autoRecoveryEnabled": true,
    "maxRecoveryAttempts": 3
  }
}

Troubleshooting

Issue: /update-copilot command not found

Cause: Old version of framework Solution: Use Manual Upgrade instead

Issue: MCP servers fail to build

Symptom:

npm ERR! Build failed

Solution:

# Clear node_modules and rebuild
cd ~/.claude/copilot/mcp-servers/copilot-memory
rm -rf node_modules package-lock.json
npm install
npm run build

# Repeat for skills-copilot

Issue: /orchestrate command not available

Cause: Project files not updated Solution:

cd ~/your-project
cp ~/.claude/copilot/.claude/commands/orchestrate.md .claude/commands/

Restart Claude Code.

Issue: Quality gates not running

Cause: Invalid configuration or missing file Solution:

# Validate JSON syntax
cat .claude/quality-gates.json | jq

# If error, fix JSON syntax
# Ensure gates match task metadata

Issue: WebSocket bridge fails to start

Symptom:

Error: WORKSPACE_ID required

Solution:

# Get workspace ID
ls ~/.claude/tasks/
# Use directory name as WORKSPACE_ID

# Set in .env
echo "WORKSPACE_ID=<directory-name>" >> .env

Issue: Orchestration script fails

Symptom:

ModuleNotFoundError: No module named 'requests'

Solution:

pip3 install requests

# Verify
python3 -c "import requests; print('OK')"

Issue: tmux not found

Symptom:

tmux: command not found

Solution:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Fedora/CentOS
sudo dnf install tmux

Issue: Tests fail after upgrade

Symptom: Existing tests fail that previously passed

Solution:

# Clear test cache
npm run test -- --clearCache

# Rebuild
npm run build

# Run tests
npm test

If tests still fail, review changes in CHANGELOG.md for breaking changes (there should be none, but verify).

Issue: Agent performance seems slower

Cause: New validation overhead Solution:

• First upgrade is slower due to database migrations
• Subsequent runs are normal speed
• Disable quality gates temporarily if needed: metadata: { qualityGates: [] }

Rollback Instructions

If you encounter critical issues, rollback to previous version.

Step 1: Identify Previous Version

cd ~/.claude/copilot
git log --oneline -10

Find the commit for v1.7.1 or your previous version.

Step 2: Rollback Framework

cd ~/.claude/copilot

# Rollback to specific commit
git reset --hard <commit-hash>

# Or rollback to specific tag
git checkout v1.7.1

Step 3: Rebuild MCP Servers

cd mcp-servers/copilot-memory && npm install && npm run build
cd ../skills-copilot && npm install && npm run build

Step 4: Restore Project Files

cd ~/your-project

# Remove new files
rm .claude/commands/orchestrate.md
rm -rf .claude/orchestrator/

# Restore agents from backup
git checkout HEAD .claude/agents/

Step 5: Restore Configuration

# Restore MCP config
cp ~/.mcp/config.json.backup ~/.mcp/config.json

# Or restore project config
cp ~/your-project/.mcp.json.backup ~/your-project/.mcp.json

Step 6: Restart Claude Code

Close and reopen Claude Code.

Step 7: Verify Rollback

cd ~/.claude/copilot
git log --oneline -1

Should show your previous version.

Migration Notes

Database Migrations

Task database automatically migrates on first run:

• No data loss: Existing tasks preserved
• Automatic: No manual intervention needed

Memory Schema

Memory Copilot database remains compatible. New agent_improvement type is additive.

Configuration Changes

No breaking changes to:

• .mcp.json format
• CLAUDE.md structure
• Agent frontmatter schema
• Tool signatures

New optional configs:

• .claude/quality-gates.json (optional)
• .claude/orchestrator/ (generated on-demand)
• contextRecovery in orchestration config (optional)

Getting Help

If you encounter issues not covered in this guide:

1. Check Logs:

   # MCP server logs
   tail -f ~/.claude/logs/copilot-memory.log
   

2. Search Issues:

   • GitHub Issues

3. Ask Community:

   • GitHub Discussions

4. File Bug Report:

   • Include version: git log --oneline -1
   • Include error messages
   • Include steps to reproduce

Next Steps

After successful upgrade:

1. Explore New Features:

   • Try /orchestrate with a multi-stream PRD
   • Set up quality gates for your project
   • Test activation modes (quick, thorough, analyze)

2. Read Documentation:

   • Orchestration Guide
   • Enhancement Features
   • WebSocket Bridge

3. Update Team:

   • Share upgrade guide with team members
   • Configure shared quality gates
   • Set up orchestration for large initiatives

4. Provide Feedback:

   • Report bugs or issues
   • Suggest improvements
   • Share success stories

Welcome to Claude Copilot v1.8.0!

Enjoy parallel stream orchestration, real-time monitoring, and enhanced agent reliability.