@phuetz/code-buddy 0.1.0

package/README.md

@@ -0,0 +1,858 @@
+<div align="center">
+
+<img src="https://img.shields.io/badge/🤖-Code_Buddy-blueviolet?style=for-the-badge&labelColor=1a1a2e" alt="Code Buddy"/>
+
+# Code Buddy
+
+### Multi-AI Personal Assistant with OpenClaw-Inspired Architecture
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@phuetz/code-buddy"><img src="https://img.shields.io/npm/v/@phuetz/code-buddy.svg?style=flat-square&color=ff6b6b&label=version" alt="npm version"/></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-feca57.svg?style=flat-square" alt="License: MIT"/></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-54a0ff?style=flat-square&logo=node.js" alt="Node Version"/></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.3-5f27cd?style=flat-square&logo=typescript" alt="TypeScript"/></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Tests-340%2B-00d26a?style=flat-square&logo=jest" alt="Tests"/>
+  <img src="https://img.shields.io/badge/Coverage-85%25-48dbfb?style=flat-square" alt="Coverage"/>
+  <img src="https://img.shields.io/badge/Build-passing-00d26a?style=flat-square" alt="Build"/>
+</p>
+
+<br/>
+
+**A powerful multi-AI terminal agent inspired by [OpenClaw](https://github.com/openclaw/openclaw) architecture. Supports Grok, Claude, ChatGPT, Gemini, LM Studio, and Ollama with advanced memory, multi-channel messaging, and intelligent context management.**
+
+<br/>
+
+[Quick Start](#-quick-start) |
+[Architecture](#-architecture) |
+[Memory System](#-memory-system) |
+[Channels](#-multi-channel-support) |
+[Security](#-security) |
+[API](#-api-server)
+
+</div>
+
+---
+
+## What's New
+
+### OpenClaw-Inspired Features
+
+Code Buddy incorporates advanced patterns from the [OpenClaw](https://github.com/openclaw/openclaw) project:
+
+| Module | Status | Description |
+|:-------|:------:|:------------|
+| **Tool Policy System** | ✅ 100% | Fine-grained tool permissions with allowlist/denylist |
+| **Bash Allowlist** | ✅ 100% | Secure command execution with pattern matching |
+| **Context Window Guard** | ✅ 100% | Automatic context management with 34 test cases |
+| **Smart Compaction** | ✅ 100% | Multi-stage conversation compression |
+| **Context Pruning** | ✅ 100% | TTL-based message expiration |
+| **Hybrid Search** | ✅ 100% | Combined keyword + semantic search |
+| **Lifecycle Hooks** | ✅ 100% | Pre/post hooks with 52 test cases |
+| **Connection Profiles** | ✅ 100% | Multi-provider switching with 57 tests |
+| **Desktop Automation** | ✅ 100% | Screen capture, OCR, UI control |
+| **Gemini Vision** | ✅ 100% | Native image support via `inlineData` (base64 data URLs) |
+| **Auto-Capture Memory** | ✅ 100% | Pattern-based memory extraction |
+| **Memory Lifecycle** | ✅ 100% | Auto-recall and auto-capture hooks |
+
+### Phase 3 — Streaming & Security
+
+| Module | Status | Description |
+|:-------|:------:|:------------|
+| **Middleware Pipeline** | ✅ 100% | Composable before/after turn hooks (cost limit, context warning, turn limit) |
+| **Reasoning Events** | ✅ 100% | Streaming chain-of-thought display with collapsible UI |
+| **Trust Folders** | ✅ 100% | Directory-level tool permissions via `.codebuddy-trust.json` |
+| **Agent Profiles** | ✅ 100% | Predefined agent configs (secure, minimal, power-user) |
+| **Tool Streaming** | ✅ 100% | Real-time bash output via AsyncGenerator |
+| **TabbedQuestion UI** | ✅ 100% | Multi-option interactive prompts |
+
+### Phase 4 — Autonomous Agent
+
+| Module | Status | Description |
+|:-------|:------:|:------------|
+| **Daemon Mode** | ✅ 100% | Background process with PID management, auto-restart (max 3) |
+| **Cron-Agent Bridge** | ✅ 100% | Scheduled task execution via CodeBuddyAgent instances |
+| **Task Planner** | ✅ 100% | DAG-based decomposition with topological sort and parallel execution |
+| **Screen Observer** | ✅ 100% | Periodic screenshots, perceptual diff, event triggers |
+| **Proactive Agent** | ✅ 100% | Push notifications, question/response, rate limiting, quiet hours |
+| **Orchestrator** | ✅ 100% | Multi-agent supervisor (sequential/parallel/race/all strategies) |
+| **Self-Healing** | ✅ 100% | Error pattern recognition, auto-recovery with exponential backoff |
+| **Checkpoint Rollback** | ✅ 100% | Auto-checkpoint before risky ops, rollback to last good state |
+| **Shared Context** | ✅ 100% | Thread-safe key-value store with optimistic locking |
+
+### Phase 5 — OpenClaw-Inspired Platform
+
+| Module | Status | Description |
+|:-------|:------:|:------------|
+| **Doctor Command** | ✅ 100% | Environment/deps/config diagnostics (`buddy doctor`) |
+| **Onboarding Wizard** | ✅ 100% | Interactive setup wizard (`buddy onboard`) |
+| **Model Failover Chain** | ✅ 100% | Cascading provider fallback with health tracking |
+| **Webhook Triggers** | ✅ 100% | HMAC-verified HTTP triggers + CLI + API routes |
+| **Typing Indicators** | ✅ 100% | Presence & typing events for channels |
+| **Live Canvas** | ✅ 100% | WebSocket-driven visual workspace (A2UI) |
+| **Docker Sandbox** | ✅ 100% | Containerized command execution with resource limits |
+| **Skills Registry** | ✅ 100% | Bundled/managed/workspace skills with YAML frontmatter |
+| **Media Pipeline** | ✅ 100% | Ingest, track, transcode with transcription hooks |
+| **ACP Protocol** | ✅ 100% | Inter-agent communication router with request/response |
+| **Extension System** | ✅ 100% | Manifest-based plugin loader with lifecycle hooks |
+| **Copilot Proxy** | ✅ 100% | IDE-compatible completions backend (`/v1/completions`) |
+
+---
+
+## Installation
+
+### Prerequisites
+
+- **Node.js** 18.0.0 or higher
+- **ripgrep** (recommended for faster search)
+
+```bash
+# macOS
+brew install ripgrep
+
+# Ubuntu/Debian
+sudo apt-get install ripgrep
+
+# Windows
+choco install ripgrep
+```
+
+### Install Code Buddy
+
+```bash
+# npm (recommended)
+npm install -g @phuetz/code-buddy
+
+# Or try without installing
+npx @phuetz/code-buddy@latest
+```
+
+---
+
+## Quick Start
+
+```bash
+# Configure API key (Grok/xAI)
+export GROK_API_KEY=your_api_key
+
+# Start interactive mode
+buddy
+
+# Or with a specific task
+buddy --prompt "analyze the codebase structure"
+
+# Use with local LLM (LM Studio)
+buddy --profile lmstudio
+
+# Full autonomy mode
+YOLO_MODE=true buddy
+```
+
+### Typical Project Workflow
+
+```bash
+# 1. First-time setup
+buddy onboard                # Interactive config wizard
+buddy doctor                 # Verify environment & dependencies
+
+# 2. Start coding
+buddy                        # Launch interactive chat
+
+# 3. Describe what you want in natural language
+> "Create a Node.js project with Express and Prisma"
+> "Add Google OAuth authentication"
+> "Write tests for the auth module"
+> "Fix the typecheck errors"
+> "Commit everything"
+
+# 4. Advanced modes
+buddy --profile gemini       # Switch AI provider
+buddy speak                  # Voice conversation mode
+buddy daemon start           # Run 24/7 in background
+buddy server --port 3000     # Expose REST/WebSocket API
+```
+
+Code Buddy autonomously reads files, writes code, runs commands, and fixes errors — typically 5-15 tool calls per task (up to 50, or 400 in YOLO mode).
+
+---
+
+## Architecture
+
+Code Buddy uses a **facade architecture** for clean separation of concerns:
+
+```
+CodeBuddyAgent
+    │
+    ├── AgentContextFacade      # Context window and memory management
+    │       - Token counting, compression, memory retrieval
+    │
+    ├── SessionFacade           # Session persistence and checkpoints
+    │       - Save/load, checkpoint creation, rewind
+    │
+    ├── ModelRoutingFacade      # Model routing and cost tracking
+    │       - Provider selection, cost calculation
+    │
+    ├── InfrastructureFacade    # MCP, sandbox, hooks, plugins
+    │       - Hook execution, plugin loading
+    │
+    └── MessageHistoryManager   # Chat and LLM message history
+```
+
+### Autonomy Layer (Phase 4)
+
+```
+CodeBuddyAgent
+    │
+    ├── TaskPlanner             # DAG decomposition of complex requests
+    │       - needsPlanning() heuristic
+    │       - createPlan() → TaskGraph → parallel execution
+    │
+    ├── SupervisorAgent         # Multi-agent orchestration
+    │       - Sequential, parallel, race, all strategies
+    │       - SharedContext with optimistic locking
+    │
+    ├── SelfHealing             # Automatic error recovery
+    │       - Pattern recognition (6 built-in patterns)
+    │       - Retry with exponential backoff
+    │
+    ├── ScreenObserver          # Environment monitoring
+    │       - Periodic screenshots with perceptual diff
+    │       - Event triggers (file_change, screen_change, time, webhook)
+    │
+    ├── ProactiveAgent          # Agent-initiated communication
+    │       - Push notifications with priority levels
+    │       - Rate limiting and quiet hours
+    │
+    └── DaemonManager           # Background process lifecycle
+            - PID file management, auto-restart
+            - Service registry, health monitoring
+```
+
+### Core Flow
+
+```
+User Input → ChatInterface (Ink/React) → CodeBuddyAgent → AI Provider
+                                              │
+                                         Tool Calls (max 50/400 rounds)
+                                              │
+                                      Tool Execution + Confirmation
+                                              │
+                                        Results back to API (loop)
+```
+
+---
+
+## AI Providers
+
+Code Buddy supports multiple AI providers with automatic failover:
+
+| Provider | Models | Context | Configuration |
+|:---------|:-------|:--------|:--------------|
+| **Grok** (xAI) | grok-4, grok-code-fast-1 | 128K | `GROK_API_KEY` |
+| **Claude** (Anthropic) | claude-sonnet-4, opus | 200K | `ANTHROPIC_API_KEY` |
+| **ChatGPT** (OpenAI) | gpt-4o, gpt-4-turbo | 128K | `OPENAI_API_KEY` |
+| **Gemini** (Google) | gemini-2.0-flash (+ vision) | 2M | `GOOGLE_API_KEY` |
+| **LM Studio** | Any local model | Varies | `--profile lmstudio` |
+| **Ollama** | llama3, codellama, etc. | Varies | `--profile ollama` |
+
+### Connection Profiles
+
+Switch between providers instantly:
+
+```bash
+# List profiles
+buddy --list-profiles
+
+# Use specific profile
+buddy --profile lmstudio
+
+# Auto-detect local servers
+buddy --detect-servers
+```
+
+### Profile Configuration
+
+```json
+// ~/.codebuddy/user-settings.json
+{
+  "connection": {
+    "activeProfileId": "grok",
+    "profiles": [
+      {
+        "id": "grok",
+        "name": "Grok API (xAI)",
+        "provider": "grok",
+        "baseURL": "https://api.x.ai/v1",
+        "model": "grok-4-latest"
+      },
+      {
+        "id": "lmstudio",
+        "name": "LM Studio Local",
+        "provider": "lmstudio",
+        "baseURL": "http://localhost:1234/v1",
+        "apiKey": "lm-studio"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Memory System
+
+Code Buddy features a sophisticated memory system inspired by OpenClaw:
+
+### Three Memory Subsystems
+
+| Subsystem | Storage | Purpose |
+|:----------|:--------|:--------|
+| **Persistent Memory** | Markdown files | Project/user notes |
+| **Enhanced Memory** | SQLite + embeddings | Semantic search |
+| **Prospective Memory** | SQLite | Tasks, goals, reminders |
+
+### Auto-Capture (OpenClaw Pattern)
+
+Automatically detects and stores important information:
+
+```typescript
+// Detected patterns (English + French)
+"Remember that..."        → Stored as instruction
+"I prefer..."             → Stored as preference
+"This project uses..."    → Stored as project fact
+"My email is..."          → Stored as contact info
+"We decided to..."        → Stored as decision
+```
+
+### Memory Lifecycle Hooks
+
+```typescript
+// Before execution: Inject relevant memories
+beforeExecute(context) → { injectedContext, recalledMemories }
+
+// After response: Capture important info
+afterResponse(context) → { capturedCount, capturedMemories }
+
+// Session end: Summarize conversation
+sessionEnd(sessionId) → { summaryId, memoriesStored }
+```
+
+### Deduplication
+
+- Jaccard similarity threshold: 0.95
+- Hash-based recent capture cache
+- Automatic duplicate detection
+
+---
+
+## Multi-Channel Support
+
+Code Buddy supports multiple messaging channels:
+
+| Channel | Status | Features |
+|:--------|:------:|:---------|
+| **Discord** | 🟡 Base | Bot integration, slash commands |
+| **Telegram** | 🟡 Base | Bot API, message handlers |
+| **Slack** | 🟡 Base | Bolt framework, events |
+| **Terminal** | ✅ Full | Native CLI interface |
+| **HTTP API** | ✅ Full | REST + WebSocket |
+
+### Channel Configuration
+
+```typescript
+// Enable Discord channel
+const discord = new DiscordChannel({
+  token: process.env.DISCORD_TOKEN,
+  allowedGuilds: ['guild-id'],
+});
+await discord.connect();
+```
+
+---
+
+## Security
+
+### Tool Policy System
+
+Fine-grained control over tool execution:
+
+```typescript
+const policy = new ToolPolicy({
+  allowlist: ['read_file', 'search', 'web_fetch'],
+  denylist: ['bash', 'write_file'],
+  requireConfirmation: ['delete_file'],
+});
+```
+
+### Bash Allowlist
+
+Secure command execution:
+
+```typescript
+const bashPolicy = new BashAllowlist({
+  patterns: [
+    /^npm (install|test|run)/,
+    /^git (status|diff|log)/,
+    /^ls -la?/,
+  ],
+  blocked: [
+    /rm -rf/,
+    /sudo/,
+    /curl.*\|.*sh/,
+  ],
+});
+```
+
+### Security Modes
+
+| Mode | Description |
+|:-----|:------------|
+| `suggest` | Confirm all operations |
+| `auto-edit` | Auto-approve safe ops |
+| `full-auto` | Full autonomy (YOLO) |
+
+```bash
+/mode suggest    # Maximum safety
+/mode full-auto  # Full autonomy
+```
+
+### Sandbox Isolation
+
+Docker-based execution environment:
+
+```typescript
+const sandbox = new DockerSandbox({
+  image: 'codebuddy/sandbox:latest',
+  memoryLimit: '512m',
+  networkMode: 'none',
+  timeout: 30000,
+});
+```
+
+---
+
+## Context Management
+
+### Context Window Guard
+
+Automatic context management with configurable thresholds:
+
+```typescript
+const guard = new ContextWindowGuard({
+  maxTokens: 128000,
+  warningThreshold: 0.8,  // Warn at 80%
+  compactionThreshold: 0.9,  // Compact at 90%
+});
+```
+
+### Smart Compaction
+
+Multi-stage compression:
+
+1. **Stage 1**: Remove tool results older than TTL
+2. **Stage 2**: Summarize older messages
+3. **Stage 3**: Aggressive truncation if needed
+
+### Hybrid Search
+
+Combined keyword + semantic search:
+
+```typescript
+const results = await hybridSearch({
+  query: "authentication flow",
+  keywordWeight: 0.3,
+  semanticWeight: 0.7,
+});
+```
+
+---
+
+## Tools
+
+### Built-in Tools
+
+| Category | Tools |
+|:---------|:------|
+| **File Operations** | `view_file`, `create_file`, `str_replace_editor`, `edit_file`, `multi_edit` |
+| **Search** | `search`, `codebase_map` |
+| **System** | `bash`, `docker`, `kubernetes` |
+| **Web** | `web_search`, `web_fetch`, `browser` |
+| **Planning** | `create_todo_list`, `get_todo_list`, `update_todo_list` |
+| **Media** | `screenshot`, `audio`, `video`, `ocr`, `clipboard` |
+| **Documents** | `pdf`, `document`, `archive` |
+
+### RAG-Based Tool Selection
+
+Tools are selected based on query relevance:
+
+```typescript
+// Query: "what's the weather in Paris?"
+// Selected tools: web_search, web_fetch
+// Not selected: bash, edit_file, etc.
+```
+
+---
+
+## API Server
+
+REST API with WebSocket support:
+
+### Starting the Server
+
+```bash
+buddy server --port 3000
+```
+
+### Endpoints
+
+| Endpoint | Method | Description |
+|:---------|:-------|:------------|
+| `/api/health` | GET | Health check |
+| `/api/metrics` | GET | Prometheus metrics |
+| `/api/chat` | POST | Chat completion |
+| `/api/chat/completions` | POST | OpenAI-compatible |
+| `/api/tools` | GET | List tools |
+| `/api/tools/{name}/execute` | POST | Execute tool |
+| `/api/sessions` | GET/POST | Session management |
+| `/api/memory` | GET/POST | Memory entries |
+| `/api/daemon/status` | GET | Daemon status |
+| `/api/daemon/health` | GET | Health metrics (CPU, memory) |
+| `/api/cron/jobs` | GET | List cron jobs |
+| `/api/cron/jobs/{id}/trigger` | POST | Trigger a cron job |
+| `/api/notifications/preferences` | GET/POST | Notification settings |
+
+### WebSocket Events
+
+```javascript
+const ws = new WebSocket('ws://localhost:3000/ws');
+
+// Authenticate
+ws.send(JSON.stringify({
+  type: 'authenticate',
+  payload: { token: 'jwt-token' }
+}));
+
+// Stream chat
+ws.send(JSON.stringify({
+  type: 'chat_stream',
+  payload: { messages: [{ role: 'user', content: 'Hello' }] }
+}));
+```
+
+---
+
+## Slash Commands
+
+| Command | Description |
+|:--------|:------------|
+| `/help` | Show help |
+| `/model [name]` | Change model |
+| `/mode [mode]` | Change security mode |
+| `/profile [id]` | Switch connection profile |
+| `/think` | Enable reasoning (4K tokens) |
+| `/megathink` | Deep reasoning (10K tokens) |
+| `/ultrathink` | Exhaustive reasoning (32K tokens) |
+| `/cost` | Show cost dashboard |
+| `/memory` | Memory management |
+| `/hooks list` | List lifecycle hooks |
+| `/plugin list` | List plugins |
+
+### Daemon Commands
+
+```bash
+buddy daemon start [--detach]  # Start background daemon
+buddy daemon stop              # Stop daemon
+buddy daemon restart           # Restart daemon
+buddy daemon status            # Show daemon status and services
+buddy daemon logs [--lines N]  # View daemon logs
+```
+
+### Trigger Commands
+
+```bash
+buddy trigger list             # List all event triggers
+buddy trigger add <pattern> <action>  # Add a trigger
+buddy trigger remove <id>      # Remove a trigger
+```
+
+### Voice & TTS Commands
+
+```bash
+buddy speak "Bonjour, je suis Code Buddy"   # Synthesize and play speech
+buddy speak --voice af_bella "Hello world"   # Use a specific voice
+buddy speak --list-voices                    # List available voices
+buddy speak --speed 1.5 "Fast speech"        # Adjust speed (0.25-4.0)
+buddy speak --format mp3 "Hello"             # Output format (wav, mp3)
+buddy speak --url http://host:8000 "Hello"   # Custom AudioReader URL
+```
+
+**In-chat voice commands:**
+
+| Command | Description |
+|:--------|:------------|
+| `/speak <text>` | Speak text with current TTS provider |
+| `/tts on\|off` | Enable/disable TTS |
+| `/tts auto` | Auto-speak all agent responses |
+| `/tts provider audioreader` | Switch to AudioReader (Kokoro-82M, local, free) |
+| `/tts voice ff_siwis` | Set voice (e.g., `ff_siwis` FR, `af_bella` EN) |
+
+**Supported TTS providers:** Edge TTS, espeak, macOS `say`, Piper, OpenAI, ElevenLabs, AudioReader (Kokoro-82M)
+
+**Infinite voice conversation:** Enable `continuousListening` + `autoSpeak` with AudioReader for a hands-free loop: listen → STT → agent → TTS → listen.
+
+---
+
+## Plugin System
+
+### Plugin Structure
+
+```
+~/.codebuddy/plugins/
+  my-plugin/
+    manifest.json
+    index.js
+```
+
+### Plugin Types
+
+- **Tool Plugins**: Add custom tools
+- **Provider Plugins**: Add LLM/embedding/search providers
+- **Command Plugins**: Add slash commands
+- **Hook Plugins**: Add lifecycle hooks
+
+### Example Plugin
+
+```typescript
+const plugin: Plugin = {
+  async activate(context: PluginContext) {
+    context.registerTool({
+      name: 'my_tool',
+      description: 'Custom tool',
+      execute: async (args) => {
+        return { success: true, output: 'Done!' };
+      }
+    });
+
+    context.registerProvider({
+      id: 'my-llm',
+      type: 'llm',
+      async chat(messages) { return 'response'; }
+    });
+  }
+};
+```
+
+---
+
+## Bundled Skills (40)
+
+Code Buddy includes 40 built-in SKILL.md files that provide domain-specific knowledge, best practices, and MCP server integration for popular software. Skills are loaded contextually when relevant to your project.
+
+| Category | Skill | Description |
+|----------|-------|-------------|
+| **PR Workflow** | `review-pr` | Code review checklist, inline comments, approval criteria |
+| | `prepare-pr` | Branch naming, commit cleanup, PR description template |
+| | `merge-pr` | Merge strategies, conflict resolution, post-merge cleanup |
+| **Dev Tools** | `github` | Issues, releases, Actions workflows, gh CLI |
+| | `gitlab` | GitLab API, glab CLI, CI/CD pipelines, merge requests |
+| | `session-logs` | Export/search conversation history and session metadata |
+| | `model-usage` | Token tracking, cost analysis, provider comparison |
+| | `tmux-sessions` | Terminal multiplexing, pane layouts, session management |
+| | `healthcheck` | Service monitoring, endpoint checks, alerting |
+| **Project** | `project-best-practices` | Project scaffolding, structure, linting, testing conventions |
+| | `csharp-avalonia` | Cross-platform desktop/mobile with C# and Avalonia UI |
+| | `coding-agent` | Autonomous multi-step coding with planning and validation |
+| | `skill-creator` | Author new SKILL.md files with YAML frontmatter |
+| **Creative & 3D** | `blender` | Python bpy scripting, CLI rendering, Geometry Nodes |
+| | `unreal-engine` | Remote Control API, Python editor scripting, Movie Render Queue |
+| | `davinci-resolve` | DaVinciResolveScript Python API, color grading, render queue |
+| | `ableton-live` | OSC protocol, MIDI Remote Scripts, Max for Live |
+| **Design** | `figma` | REST API, Plugin API, design tokens extraction |
+| | `gimp` | Python-Fu / Script-Fu scripting, batch image processing |
+| | `inkscape` | Extensions API, CLI export, SVG manipulation |
+| **DevOps & Infra** | `kubernetes` | kubectl, Helm, ArgoCD GitOps |
+| | `terraform-ansible` | Terraform IaC + Ansible configuration management |
+| | `grafana-prometheus` | Grafana HTTP API, PromQL, alerting pipelines |
+| | `jenkins-ci` | Jenkins API, Groovy pipelines, shared libraries |
+| **Workflow & Data** | `n8n` | REST API, webhook triggers, workflow automation |
+| | `databases` | PostgreSQL, MongoDB, Redis CLI and automation |
+| | `game-engines` | Unity C# + Godot GDScript, builds, scene management |
+| **Utilities** | `summarize` | Text/file/URL summarization with configurable length |
+| | `weather` | Weather lookups via wttr.in and OpenWeatherMap |
+| **Media** | `image-gen` | Image generation via DALL-E, Stable Diffusion, Midjourney |
+| | `whisper-transcribe` | Audio/video transcription with OpenAI Whisper |
+| | `pdf-tools` | PDF creation, merging, text extraction, conversion |
+| | `screenshot` | Screen capture, annotation, OCR text extraction |
+| | `video-tools` | FFmpeg video editing, conversion, thumbnails, GIFs |
+| | `gif-search` | GIF search via Giphy and Tenor APIs |
+| **Communication** | `email-tools` | Email send/read via himalaya CLI and SMTP |
+| | `notion` | Notion API for pages, databases, search, content blocks |
+| | `blog-watcher` | RSS/Atom feed monitoring, web page change detection |
+| **Smart Home** | `spotify` | Spotify playback control via spotify_player and Web API |
+| | `smart-home` | Philips Hue and Home Assistant control |
+
+Each skill includes **Direct Control** (CLI/API/scripting commands), **MCP Server Integration** (config for `.codebuddy/mcp.json`), and **Common Workflows** (step-by-step recipes). Skills are stored in `.codebuddy/skills/bundled/` and can be extended with managed or workspace skills via the Skills Registry.
+
+---
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/phuetz/code-buddy.git
+cd code-buddy
+npm install
+
+# Development mode
+npm run dev
+
+# Run tests
+npm test
+
+# Validate before commit
+npm run validate
+
+# Build
+npm run build
+```
+
+### Test Coverage
+
+```
+340+ tests across 25+ suites:
+- Tool Policy System (2 suites)
+- Bash Allowlist (2 suites)
+- Context Window Guard (34 tests)
+- Context Compaction (4 suites)
+- Moltbot Hooks (52 tests)
+- Connection Profiles (57 tests)
+- Desktop Automation (100 tests)
+- Middleware Pipeline (pipeline tests)
+- Agent Profiles & Streaming (reasoning, profiles)
+- Daemon Manager & Cron Bridge (lifecycle, PID, jobs)
+- Task Planner & Delegation (DAG, topological sort)
+- Screen Observer & Triggers (capture, diff, cooldown)
+- Proactive Agent & Notifications (rate limit, quiet hours)
+- Orchestrator (supervisor, shared context, self-healing, rollback)
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+| `GROK_API_KEY` | xAI API key | Required |
+| `ANTHROPIC_API_KEY` | Anthropic API key | - |
+| `OPENAI_API_KEY` | OpenAI API key | - |
+| `GOOGLE_API_KEY` | Google AI API key | - |
+| `SERPER_API_KEY` | Web search API key | - |
+| `GROK_BASE_URL` | Custom API endpoint | - |
+| `GROK_MODEL` | Default model | - |
+| `YOLO_MODE` | Full autonomy | `false` |
+| `MAX_COST` | Cost limit ($) | `10` |
+| `JWT_SECRET` | API server auth | Required in prod |
+
+### Project Settings
+
+Create `.codebuddy/settings.json`:
+
+```json
+{
+  "systemPrompt": "You are working on a TypeScript project.",
+  "tools": {
+    "enabled": ["read_file", "search", "bash"],
+    "disabled": ["web_search"]
+  },
+  "security": {
+    "mode": "auto-edit",
+    "bashAllowlist": ["npm *", "git *"]
+  }
+}
+```
+
+---
+
+## Roadmap
+
+### Planned Features
+
+| Feature | Priority | Status |
+|:--------|:---------|:-------|
+| Daemon Mode (background agent) | HIGH | ✅ Done |
+| Task Planner (DAG decomposition) | HIGH | ✅ Done |
+| Screen Observer & Triggers | HIGH | ✅ Done |
+| Proactive Agent (push notifications) | HIGH | ✅ Done |
+| Multi-Agent Orchestrator | HIGH | ✅ Done |
+| Self-Healing & Checkpoint Rollback | HIGH | ✅ Done |
+| Gateway WebSocket Control Plane | HIGH | 🔲 Planned |
+| Canvas A2UI Visual Workspace | HIGH | ✅ Done |
+| ClawHub Skills Registry | MEDIUM | ✅ Done |
+| OAuth Authentication | MEDIUM | 🔲 Planned |
+| Voice Wake Word Detection | MEDIUM | ✅ Done |
+| TTS Providers (OpenAI, ElevenLabs, AudioReader) | MEDIUM | ✅ Done |
+| Companion Apps (iOS, Android, macOS) | LOW | 🔲 Planned |
+| Tailscale Integration | LOW | 🔲 Planned |
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**API key not working**
+```bash
+echo $GROK_API_KEY  # Verify key is set
+buddy --prompt "test"
+```
+
+**Switching profiles doesn't work**
+```bash
+# Check current profile
+buddy --show-config
+
+# Force profile switch
+buddy --profile lmstudio --prompt "test"
+```
+
+**Memory not persisting**
+```bash
+# Check memory directory
+ls ~/.codebuddy/memory/
+
+# Clear and reinitialize
+rm -rf ~/.codebuddy/memory/
+buddy
+```
+
+**High latency**
+- Use a faster model: `buddy --model grok-code-fast-1`
+- Use local LLM: `buddy --profile ollama`
+
+### Debug Mode
+
+```bash
+DEBUG=codebuddy:* buddy
+```
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+
+**[Report Bug](https://github.com/phuetz/code-buddy/issues)** |
+**[Request Feature](https://github.com/phuetz/code-buddy/discussions)** |
+**[Star on GitHub](https://github.com/phuetz/code-buddy)**
+
+<sub>Inspired by [OpenClaw](https://github.com/openclaw/openclaw) | Multi-AI: Grok | Claude | ChatGPT | Gemini | LM Studio | Ollama</sub>
+
+</div>