1  # CLAUDE.md
  2  
  3  This file provides guidance to Claude Code when working with the ECHO repository.
  4  
  5  ## 🎯 Project Overview
  6  
  7  **ECHO (Executive Coordination & Hierarchical Organization)** is an AI-powered organizational model where autonomous role-based agents communicate via the Model Context Protocol (MCP). Each agent is an independent MCP server that can connect to Claude Desktop or other MCP clients.
  8  
  9  **Vision:** Enable AI agents to operate as autonomous workers that make decisions, collaborate, escalate appropriately, and require human approval for critical actions.
 10  
 11  ## 🏗️ Architecture
 12  
 13  ```
 14  Claude Desktop / MCP Client
 15      ├──> 9 Independent Agent MCP Servers (CEO, CTO, CHRO, Ops, PM, Architect, UI/UX, Dev, Test)
 16      │    └──> Each has specialized LLM via Ollama
 17      └──> Shared Infrastructure
 18           ├── PostgreSQL (decisions, messages, memories, votes, agent status)
 19           └── Redis (message bus, pub/sub, real-time coordination)
 20  ```
 21  
 22  **Tech Stack:** Elixir 1.18, PostgreSQL 16, Redis 7, MCP 2024-11-05, Ollama (9 specialized local models), Phoenix LiveView
 23  
 24  ## 📂 Repository Structure
 25  
 26  **12 focused `claude.md` files** (see each directory):
 27  `apps/` `apps/echo_shared/` `apps/delegator/` `test/` `scripts/` `workflows/` `monitor/` `docker/` `k8s/` `benchmark_models/` `training/`
 28  
 29  **Reusable snippets:** `docs/snippets/` | **Full index:** `docs/INDEX.md`
 30  
 31  ## 🚨 Critical Rules - READ FIRST
 32  
 33  ### Rule 1: Never Break Existing Tests
 34  - **ALWAYS run tests** before committing changes
 35  - All tests must pass: `cd shared && mix test`
 36  - If tests fail, fix the code, don't modify tests to pass
 37  
 38  ### Rule 2: Respect the Autonomous Flag
 39  - Agents run as MCP servers by default (stdio mode)
 40  - Use `--autonomous` flag for standalone mode: `./ceo --autonomous`
 41  - MCP servers exit when stdin closes - this is expected behavior
 42  
 43  ### Rule 3: Compile Shared Library First
 44  - The `shared/` library is a dependency for all agents
 45  - Always compile shared before agents: `cd shared && mix compile`
 46  
 47  ### Rule 4: Database Safety
 48  - **NEVER run** `mix ecto.drop` or `mix ecto.reset` without explicit user permission
 49  - Use migrations for schema changes: `mix ecto.migrate`
 50  
 51  ### Rule 5: Don't Overengineer
 52  - Start with the simplest solution
 53  - Consult the user before adding complexity
 54  - Follow existing patterns before inventing new ones
 55  
 56  ### Rule 6: MCP Protocol Compliance
 57  - Use `EchoShared.MCP.Server` behavior - don't roll your own
 58  - JSON-RPC 2.0 over stdio is the transport layer
 59  
 60  ### Rule 7: Message Bus Discipline
 61  - All inter-agent communication via Redis pub/sub
 62  - Use `EchoShared.MessageBus` functions
 63  - Never bypass the message bus for direct communication
 64  
 65  ### Rule 8: Dual-AI Workflow (Claude Code + LocalCode)
 66  
 67  **ECHO has TWO AI assistant systems:**
 68  
 69  **LocalCode** - Local LLM assistant (deepseek-coder:6.7b)
 70  - $0 cost, 100% private, project-aware
 71  - Response time: 7-30 seconds
 72  - Session capacity: 10-12 conversational turns
 73  
 74  **Quick Commands:**
 75  ```bash
 76  source ./scripts/llm/localcode_quick.sh  # Load once per terminal
 77  lc_start        # Start session with auto-context
 78  lc_query "..."  # Query local LLM
 79  lc_interactive  # Interactive mode
 80  lc_end          # End and archive session
 81  ```
 82  
 83  **When to Use:**
 84  - **Claude Code (me):** Complex tasks, multi-file changes, refactoring, git operations
 85  - **LocalCode:** Quick questions, code exploration, documentation lookup, debugging hints
 86  - **Both:** Code reviews, architectural decisions, dual perspectives
 87  
 88  **Context Awareness:**
 89  - Startup: ~1,900 tokens (CLAUDE.md first 200 lines + git + system status)
 90  - Warning at: >3,000 tokens (moderate), >4,000 (high), >6,000 (restart required)
 91  - Restart session every 5-8 turns to avoid context overflow
 92  
 93  **Full LocalCode documentation:** See `scripts/claude.md` (Rule 8 complete guide, 400+ lines) or `scripts/llm/QUICK_START.md`
 94  
 95  ### Rule 9: Documentation Organization
 96  
 97  **All documentation organized in `docs/` folders:**
 98  - `docs/architecture/` - System architecture documents
 99  - `docs/guides/` - User guides and tutorials
100  - `docs/completed/` - Completed implementation reports
101  - `docs/troubleshooting/` - Troubleshooting guides
102  - `apps/{app}/docs/` - App-specific documentation
103  
104  **Rules:**
105  - ✅ **DO** create `docs/` folders when adding documentation
106  - ✅ **DO** keep only `CLAUDE.md` and `README.md` at project root
107  - ❌ **DON'T** leave loose `.md` files at project root
108  
109  ## 🚀 Quick Start
110  
111  **Setup:** `docker-compose up -d && cd shared && mix ecto.create && mix ecto.migrate && ./setup_llms.sh && ./setup.sh`
112  **Dev:** `cd shared && mix compile && mix test` → `cd apps/ceo && mix compile && ./ceo --autonomous`
113  **Monitor:** `cd monitor && ./start.sh` (http://localhost:4000)
114  
115  ## 🐛 Troubleshooting
116  
117  **DB/Redis:** `docker-compose up -d && cd shared && mix ecto.migrate`
118  **Compile:** `cd shared && mix clean && mix compile`
119  **LLM:** `curl http://localhost:11434/api/tags && ollama list`
120  **LocalCode:** `lc_end && lc_start` or `export LLM_TIMEOUT=300`
121  
122  **Full guide:** `docs/snippets/` (database, ollama, testing, git)
123  
124  ## 🎨 Core Concepts
125  
126  **Decision Modes:** Autonomous | Collaborative | Hierarchical | Human-in-the-Loop
127  **DB Tables:** decisions, messages, memories, decision_votes, agent_status
128  **Redis Channels:** messages:{role}, messages:all, decisions:*, agents:heartbeat
129  
130  See `apps/echo_shared/claude.md` for details.
131  
132  ## ⚠️ Common Pitfalls
133  
134  1. **Forgetting to compile shared library first** - Always `cd shared && mix compile`
135  2. **Running agents without --autonomous for testing** - Use `--autonomous` for standalone mode
136  3. **Modifying database without migrations** - Use `mix ecto.gen.migration`
137  4. **Bypassing message bus** - All communication must go through Redis + PostgreSQL
138  5. **Not checking if PostgreSQL/Redis are running** - `docker ps | grep echo`
139  
140  ## 📖 Current Phase
141  
142  **Phase 4: Workflows & Integration** (In Progress)
143  
144  **Completed:**
145  - ✅ Phase 1: Foundation (shared library, MCP protocol, database schemas)
146  - ✅ Phase 2: CEO agent (reference implementation)
147  - ✅ Phase 3: All 9 agents with LLM integration
148  
149  **In Progress:**
150  - 🔄 Workflow engine testing
151  - 🔄 Multi-agent workflow examples
152  - 🔄 Integration test suite
153  
154  ## 🤝 Contributing Guidelines
155  
156  1. **Read the focused context** - Check the `claude.md` in the directory you're working in
157  2. **Follow existing patterns** - Look at similar code before implementing
158  3. **Run tests** - Always ensure tests pass
159  4. **Keep it simple** - Don't overengineer solutions
160  5. **Ask before major changes** - Consult user for architectural decisions
161  
162  ## 📞 Getting Help
163  
164  - **Architecture:** `docs/architecture/ECHO_ARCHITECTURE.md`
165  - **Agent development:** `apps/claude.md`
166  - **Delegator (resource optimization):** `apps/delegator/claude.md`
167  - **Shared library:** `apps/echo_shared/claude.md`
168  - **Testing:** `test/claude.md`
169  - **LocalCode:** `scripts/claude.md` (Rule 8 complete guide)
170  - **Workflows:** `workflows/claude.md`
171  - **Deployment (Docker):** `docker/claude.md`
172  - **Deployment (Kubernetes):** `k8s/claude.md`
173  - **LLM Benchmarking:** `benchmark_models/claude.md`
174  - **Common troubleshooting:** `docs/snippets/` (database, Ollama, testing, git)
175  
176  ---
177  
178  **Remember:** This is a complex multi-agent system. Simplicity in implementation is key to maintainability.
179  
180  ---
181  
182  # Detailed Documentation (Below First 200 Lines)
183  
184  The sections below provide comprehensive details not included in the first 200 lines for token optimization.
185  
186  ## 🔍 9 Agent Roles (Detailed)
187  
188  | Agent | Model | Size | Purpose |
189  |-------|-------|------|---------|
190  | **CEO** | qwen2.5:14b | 14B | Strategic leadership and budget decisions |
191  | **CTO** | deepseek-coder:33b | 33B | Technology strategy and architecture review |
192  | **CHRO** | llama3.1:8b | 8B | People management and communication |
193  | **Operations Head** | mistral:7b | 7B | Infrastructure optimization |
194  | **Product Manager** | llama3.1:8b | 8B | Product strategy and prioritization |
195  | **Senior Architect** | deepseek-coder:33b | 33B | System design and technical specifications |
196  | **UI/UX Engineer** | llama3.2-vision:11b | 11B | Design evaluation and visual understanding |
197  | **Senior Developer** | deepseek-coder:6.7b | 6.7B | Fast code generation and implementation |
198  | **Test Lead** | codellama:13b | 13B | Test generation and quality assurance |
199  
200  ## 🔧 Environment Variables (Detailed)
201  
202  ```bash
203  # Database (Docker on port 5433)
204  DB_HOST=localhost
205  DB_USER=echo_org
206  DB_PASSWORD=postgres
207  DB_PORT=5433
208  DB_NAME=echo_org
209  
210  # Redis (Docker on port 6383)
211  REDIS_HOST=localhost
212  REDIS_PORT=6383
213  
214  # Ollama
215  OLLAMA_ENDPOINT=http://localhost:11434
216  
217  # Agent-specific
218  AUTONOMOUS_BUDGET_LIMIT=1000000  # CEO authority limit
219  CEO_MODEL=qwen2.5:14b           # Override default model
220  CEO_LLM_ENABLED=true            # Enable/disable LLM
221  
222  # LocalCode (see scripts/claude.md for details)
223  LLM_MODEL=deepseek-coder:6.7b   # Model to use
224  LLM_TIMEOUT=180                  # Query timeout (3 minutes)
225  LOCALCODE_SESSIONS_DIR=~/.localcode/sessions/
226  ```
227  
228  ## 📚 Documentation Map (Complete)
229  
230  ### Project Documentation (`./docs/`)
231  
232  | Document | Location | Purpose |
233  |----------|----------|---------|
234  | **Architecture** | | |
235  | `ECHO_ARCHITECTURE.md` | `docs/architecture/` | Complete system architecture and design decisions |
236  | `DELEGATOR_ARCHITECTURE.md` | `docs/architecture/` | Delegator agent resource optimization |
237  | `FLOW_DSL_IMPLEMENTATION.md` | `docs/architecture/` | Event-driven Flow DSL implementation details |
238  | `TOKEN_OPTIMIZATION_ANALYSIS.md` | `docs/architecture/` | Token optimization strategies and analysis |
239  | **Guides** | | |
240  | `README.md` | `./ (root)` | User-facing getting started guide |
241  | `GETTING_STARTED.md` | `docs/guides/` | Step-by-step setup instructions |
242  | `DEMO_GUIDE.md` | `docs/guides/` | 10 demo scenarios with examples |
243  | `claude-desktop-setup.md` | `docs/guides/` | Connect agents to Claude Desktop |
244  | `DELEGATOR_QUICK_START.md` | `docs/guides/` | Delegator agent quick start |
245  | **Completed** | | |
246  | `DAY2_TRAINING_COMPLETE.md` | `docs/completed/` | Day 2 training completion report |
247  | `DAY3_TRAINING_COMPLETE.md` | `docs/completed/` | Day 3 training completion report |
248  | `SECURITY_FIXES.md` | `docs/completed/` | Security hardening implementation |
249  | `SCRIPT_CLEANUP_SUMMARY.md` | `docs/completed/` | Script cleanup and umbrella migration |
250  
251  ### App-Specific Documentation
252  
253  | Document | Location | Purpose |
254  |----------|----------|---------|
255  | `apps/claude.md` | `apps/` | Agent development patterns |
256  | `apps/echo_shared/claude.md` | `apps/echo_shared/` | Shared library API reference |
257  | `apps/delegator/claude.md` | `apps/delegator/` | Delegator agent (resource optimization) |
258  | **Session Consult** | | |
259  | `SESSION_CONSULT_INTEGRATION_FINAL_REPORT.md` | `apps/echo_shared/docs/` | Complete integration report |
260  | `LLM_SESSION_INTEGRATION_SUMMARY.md` | `apps/echo_shared/docs/` | Integration summary |
261  
262  ## 🧪 Testing Philosophy (Detailed)
263  
264  - **Unit Tests:** Test individual components in isolation
265    - Location: `apps/*/test/`
266    - Run: `cd apps/ceo && mix test`
267  - **Integration Tests:** Test multi-agent workflows end-to-end
268    - Location: `test/integration/`
269    - See `test/claude.md` for patterns
270  - **System Tests:** Load testing, failover scenarios, audit trails
271    - Location: `test/e2e/`
272    - Tagged with `@moduletag :e2e`
273  - **All tests must pass before committing**
274  
275  ## 🚀 Complete Deployment Guide
276  
277  See `docker/claude.md` for:
278  - Docker Compose setup
279  - Kubernetes manifests
280  - Production deployment
281  - Scaling strategies
282  - Monitoring and logging
283  
284  ## 📈 Performance & Monitoring
285  
286  ### Monitor Dashboard
287  ```bash
288  cd monitor && ./start.sh
289  # Open http://localhost:4000
290  ```
291  
292  **Features:**
293  - Real-time agent activity
294  - Decision flow tracking
295  - Performance metrics
296  - Activity timeline
297  
298  See `monitor/claude.md` for dashboard development.
299  
300  ## 🔐 Security Best Practices
301  
302  1. **Never commit secrets** - Use environment variables
303  2. **Validate all MCP tool inputs** - Prevent injection attacks
304  3. **Respect agent authority limits** - Check before executing
305  4. **Audit trail** - All decisions and messages persisted
306  5. **Database transactions** - Use Ecto transactions for consistency
307  
308  See `docs/completed/SECURITY_FIXES.md` for security hardening details.
309  
310  ## 🎯 Advanced Topics
311  
312  ### LocalCode - Complete Guide
313  
314  See `scripts/claude.md` for comprehensive LocalCode documentation including:
315  - Context injection architecture (tiered system)
316  - Tool simulation (auto-detection and execution)
317  - Session management (lifecycle, context growth)
318  - Dual perspective workflows (LocalCode + Claude Code)
319  - Configuration and environment variables
320  - Performance metrics and optimization
321  - Troubleshooting guide
322  - 10+ workflow integration examples
323  
324  **Key features:**
325  - $0 cost per query (local inference)
326  - 100% private (no external API calls)
327  - Project-aware (auto-loads CLAUDE.md, git context, system status)
328  - Tool simulation (read_file, grep_code, glob_files, run_bash)
329  - Conversation memory (last 5 turns)
330  - Context warnings (prevents overflow)
331  
332  **When to use LocalCode:**
333  - Quick questions: "How does X work?"
334  - Code exploration: "What's in this file?"
335  - Documentation lookup: "What does this function do?"
336  - Debugging hints: "Why might this fail?"
337  - Architecture clarifications: "How do agents communicate?"
338  
339  **When to use Claude Code:**
340  - Complex architectural decisions
341  - Multi-file refactoring
342  - Code generation (new features)
343  - Test writing and execution
344  - Git operations (commits, PRs)
345  - Tasks requiring >10 steps or >30 minutes
346  
347  **Dual perspective approach:**
348  1. Query LocalCode for fast, code-focused perspective
349  2. Query Claude Code for comprehensive analysis
350  3. Compare insights for best outcome
351  
352  ### Delegator Agent
353  
354  See `apps/delegator/claude.md` for complete delegator documentation.
355  
356  **Purpose:** Intelligent agent coordinator that spawns only required agents per session.
357  
358  **Benefits:**
359  - ⚡ 50-85% reduction in CPU/memory usage
360  - 🚀 Faster startup (load only necessary LLMs)
361  - 🎯 Better UX (relevant agents for task)
362  - 💰 Resource efficiency (scale based on needs)
363  
364  **Example:**
365  ```
366  Task: "Fix typo in README"
367  Before: 9 agents loaded (~48GB)
368  After: 1 agent loaded (Developer, ~7GB)
369  Savings: 85% memory reduction
370  ```
371  
372  ### Workflows
373  
374  See `workflows/claude.md` for multi-agent workflow patterns and orchestration.
375  
376  ## 🛠️ Advanced Troubleshooting
377  
378  ### Debug Mode
379  ```bash
380  # Enable debug logging for agent
381  export AGENT_LOG_LEVEL=debug
382  ./ceo --autonomous
383  
384  # Enable debug logging for shared library
385  export ECHO_SHARED_LOG_LEVEL=debug
386  ```
387  
388  ### Database Issues
389  ```bash
390  # Stale connections
391  cd shared && MIX_ENV=test mix ecto.reset
392  
393  # Migration conflicts
394  cd shared && mix ecto.rollback && mix ecto.migrate
395  
396  # Permission issues
397  GRANT ALL PRIVILEGES ON DATABASE echo_org TO echo_org;
398  ```
399  
400  ### Redis Issues
401  ```bash
402  # Clear all keys (WARNING: destructive)
403  redis-cli -h 127.0.0.1 -p 6383 FLUSHALL
404  
405  # Monitor messages in real-time
406  redis-cli -h 127.0.0.1 -p 6383
407  > SUBSCRIBE messages:all
408  
409  # Check memory usage
410  redis-cli -h 127.0.0.1 -p 6383 INFO memory
411  ```
412  
413  ### Ollama / LLM Issues
414  ```bash
415  # Check Ollama status
416  curl http://localhost:11434/api/tags
417  
418  # List installed models
419  ollama list
420  
421  # Pull missing model
422  ollama pull deepseek-coder:6.7b
423  
424  # Test model inference
425  curl http://localhost:11434/api/generate -d '{
426    "model": "deepseek-coder:6.7b",
427    "prompt": "def hello():",
428    "stream": false
429  }'
430  
431  # Monitor Ollama logs
432  docker logs -f ollama  # If running in Docker
433  ```
434  
435  ### LocalCode Troubleshooting
436  
437  See `scripts/claude.md` (Section 8.9) for complete LocalCode troubleshooting guide.
438  
439  **Common issues:**
440  - "Failed to get response from Ollama" → Check Ollama running, increase timeout
441  - "Context too large" warning → Restart session (`lc_end && lc_start`)
442  - Slow responses (>60s) → Use smaller model or increase timeout
443  - Inaccurate responses → Use dual perspective (check with Claude Code)
444  
445  ## 🎓 Learning Resources
446  
447  ### For New Contributors
448  
449  1. Start with `README.md` - High-level overview
450  2. Read `CLAUDE.md` (this file) - Development guidelines
451  3. Explore `docs/guides/GETTING_STARTED.md` - Step-by-step setup
452  4. Study `apps/claude.md` - Agent development patterns
453  5. Review `apps/ceo/` - Reference implementation
454  6. Experiment with `scripts/llm/` - Try LocalCode assistant
455  
456  ### For Advanced Development
457  
458  1. `docs/architecture/ECHO_ARCHITECTURE.md` - Deep dive into system design
459  2. `apps/echo_shared/claude.md` - Shared library internals
460  3. `workflows/claude.md` - Multi-agent orchestration
461  4. `test/claude.md` - Integration testing patterns
462  5. `docker/claude.md` - Production deployment
463  
464  ## 📊 Project Statistics
465  
466  - **Total Lines of Code:** ~15,000+ (Elixir)
467  - **Number of Agents:** 9 independent MCP servers
468  - **LLM Models:** 9 specialized models (~48GB total)
469  - **Database Tables:** 6 core tables (decisions, messages, memories, etc.)
470  - **Redis Channels:** 10+ pub/sub channels
471  - **Claude.md Files:** 12 files (127KB total documentation)
472  - **Test Coverage:** >80% (unit + integration tests)
473  
474  ## 🌟 Future Roadmap
475  
476  **Phase 5: Production Readiness**
477  - Kubernetes deployment automation
478  - Horizontal scaling for agents
479  - Load balancing and failover
480  - Advanced monitoring and alerting
481  
482  **Phase 6: Advanced Features**
483  - Inter-organization communication
484  - External API integrations
485  - Machine learning for decision optimization
486  - Natural language workflow definitions
487  
488  ---
489  
490  **End of CLAUDE.md** - For detailed context on specific areas, see the focused `claude.md` files in each directory.