CHORUS/docs/comprehensive/commands/chorus.md

chorus - Deprecated Compatibility Wrapper

Binary: chorus Source: cmd/chorus/main.go Status: ⚠️ DEPRECATED (Removal planned in future version) Purpose: Compatibility wrapper redirecting users to new binaries

---

Deprecation Notice

⚠️ THIS BINARY IS DEPRECATED AND SHOULD NOT BE USED ⚠️

The chorus binary has been replaced by specialized binaries:

Old Binary	New Binary	Purpose
./chorus	./chorus-agent	Autonomous AI agents
./chorus	./chorus-hap	Human Agent Portal

Migration Deadline: This wrapper will be removed in a future version. All deployments should migrate to the new binaries immediately.

---

Overview

The chorus binary is a compatibility wrapper that exists solely to inform users about the deprecation and guide them to the correct replacement binary. It does not provide any functional capabilities and will exit immediately with an error code.

Why Deprecated?

Architectural Evolution:

The CHORUS system evolved from a single-binary model to a multi-binary architecture to support:

1. Human Participation: Enable humans to participate in agent networks as peers
2. Separation of Concerns: Different UIs for autonomous vs human agents
3. Specialized Interfaces: Terminal and web interfaces for humans
4. Clearer Purpose: Binary names reflect their specific roles

Old Architecture:

chorus (single binary)
└─→ All functionality combined

New Architecture:

chorus-agent (autonomous operation)
├─→ Headless execution
├─→ Automatic task acceptance
└─→ AI-driven decision making

chorus-hap (human interface)
├─→ Terminal interface
├─→ Web interface (planned)
└─→ Interactive prompts

---

Usage (Deprecation Messages Only)

Help Output

$ ./chorus --help
⚠️ CHORUS 0.5.0-dev - DEPRECATED BINARY

This binary has been replaced by specialized binaries:

🤖 chorus-agent    - Autonomous AI agent for task coordination
👤 chorus-hap      - Human Agent Portal for human participation

Migration Guide:
  OLD: ./chorus
  NEW: ./chorus-agent     (for autonomous agents)
       ./chorus-hap       (for human agents)

Why this change?
  - Enables human participation in agent networks
  - Better separation of concerns
  - Specialized interfaces for different use cases
  - Shared P2P infrastructure with different UIs

For help with the new binaries:
  ./chorus-agent --help
  ./chorus-hap --help

Version Output

$ ./chorus --version
CHORUS 0.5.0-dev (DEPRECATED)

Direct Execution (Error)

$ ./chorus
⚠️ DEPRECATION WARNING: The 'chorus' binary is deprecated!

This binary has been replaced with specialized binaries:
  🤖 chorus-agent - For autonomous AI agents
  👤 chorus-hap   - For human agent participation

Please use one of the new binaries instead:
  ./chorus-agent --help
  ./chorus-hap --help

This wrapper will be removed in a future version.

# Exit code: 1

Important: The binary exits with code 1 to prevent accidental use in scripts or deployments.

---

Source Code Analysis

File: cmd/chorus/main.go

Lines: 63 Package: main Imports:

• chorus/internal/runtime - Only for version constants

Purpose: Print deprecation messages and exit

Complete Source Breakdown

Lines 1-9: Package Declaration and Imports

package main

import (
    "fmt"
    "os"

    "chorus/internal/runtime"
)

Note: Minimal imports since binary only prints messages.

Lines 10-12: Deprecation Comment

// DEPRECATED: This binary is deprecated in favor of chorus-agent and chorus-hap
// This compatibility wrapper redirects users to the appropriate new binary

Documentation: Clear deprecation notice in code comments.

Lines 13-29: main() Function

func main() {
    // Early CLI handling: print help/version/deprecation notice
    for _, a := range os.Args[1:] {
        switch a {
        case "--help", "-h", "help":
            printDeprecationHelp()
            return
        case "--version", "-v":
            fmt.Printf("%s %s (DEPRECATED)\n", runtime.AppName, runtime.AppVersion)
            return
        }
    }

    // Print deprecation warning for direct execution
    printDeprecationWarning()
    os.Exit(1)
}

Flow:

1. CLI Argument Parsing (lines 15-24):

   • Check for --help, -h, help: Print help and exit 0
   • Check for --version, -v: Print version with deprecation tag and exit 0
   • No arguments or unknown arguments: Continue to deprecation warning

2. Deprecation Warning (lines 26-28):

   • Print warning message to stderr
   • Exit with code 1 (error)

Exit Codes:

Scenario	Exit Code	Purpose
--help	0	Normal help display
--version	0	Normal version display
Direct execution	1	Prevent accidental use
Unknown arguments	1	Force user to read deprecation message

Lines 31-52: printDeprecationHelp()

func printDeprecationHelp() {
    fmt.Printf("⚠️ %s %s - DEPRECATED BINARY\n\n", runtime.AppName, runtime.AppVersion)
    fmt.Println("This binary has been replaced by specialized binaries:")
    fmt.Println()
    fmt.Println("🤖 chorus-agent    - Autonomous AI agent for task coordination")
    fmt.Println("👤 chorus-hap      - Human Agent Portal for human participation")
    fmt.Println()
    fmt.Println("Migration Guide:")
    fmt.Println("  OLD: ./chorus")
    fmt.Println("  NEW: ./chorus-agent     (for autonomous agents)")
    fmt.Println("       ./chorus-hap       (for human agents)")
    fmt.Println()
    fmt.Println("Why this change?")
    fmt.Println("  - Enables human participation in agent networks")
    fmt.Println("  - Better separation of concerns")
    fmt.Println("  - Specialized interfaces for different use cases")
    fmt.Println("  - Shared P2P infrastructure with different UIs")
    fmt.Println()
    fmt.Println("For help with the new binaries:")
    fmt.Println("  ./chorus-agent --help")
    fmt.Println("  ./chorus-hap --help")
}

Content Breakdown:

Section	Lines	Purpose
Header	32-33	Show deprecation status with warning emoji
Replacement Info	34-36	List new binaries and their purposes
Migration Guide	37-41	Show old vs new commands
Rationale	42-46	Explain why change was made
Next Steps	47-51	Direct users to help for new binaries

Design: User-friendly guidance with:

• Clear visual indicators (emojis)
• Side-by-side comparison (OLD/NEW)
• Contextual explanations (Why?)
• Actionable next steps (--help commands)

Lines 54-63: printDeprecationWarning()

func printDeprecationWarning() {
    fmt.Fprintf(os.Stderr, "⚠️ DEPRECATION WARNING: The 'chorus' binary is deprecated!\n\n")
    fmt.Fprintf(os.Stderr, "This binary has been replaced with specialized binaries:\n")
    fmt.Fprintf(os.Stderr, "  🤖 chorus-agent - For autonomous AI agents\n")
    fmt.Fprintf(os.Stderr, "  👤 chorus-hap   - For human agent participation\n\n")
    fmt.Fprintf(os.Stderr, "Please use one of the new binaries instead:\n")
    fmt.Fprintf(os.Stderr, "  ./chorus-agent --help\n")
    fmt.Fprintf(os.Stderr, "  ./chorus-hap --help\n\n")
    fmt.Fprintf(os.Stderr, "This wrapper will be removed in a future version.\n")
}

Key Differences from Help:

Aspect	printDeprecationHelp()	printDeprecationWarning()
Output Stream	stdout	stderr
Verbosity	Detailed explanation	Brief warning
Tone	Educational	Urgent
Exit Code	0	1
Context	User requested help	Accidental execution

Why stderr?

• Ensures warning appears in logs
• Distinguishes error from normal output
• Prevents piping warning into scripts
• Signals abnormal execution

Why brief?

• User likely expected normal execution
• Quick redirection to correct binary
• Reduces noise in automated systems
• Clear that this is an error condition

---

Migration Guide

For Deployment Scripts

Old Script:

#!/bin/bash
# DEPRECATED - DO NOT USE

export CHORUS_LICENSE_ID=prod-123
export CHORUS_AGENT_ID=chorus-worker-1

# This will fail with exit code 1
./chorus

New Script (Autonomous Agent):

#!/bin/bash
# Updated for chorus-agent

export CHORUS_LICENSE_ID=prod-123
export CHORUS_AGENT_ID=chorus-worker-1
export CHORUS_P2P_PORT=9000

# Use new agent binary
./chorus-agent

New Script (Human Agent):

#!/bin/bash
# Updated for chorus-hap

export CHORUS_LICENSE_ID=prod-123
export CHORUS_AGENT_ID=human-alice
export CHORUS_HAP_MODE=terminal

# Use new HAP binary
./chorus-hap

For Docker Deployments

Old Dockerfile:

FROM debian:bookworm-slim
COPY chorus /usr/local/bin/chorus
ENTRYPOINT ["/usr/local/bin/chorus"]  # DEPRECATED

New Dockerfile (Agent):

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates docker.io
COPY chorus-agent /usr/local/bin/chorus-agent
ENTRYPOINT ["/usr/local/bin/chorus-agent"]

New Dockerfile (HAP):

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates
COPY chorus-hap /usr/local/bin/chorus-hap
ENTRYPOINT ["/usr/local/bin/chorus-hap"]

For Docker Compose

Old docker-compose.yml:

services:
  chorus:  # DEPRECATED
    image: chorus:latest
    command: /chorus  # Will fail

New docker-compose.yml (Agent):

services:
  chorus-agent:
    image: chorus-agent:latest
    command: /usr/local/bin/chorus-agent
    environment:
      - CHORUS_LICENSE_ID=${CHORUS_LICENSE_ID}

New docker-compose.yml (HAP):

services:
  chorus-hap:
    image: chorus-hap:latest
    command: /usr/local/bin/chorus-hap
    stdin_open: true  # Required for terminal interface
    tty: true
    environment:
      - CHORUS_LICENSE_ID=${CHORUS_LICENSE_ID}
      - CHORUS_HAP_MODE=terminal

For Systemd Services

Old Service File: /etc/systemd/system/chorus.service

[Unit]
Description=CHORUS Agent (DEPRECATED)

[Service]
ExecStart=/usr/local/bin/chorus  # Will fail
Restart=always

[Install]
WantedBy=multi-user.target

New Service File: /etc/systemd/system/chorus-agent.service

[Unit]
Description=CHORUS Autonomous Agent
After=network.target docker.service

[Service]
Type=simple
User=chorus
EnvironmentFile=/etc/chorus/agent.env
ExecStart=/usr/local/bin/chorus-agent
Restart=on-failure
RestartSec=10s

[Install]
WantedBy=multi-user.target

Migration Steps:

# Stop old service
sudo systemctl stop chorus
sudo systemctl disable chorus

# Install new service
sudo cp chorus-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable chorus-agent
sudo systemctl start chorus-agent

For CI/CD Pipelines

Old Pipeline (GitLab CI):

build:
  script:
    - go build -o chorus ./cmd/chorus  # DEPRECATED
    - ./chorus --version

New Pipeline:

build:
  script:
    - make build-agent  # Builds chorus-agent
    - make build-hap    # Builds chorus-hap
    - ./build/chorus-agent --version
    - ./build/chorus-hap --version

For Kubernetes Deployments

Old Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: chorus  # DEPRECATED
spec:
  template:
    spec:
      containers:
      - name: chorus
        image: chorus:latest
        command: ["/chorus"]  # Will fail

New Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: chorus-agent
spec:
  template:
    spec:
      containers:
      - name: chorus-agent
        image: chorus-agent:latest
        command: ["/usr/local/bin/chorus-agent"]
        env:
        - name: CHORUS_LICENSE_ID
          valueFrom:
            secretKeyRef:
              name: chorus-secrets
              key: license-id

---

Build Process

Current Makefile Targets

The CHORUS Makefile provides migration-friendly targets:

# Build all binaries
make all
├─→ make build-agent   # Builds chorus-agent (recommended)
├─→ make build-hap     # Builds chorus-hap (recommended)
└─→ make build-compat  # Builds chorus (deprecated wrapper)

Building Individual Binaries

Autonomous Agent:

make build-agent
# Output: build/chorus-agent

Human Agent Portal:

make build-hap
# Output: build/chorus-hap

Deprecated Wrapper:

make build-compat
# Output: build/chorus (for compatibility only)

Why Keep the Deprecated Binary?

Reasons to Build chorus:

1. Gradual Migration: Allows staged rollout of new binaries
2. Error Detection: Catches deployments still using old binary
3. User Guidance: Provides migration instructions at runtime
4. CI/CD Compatibility: Prevents hard breaks in existing pipelines

Planned Removal:

The chorus binary and make build-compat target will be removed in:

• Version: 1.0.0
• Timeline: After all known deployments migrate
• Warning Period: At least 3 minor versions (e.g., 0.5 → 0.6 → 0.7 → 1.0)

---

Troubleshooting

Script Fails with "DEPRECATION WARNING"

Symptom:

$ ./deploy.sh
⚠️ DEPRECATION WARNING: The 'chorus' binary is deprecated!
...
# Script exits with error

Cause: Script uses old ./chorus binary

Fix:

# Update script to use chorus-agent
sed -i 's|./chorus|./chorus-agent|g' deploy.sh

# Or update to chorus-hap for human agents
sed -i 's|./chorus|./chorus-hap|g' deploy.sh

Docker Container Exits Immediately

Symptom:

$ docker run chorus:latest
⚠️ DEPRECATION WARNING: The 'chorus' binary is deprecated!
# Container exits with code 1

Cause: Container uses deprecated binary

Fix: Rebuild image with correct binary:

# Old
COPY chorus /usr/local/bin/chorus

# New
COPY chorus-agent /usr/local/bin/chorus-agent
ENTRYPOINT ["/usr/local/bin/chorus-agent"]

Systemd Service Fails to Start

Symptom:

$ sudo systemctl status chorus
● chorus.service - CHORUS Agent
   Active: failed (Result: exit-code)
   Main PID: 12345 (code=exited, status=1/FAILURE)

Cause: Service configured to run deprecated binary

Fix: Create new service file:

# Disable old service
sudo systemctl stop chorus
sudo systemctl disable chorus

# Create new service
sudo cp chorus-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable chorus-agent
sudo systemctl start chorus-agent

CI Build Succeeds but Tests Fail

Symptom:

$ ./chorus --version
CHORUS 0.5.0-dev (DEPRECATED)
# Tests that try to run ./chorus fail

Cause: Tests invoke deprecated binary

Fix: Update test commands:

# Old test
./chorus --help

# New test
./chorus-agent --help

Can't Find Replacement Binary

Symptom:

$ ./chorus-agent
bash: ./chorus-agent: No such file or directory

Cause: New binaries not built or installed

Fix:

# Build new binaries
make build-agent
make build-hap

# Binaries created in build/ directory
ls -la build/chorus-*

# Install to system
sudo cp build/chorus-agent /usr/local/bin/
sudo cp build/chorus-hap /usr/local/bin/

---

Migration Checklist

Pre-Migration Assessment

• Inventory Deployments: List all places chorus binary is used

  • Production servers
  • Docker images
  • Kubernetes deployments
  • CI/CD pipelines
  • Developer machines
  • Documentation

• Identify Binary Types: Determine which replacement is needed

  • Autonomous operation → chorus-agent
  • Human interaction → chorus-hap
  • Mixed use → Both binaries needed

• Review Configuration: Check environment variables

  • CHORUS_AGENT_ID naming conventions
  • HAP-specific variables (CHORUS_HAP_MODE)
  • Port assignments (avoid conflicts)

Migration Execution

• Build New Binaries

  make build-agent
  make build-hap
  

• Update Docker Images

  • Modify Dockerfile to use new binaries
  • Rebuild and tag images
  • Push to registry

• Update Deployment Configs

  • docker-compose.yml
  • kubernetes manifests
  • systemd service files
  • deployment scripts

• Test in Staging

  • Deploy new binaries to staging environment
  • Verify P2P connectivity
  • Test agent/HAP functionality
  • Validate health checks

• Update CI/CD Pipelines

  • Build configurations
  • Test scripts
  • Deployment scripts
  • Rollback procedures

• Deploy to Production

  • Rolling deployment (one node at a time)
  • Monitor logs for deprecation warnings
  • Verify peer discovery still works
  • Check metrics and health endpoints

• Update Documentation

  • README files
  • Deployment guides
  • Runbooks
  • Architecture diagrams

Post-Migration Verification

• Verify No Deprecation Warnings

  # Check logs for deprecation messages
  journalctl -u chorus-agent | grep DEPRECATION
  # Should return no results
  

• Confirm Binary Versions

  ./chorus-agent --version
  ./chorus-hap --version
  # Should show correct version without (DEPRECATED)
  

• Test Functionality

  • P2P peer discovery works
  • Tasks execute successfully (agents)
  • Terminal interface works (HAP)
  • Health checks pass
  • Metrics collected

• Remove Old Binary

  # After confirming everything works
  rm /usr/local/bin/chorus
  

• Clean Up Old Configs

  • Remove old systemd service files
  • Delete old Docker images
  • Archive old deployment scripts

---

Comparison with New Binaries

Feature Comparison

Feature	chorus (deprecated)	chorus-agent	chorus-hap
Functional	❌ No	✅ Yes	✅ Yes
P2P Networking	❌ N/A	✅ Yes	✅ Yes
Task Execution	❌ N/A	✅ Automatic	✅ Interactive
UI Mode	❌ N/A	Headless	Terminal/Web
Purpose	Deprecation notice	Autonomous agent	Human interface
Exit Code	1 (error)	0 (normal)	0 (normal)
Runtime	Immediate exit	Long-running	Long-running

Size Comparison

Binary	Size	Notes
chorus	~2 MB	Minimal (messages only)
chorus-agent	~25 MB	Full functionality + dependencies
chorus-hap	~28 MB	Full functionality + UI components

Why is chorus smaller?

• No P2P libraries linked
• No task execution engine
• No AI provider integrations
• Only runtime constants imported

Command Comparison

chorus (deprecated):

./chorus --help     # Prints deprecation help
./chorus --version  # Prints version with (DEPRECATED)
./chorus            # Prints warning, exits 1

chorus-agent:

./chorus-agent --help     # Prints agent help
./chorus-agent --version  # Prints version
./chorus-agent            # Runs autonomous agent

chorus-hap:

./chorus-hap --help     # Prints HAP help
./chorus-hap --version  # Prints version
./chorus-hap            # Runs human interface

---

Related Documentation

• chorus-agent - Autonomous agent binary (REPLACEMENT)
• chorus-hap - Human Agent Portal binary (REPLACEMENT)
• internal/runtime - Shared runtime initialization
• Migration Guide - Detailed migration instructions
• Deployment - Docker deployment guide

---

Implementation Status

Feature	Status	Notes
Deprecation Messages	✅ Implemented	Help and warning outputs
Exit Code 1	✅ Implemented	Prevents accidental use
Version Tagging	✅ Implemented	Shows (DEPRECATED)
Guidance to New Binaries	✅ Implemented	Clear migration instructions
Removal Planned	⏳ Scheduled	Version 1.0.0

Removal Timeline

Version	Action	Date
0.5.0	Deprecated, wrapper implemented	2025-09-30
0.6.0	Warning messages in logs	TBD
0.7.0	Final warning before removal	TBD
1.0.0	Binary removed entirely	TBD

Recommendation: Migrate immediately. Do not wait for removal.

---

FAQ

Q: Can I still use ./chorus?

A: Technically you can build it, but it does nothing except print deprecation warnings and exit with error code 1. You should migrate to chorus-agent or chorus-hap immediately.

Q: Will chorus ever be restored?

A: No. The architecture has permanently moved to specialized binaries. The chorus wrapper exists only to guide users to the correct replacement.

Q: What if I need both agent and HAP functionality?

A: Run both binaries separately:

# Terminal 1: Run autonomous agent
./chorus-agent &

# Terminal 2: Run human interface
./chorus-hap

Both can join the same P2P network and collaborate.

Q: How do I test if my deployment uses the deprecated binary?

A: Check for deprecation warnings in logs:

# Grep for deprecation messages
journalctl -u chorus | grep "DEPRECATION WARNING"
docker logs <container> 2>&1 | grep "DEPRECATION WARNING"

# If found, migration is needed

Q: Is there a compatibility mode?

A: No. The chorus binary is intentionally non-functional to force migration. There is no compatibility mode.

Q: What about shell scripts that call ./chorus?

A: Update them to call ./chorus-agent or ./chorus-hap. Use sed for bulk updates:

# Update all scripts in directory
find . -type f -name "*.sh" -exec sed -i 's|./chorus[^-]|./chorus-agent|g' {} +

Q: Will old Docker images still work?

A: No. Docker images built with the chorus binary will fail at runtime with deprecation warnings. Rebuild images with new binaries.

Q: Can I delay migration?

A: You can delay, but the wrapper will be removed in version 1.0.0. Migrate now to avoid emergency updates later.

Q: Where can I get help with migration?

A: See:

• Migration Guide - Detailed migration steps
• chorus-agent Documentation - Agent replacement details
• chorus-hap Documentation - HAP replacement details

---

Last Updated: 2025-09-30

Deprecation Status: Active deprecation since version 0.5.0

Removal Target: Version 1.0.0