README.md
1 # ECHO Scripts 2 3 Utility scripts for managing, testing, and operating the ECHO multi-agent system. 4 5 ## Directory Structure 6 7 ``` 8 scripts/ 9 ├── README.md # This file 10 ├── setup/ # Initial setup and installation 11 ├── agents/ # Agent management scripts 12 ├── testing/ # Testing and verification 13 └── utils/ # General utilities 14 ``` 15 16 ## Quick Reference 17 18 ### First Time Setup 19 ```bash 20 ./scripts/setup/setup.sh # Complete setup 21 ./scripts/setup/setup_llms.sh # Install Ollama models 22 ./scripts/setup/docker-setup.sh # Setup Docker infrastructure 23 ``` 24 25 ### Agent Management 26 ```bash 27 ./scripts/agents/start_ceo_cto.sh # Start CEO and CTO agents 28 ./scripts/agents/stop_ceo_cto.sh # Stop CEO and CTO agents 29 ./scripts/agents/rebuild_all.sh # Rebuild all agents 30 ``` 31 32 ### Testing 33 ```bash 34 ./scripts/testing/test_agents.sh # Test all agents 35 ./scripts/testing/verify_all_agents.sh # Verify agent builds 36 ``` 37 38 ### Utilities 39 ```bash 40 ./scripts/utils/echo.sh summary # System status summary 41 ./scripts/utils/check_system_status.sh # Health check 42 ``` 43 44 ## Script Categories 45 46 ### `/setup/` - Installation & Setup 47 48 **setup.sh** 49 - Complete ECHO installation 50 - Compiles shared library 51 - Builds all 9 agents 52 - Runs initial verification 53 54 **setup_llms.sh** 55 - Installs Ollama (if not present) 56 - Downloads all 9 LLM models 57 - Verifies model installation 58 - ~48GB download 59 60 **docker-setup.sh** 61 - Starts PostgreSQL and Redis containers 62 - Creates database and runs migrations 63 - Verifies container health 64 65 ### `/agents/` - Agent Management 66 67 **start_ceo_cto.sh** 68 - Starts CEO and CTO agents for testing 69 - Useful for development workflows 70 - Runs in autonomous mode 71 72 **stop_ceo_cto.sh** 73 - Stops CEO and CTO agents gracefully 74 - Cleanup of background processes 75 76 **rebuild_all.sh** 77 - Recompiles shared library 78 - Rebuilds all 9 agent escripts 79 - Quick iteration during development 80 81 ### `/testing/` - Testing & Verification 82 83 **test_agents.sh** 84 - Runs unit tests for all agents 85 - Tests MCP tool implementations 86 - Validates agent configurations 87 88 **verify_all_agents.sh** 89 - Verifies all agents compile 90 - Checks MCP server functionality 91 - Validates database connectivity 92 93 ### `/utils/` - General Utilities 94 95 **echo.sh** 96 - Swiss army knife for ECHO management 97 - Commands: summary, status, agents, decisions, messages 98 - Primary development tool 99 100 **check_system_status.sh** 101 - System health check 102 - PostgreSQL, Redis, Ollama status 103 - Quick diagnostic tool 104 105 ## Script Conventions 106 107 ### Error Handling 108 All scripts use: 109 ```bash 110 set -euo pipefail # Exit on error, undefined vars, pipe failures 111 ``` 112 113 ### Project Root 114 Scripts reliably find project root: 115 ```bash 116 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" 117 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" 118 ``` 119 120 ### Output Format 121 - ✅ Success messages in green 122 - ❌ Error messages in red 123 - ℹ️ Info messages in blue 124 - ⚠️ Warnings in yellow 125 126 ### Logging 127 Scripts log to: 128 - `logs/scripts/` - Script execution logs 129 - `logs/agents/` - Agent-specific logs 130 - stderr - Errors and warnings 131 132 ## Creating New Scripts 133 134 ### Template 135 136 ```bash 137 #!/usr/bin/env bash 138 # Description: Brief description of what this script does 139 140 set -euo pipefail 141 142 # Find project root 143 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" 144 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" 145 146 # Change to project root 147 cd "$PROJECT_ROOT" || { 148 echo "Error: Failed to change to project directory" >&2 149 exit 1 150 } 151 152 # Main logic 153 main() { 154 echo "Doing something..." 155 } 156 157 # Run main 158 main "$@" 159 ``` 160 161 ### Best Practices 162 1. **Add description** - First comment should explain purpose 163 2. **Use `set -euo pipefail`** - Fail fast on errors 164 3. **Find project root** - Don't assume working directory 165 4. **Validate inputs** - Check arguments before use 166 5. **Provide usage** - Show help with `--help` flag 167 6. **Log important actions** - Especially destructive operations 168 7. **Make executable** - `chmod +x script.sh` 169 170 ## Common Patterns 171 172 ### Wait for Service 173 ```bash 174 wait_for_postgres() { 175 for i in {1..30}; do 176 if psql -U postgres -h localhost -p 5433 -c "SELECT 1" &>/dev/null; then 177 return 0 178 fi 179 sleep 1 180 done 181 return 1 182 } 183 ``` 184 185 ### Cleanup on Exit 186 ```bash 187 cleanup() { 188 echo "Cleaning up..." 189 # Cleanup logic 190 } 191 trap cleanup EXIT 192 ``` 193 194 ### Progress Indication 195 ```bash 196 step() { 197 echo "▶ $1..." 198 } 199 200 step "Compiling shared library" 201 cd shared && mix compile 202 203 step "Building agents" 204 ./scripts/agents/rebuild_all.sh 205 ``` 206 207 ## Troubleshooting 208 209 ### Script Fails with "Permission Denied" 210 ```bash 211 chmod +x scripts/path/to/script.sh 212 ``` 213 214 ### Can't Find Project Root 215 Ensure script uses the standard pattern: 216 ```bash 217 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" 218 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" 219 ``` 220 221 ### PostgreSQL Connection Errors 222 ```bash 223 # Check PostgreSQL is running 224 ./scripts/utils/check_system_status.sh 225 226 # Or start Docker 227 ./scripts/setup/docker-setup.sh 228 ``` 229 230 ## Related Documentation 231 232 - **Development:** [../CLAUDE.md](../CLAUDE.md) 233 - **Testing:** [../test/README.md](../test/README.md) 234 - **Agents:** [../agents/claude.md](../agents/claude.md) 235 236 --- 237 238 **Last Updated:** 2025-11-06 239 **Script Count:** 48 scripts (organized into 4 categories) 240 **Conventions:** Bash best practices, error handling, logging