New:Microsoft Teams Notifications Are Now Available in Socket.Learn more →

@phuetz/code-buddy

Dependencies

Maintainers

Versions

Alerts

File Explorer

Advanced tools

License

Install Socket

Detect and block malicious and high-risk dependencies

Install

@phuetz/code-buddy

Open-source multi-provider AI coding agent for the terminal. Supports Grok, Claude, ChatGPT, Gemini, Ollama and LM Studio with 52+ tools, multi-channel messaging, skills system, and OpenClaw-inspired architecture.

Source

npm

Version: 0.1.25

Version published: 7 months ago

Weekly downloads: 270

Maintainers: 1

Weekly downloads

Created: 7 months ago

Source

Code Buddy

Multi-AI Personal Assistant with OpenClaw-Inspired Architecture

A powerful multi-AI terminal agent inspired by OpenClaw architecture. Supports Grok, Claude, ChatGPT, Gemini, LM Studio, and Ollama with advanced memory, multi-channel messaging, and intelligent context management.

What's New

OpenClaw-Inspired Features

Code Buddy incorporates advanced patterns from the 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`)

Phase 6 — Robustness & Developer Experience

Module	Status	Description
Web Search 5-Provider Chain	✅ 100%	Brave MCP → Brave API → Perplexity → Serper → DuckDuckGo with country/freshness/lang
Apply Patch Tool	✅ 100%	Unified diff parser and applier with fuzz factor (Codex-inspired)
Bash Parser	✅ 100%	AST-based command parsing via tree-sitter-bash with state-machine fallback
Per-Model Tool Config	✅ 100%	Capabilities, context window, patch format per model family
Head/Tail Truncation	✅ 100%	Smart output truncation keeping start + end of large results
Session Locks	✅ 100%	PID-based file locking with stale detection
Skill Scanner	✅ 100%	Static analysis of SKILL.md files for dangerous patterns (24 rules)
History Repair	✅ 100%	5-pass self-repair for malformed LLM message sequences
Cache Trace	✅ 100%	Debug prompt construction stages (`CACHE_TRACE=true`)
Turn Diff Tracker	✅ 100%	Per-turn file change tracking with rollback capability
MCP Predefined Servers	✅ 100%	Brave Search, Playwright, Exa pre-configured in MCP
Headless Mode Fixes	✅ 100%	Clean JSON stdout, `process.exit(0)`, Gemini message sanitization
Gemini Conversation Repair	✅ 100%	3-pass sanitization after context compression (orphan cleanup, role merge, user-start)

Phase 7 — Code Generation Security

Module	Status	Description
Centralized Dangerous Patterns	✅ 100%	Single registry for all dangerous patterns (bash, code, skills) with severity levels
Generated Code Validator	✅ 100%	Pre-write security scan for eval, XSS, SQL injection, hardcoded secrets, prototype pollution
Pre-Write Syntax Validator	✅ 100%	Balanced delimiters, template literals, indentation (JS/TS/Python/YAML/HTML/CSS/JSON)
Atomic Rollback (apply-patch)	✅ 100%	All-or-nothing patch application with full file state backup
Atomic Transactions (multi-edit)	✅ 100%	Multi-file edits rolled back on first failure
AST Bash Command Validation	✅ 100%	tree-sitter integration in command validator with centralized pattern checks
Bash Checkpoint	✅ 100%	Pre-snapshot of files targeted by destructive commands (rm, mv, truncate)
Shell Injection Fix	✅ 100%	Code formatter uses `spawnSync` stdin pipe instead of `execSync` echo
Diff Preview in Confirmation	✅ 100%	Shows actual diffs before approval, magnitude-based re-confirmation for large changes
Architect Parallel Execution	✅ 100%	Dependency-wave-based parallel step execution with DAG ordering
Semantic Truncation	✅ 100%	Error-preserving output truncation (keeps error lines, stack traces from middle sections)
Auto-Sandbox Router	✅ 100%	Automatic Docker routing for dangerous commands (npm, pip, cargo, make)
Security Audit Logging	✅ 100%	JSONL audit trail for all code generation security decisions
Copilot Proxy Hardening	✅ 100%	Per-IP rate limiting, token clamping, auth bypass fix, sanitized error messages

Phase 8 — OpenClaw Parity (Final)

Module	Status	Description
Skills Auto-Discovery	✅ 100%	Agent auto-finds/installs skills from hub when tool confidence is low
Device Node Connectors	✅ 100%	Real SSH, ADB, and local transports with platform-specific commands
Canvas Bidirectional Events	✅ 100%	Browser→agent event routing, data binding observers, state queries

Phase 9 — External Tool Integration

Module	Status	Description
RTK Output Compressor	✅ 100%	RTK integration — compresses bash output 60-90% via format-aware parsing, reducing token usage
ICM Memory Bridge	✅ 100%	ICM MCP server — persistent cross-session memory with episodic + semantic dual architecture
RTK Tool Hook	✅ 100%	After-hook at priority 90 auto-compresses bash results > 500 chars (configurable)
ICM MCP Predefined Server	✅ 100%	Pre-configured `icm mcp` stdio transport in MCP predefined servers
Integrations Config	✅ 100%	New `[integrations]` TOML section for RTK/ICM enable/disable and thresholds
Doctor RTK/ICM Checks	✅ 100%	`buddy doctor` reports RTK and ICM binary availability

Installation

Prerequisites

Node.js 18.0.0 or higher
ripgrep (recommended for faster search)
tree-sitter + tree-sitter-bash (optional, for AST-based bash command parsing)

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt-get install ripgrep

# Windows
choco install ripgrep

# Optional: tree-sitter for enhanced bash security parsing
npm install tree-sitter tree-sitter-bash

Install Code Buddy

# npm (recommended)
npm install -g @phuetz/code-buddy

# Or try without installing
npx @phuetz/code-buddy@latest

Quick Start

# 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 --base-url http://localhost:1234/v1 --api-key lm-studio

# Full autonomy mode
YOLO_MODE=true buddy

Headless Mode (CI / Scripting)

# Single prompt, JSON output to stdout (logs go to stderr)
buddy -p "create a hello world Express app" --output-format json > result.json

# Pipe into other tools
buddy -p "explain this code" --output-format json 2>/dev/null | jq '.content'

# Use in CI with full autonomy
buddy -p "run tests and fix failures" \
  --dangerously-skip-permissions \
  --output-format json \
  --max-tool-rounds 30

# Auto-approve all tool executions (no confirmation prompts)
buddy -p "fix lint errors" --auto-approve --output-format text

Headless mode exits cleanly after completion — safe for timeout, shell scripts, and CI pipelines.

Session Management

# Continue the most recent session
buddy --continue

# Resume a specific session by ID (supports partial matching)
buddy --resume abc123

# Set a cost limit for the session
buddy --max-price 5.00

Typical Project Workflow

# 1. First-time setup
buddy --setup                # Quick API key setup wizard
buddy onboard                # Full interactive config wizard
buddy doctor                 # Verify environment & dependencies

# 2. Start coding
buddy                        # Launch interactive chat
buddy --vim                  # Launch with Vim keybindings

# 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 --model gemini-2.5-flash  # Switch AI model
buddy --system-prompt architect # Use architect system prompt
buddy --agent my-custom-agent   # Use custom agent from ~/.codebuddy/agents/
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)

CLI Reference

Global Options

Flag	Short	Description	Default
`--version`	`-V`	Show version number	-
`--directory <dir>`	`-d`	Set working directory	`.`
`--api-key <key>`	`-k`	API key (or `GROK_API_KEY` env)	-
`--base-url <url>`	`-u`	API base URL (or `GROK_BASE_URL` env)	-
`--model <model>`	`-m`	AI model to use (or `GROK_MODEL` env)	auto-detect
`--prompt <prompt>`	`-p`	Single prompt, headless mode	-
`--browser`	`-b`	Launch browser UI instead of terminal	`false`
`--max-tool-rounds <n>`		Max tool execution rounds	`400`
`--security-mode <mode>`	`-s`	`suggest`, `auto-edit`, or `full-auto`	`suggest`
`--output-format <fmt>`	`-o`	Headless output: `json`, `stream-json`, `text`, `markdown`	`json`
`--context <patterns>`	`-c`	Glob patterns to load into context	-

Session & Cost

Flag	Description	Default
`--continue`	Resume the most recent saved session	-
`--resume <id>`	Resume a specific session (supports partial ID matching)	-
`--max-price <dollars>`	Maximum cost in dollars before stopping	`10.0`
`--no-cache`	Disable response caching	-

Autonomy & Permissions

Flag	Description	Default
`--auto-approve`	Automatically approve all tool executions	`false`
`--dangerously-skip-permissions`	Bypass all permission checks (trusted containers only)	`false`
`--no-self-heal`	Disable self-healing auto-correction	-
`--allow-outside`	Allow file operations outside workspace directory	`false`

Tool Control

Flag	Description	Example
`--force-tools`	Force-enable function calling for local models	-
`--probe-tools`	Auto-detect tool support at startup	-
`--enabled-tools <patterns>`	Only enable matching tools (glob, comma-separated)	`bash,file,search`
`--disabled-tools <patterns>`	Disable matching tools (glob, comma-separated)	`bash,web_*`
`--allowed-tools <patterns>`	Alias for `--enabled-tools` (Claude Code compat)	-

Agent & Prompt Configuration

Flag	Description	Default
`--system-prompt <id>`	System prompt: `default`, `minimal`, `secure`, `code-reviewer`, `architect` (or custom from `~/.codebuddy/prompts/`)	`default`
`--list-prompts`	List available system prompts and exit	-
`--agent <name>`	Use a custom agent from `~/.codebuddy/agents/`	-
`--list-agents`	List available custom agents and exit	-

Display & Debugging

Flag	Description
`--plain`	Minimal formatting (plain text output)
`--no-color`	Disable colored output
`--no-emoji`	Disable emoji in output
`--vim`	Enable Vim keybindings for input
`--mcp-debug`	Enable MCP protocol debugging output

Setup & Init

Flag	Description
`--init`	Initialize `.codebuddy/` directory with templates
`--dry-run`	Preview changes without applying (simulation mode)
`--setup`	Run interactive API key setup wizard
`--list-models`	List available models from the API and exit

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	`--base-url http://localhost:1234/v1`
Ollama	llama3, codellama, etc.	Varies	`--base-url http://localhost:11434/v1`

Connection Profiles

Switch between providers using CLI options or configuration:

# Use LM Studio (local)
buddy --base-url http://localhost:1234/v1 --api-key lm-studio

# Use Ollama (local)
buddy --base-url http://localhost:11434/v1 --model llama3

# Use a specific model
buddy --model grok-code-fast-1

Profile Configuration

// ~/.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
ICM (optional)	ICM MCP server	Persistent cross-session memory via episodic + semantic dual architecture

Auto-Capture (OpenClaw Pattern)

Automatically detects and stores important information:

// 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

// 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
Terminal	✅ Full	Native CLI interface (Ink/React)
HTTP API	✅ Full	REST + WebSocket
WebChat	✅ Full	Built-in HTTP + WebSocket with browser UI
Discord	🟡 Base	Bot integration, slash commands
Telegram	🟡 Base	Bot API, message handlers
Slack	🟡 Base	Bolt framework, events
WhatsApp	🟡 Base	Baileys (QR pairing, media, reconnect)
Signal	🟡 Base	signal-cli REST API (polling, groups)
Google Chat	🟡 Base	Workspace API (JWT auth, webhook events)
Microsoft Teams	🟡 Base	Bot Framework (OAuth2, adaptive cards)
Matrix	🟡 Base	matrix-js-sdk (E2EE, threads, media)

Channel Configuration

// 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:

const policy = new ToolPolicy({
  allowlist: ['read_file', 'search', 'web_fetch'],
  denylist: ['bash', 'write_file'],
  requireConfirmation: ['delete_file'],
});

Bash Allowlist

Secure command execution:

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)

/mode suggest    # Maximum safety
/mode full-auto  # Full autonomy

Sandbox Isolation

Docker-based execution environment:

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:

const guard = new ContextWindowGuard({
  maxTokens: 128000,
  warningThreshold: 0.8,  // Warn at 80%
  compactionThreshold: 0.9,  // Compact at 90%
});

Smart Compaction

Multi-stage compression:

Stage 1: Remove tool results older than TTL
Stage 2: Summarize older messages
Stage 3: Aggressive truncation if needed

Hybrid Search

Combined keyword + semantic search:

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`
Patching	`apply_patch` (unified diff)
Planning	`create_todo_list`, `get_todo_list`, `update_todo_list`
Media	`screenshot`, `audio`, `video`, `ocr`, `clipboard`
Documents	`pdf`, `document`, `archive`

Web Search (5-Provider Fallback Chain)

Code Buddy automatically cascades through available search providers:

Priority	Provider	API Key Required	Features
1	Brave MCP	`BRAVE_API_KEY` + MCP enabled	Full MCP integration, richest results
2	Brave API	`BRAVE_API_KEY`	Country, language, freshness filters
3	Perplexity	`PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`	AI-synthesized answers with citations
4	Serper	`SERPER_API_KEY`	Google Search results
5	DuckDuckGo	None	Free fallback (no API key needed)

Search parameters: country (ISO 3166), search_lang, ui_lang, freshness (pd/pw/pm/py or date range), provider (force specific).

MCP Predefined Servers

Four MCP servers are pre-configured (disabled by default):

buddy mcp add brave-search    # Brave Web Search (needs BRAVE_API_KEY)
buddy mcp add playwright      # Browser automation (no key needed)
buddy mcp add exa-search      # Exa neural search (needs EXA_API_KEY)
buddy mcp add icm             # Infinite Context Memory (needs `cargo install icm`)
buddy mcp list                # Show all configured servers

RAG-Based Tool Selection

Tools are selected based on query relevance:

// 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

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
`/api/heartbeat/status`	GET	Heartbeat engine status
`/api/heartbeat/start`	POST	Start heartbeat
`/api/heartbeat/stop`	POST	Stop heartbeat
`/api/heartbeat/tick`	POST	Trigger a single tick
`/api/hub/search?q=...`	GET	Search skills marketplace
`/api/hub/installed`	GET	List installed hub skills
`/api/hub/install`	POST	Install a skill
`/api/hub/{name}`	DELETE	Uninstall a skill
`/api/identity`	GET	List loaded identity files
`/api/identity/prompt`	GET	Combined identity prompt
`/api/identity/{name}`	PUT	Update an identity file
`/api/groups/status`	GET	Group security status
`/api/groups/list`	GET	List configured groups
`/api/groups/block`	POST	Block a user globally
`/api/groups/block/{userId}`	DELETE	Unblock a user
`/api/auth-profiles`	GET/POST/DELETE	Auth profile CRUD
`/api/auth-profiles/reset`	POST	Reset all cooldowns

WebSocket Events

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

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

buddy trigger list             # List all event triggers
buddy trigger add <spec>       # Add a trigger (format: type:condition action:target)
buddy trigger remove <id>      # Remove a trigger

Webhook Commands

buddy webhook list                          # List registered webhooks
buddy webhook add <name> <message> [opts]   # Register a new webhook
buddy webhook remove <id>                   # Remove a webhook

Hub Commands (Skills Marketplace)

buddy hub search <query>       # Search for skills
buddy hub install <name>       # Install a skill from the hub
buddy hub uninstall <name>     # Uninstall a skill
buddy hub update [name]        # Update all or a specific skill
buddy hub list                 # List installed skills
buddy hub info <name>          # Show details about a skill
buddy hub publish <path>       # Publish a skill to the hub
buddy hub sync                 # Sync installed skills with lockfile

Heartbeat Commands

buddy heartbeat start [opts]   # Start the heartbeat engine
buddy heartbeat stop           # Stop the heartbeat engine
buddy heartbeat status         # Show heartbeat status
buddy heartbeat tick           # Manually trigger a single tick

Identity Commands

buddy identity show            # Show loaded identity files (SOUL.md, USER.md, etc.)
buddy identity get <name>      # Show content of a specific identity file
buddy identity set <name> <c>  # Set content of an identity file
buddy identity prompt          # Show the combined identity prompt injection

Group Security Commands

buddy groups status            # Show group security status
buddy groups list              # List configured groups
buddy groups block <userId>    # Add a user to the global blocklist
buddy groups unblock <userId>  # Remove a user from the blocklist

Auth Profile Commands

buddy auth-profile list                   # List authentication profiles
buddy auth-profile add <id> <provider>    # Add a profile (API key rotation)
buddy auth-profile remove <id>            # Remove a profile
buddy auth-profile reset                  # Reset all cooldowns

Device Commands

buddy device list                         # List paired devices
buddy device pair --id <id> --name <name> --transport <ssh|adb|local>  # Pair a device
buddy device remove <id>                  # Remove a paired device
buddy device snap <id> [-o output.png]    # Take a screenshot on device
buddy device screenshot <id> [-o out.png] # Alias for snap
buddy device record <id> [-d 10] [-o out] # Record screen (duration in seconds)
buddy device run <id> -- <command>        # Run a command on device

Config Commands

buddy config show [--json]     # Show all environment variables and values
buddy config validate          # Validate current environment configuration
buddy config get <name>        # Show value and definition of a variable

Security Audit

buddy security-audit           # Run security audit of your environment
buddy security-audit --deep    # Deep scan (git history, npm audit)
buddy security-audit --fix     # Auto-fix file permission issues
buddy security-audit --json    # Output as JSON

Voice & TTS Commands

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

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

# 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

23,700+ tests across 554+ suites covering:
- Core: Tool Policy, Bash Allowlist, Context Window Guard, Compaction
- Agent: Middleware Pipeline, Profiles, Reasoning, Streaming
- Autonomy: Daemon, Cron Bridge, Task Planner, Delegation Engine
- Observation: Screen Observer, Triggers, Proactive Notifications
- Orchestration: Supervisor, Shared Context, Self-Healing, Rollback
- Providers: Gemini (vision + conversation), OpenAI-compat, Failover
- Security: Trust Folders, Skill Scanner, Bash Parser, Session Locks
- Infrastructure: MCP Client, Webhooks, Extensions, ACP Protocol, RTK Compressor, ICM Bridge
- Voice: Wake Word, TTS Providers, Voice Control Loop
- UI: ChatHistory, ChatInterface, TabbedQuestion

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	-
`BRAVE_API_KEY`	Brave Search API key	-
`EXA_API_KEY`	Exa neural search API key	-
`PERPLEXITY_API_KEY`	Perplexity AI search key (`pplx-...`)	-
`OPENROUTER_API_KEY`	OpenRouter key for Perplexity (`sk-or-...`)	-
`PERPLEXITY_MODEL`	Perplexity model	`perplexity/sonar-pro`
`PICOVOICE_ACCESS_KEY`	Porcupine wake word detection	-
`CACHE_TRACE`	Debug prompt construction stages	`false`
`YOLO_MODE`	Full autonomy	`false`
`MAX_COST`	Cost limit ($)	`10`
`JWT_SECRET`	API server auth	Required in prod

Optional Rust tools (install via cargo install):

Tool	Install	Purpose
RTK	`cargo install rtk`	Compresses bash output 60-90%, reducing token usage
ICM	`cargo install icm`	MCP server for persistent cross-session memory

Project Settings

Create .codebuddy/settings.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
Canvas A2UI Visual Workspace	HIGH	✅ Done
ClawHub Skills Registry	MEDIUM	✅ Done
Web Search 5-Provider Chain	HIGH	✅ Done
Apply Patch & Bash Parser	HIGH	✅ Done
Per-Model Tool Config	MEDIUM	✅ Done
Voice Wake Word Detection	MEDIUM	✅ Done
TTS Providers (OpenAI, ElevenLabs, AudioReader)	MEDIUM	✅ Done
Code Generation Security (Phase 7)	HIGH	✅ Done
Auto-Sandbox Router	HIGH	✅ Done
Semantic Output Truncation	MEDIUM	✅ Done
Gateway WebSocket Control Plane	HIGH	🔲 Planned
OAuth Authentication	MEDIUM	🔲 Planned
Companion Apps (iOS, Android, macOS)	LOW	🔲 Planned
Tailscale Integration	LOW	🔲 Planned

Troubleshooting

Common Issues

API key not working

echo $GROK_API_KEY  # Verify key is set
buddy --prompt "test"

Switching providers doesn't work

# Verify connection to local model
buddy --base-url http://localhost:1234/v1 --api-key lm-studio --prompt "test"

# List available models
buddy --list-models

Memory not persisting

# 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 --base-url http://localhost:11434/v1 --model llama3

Debug Mode

DEBUG=codebuddy:* buddy

License

MIT License - see LICENSE for details.

Report Bug | Request Feature | Star on GitHub

_{Inspired by OpenClaw | Multi-AI: Grok | Claude | ChatGPT | Gemini | LM Studio | Ollama}

Keywords

FAQs

What is @phuetz/code-buddy?

Is @phuetz/code-buddy popular?

Is @phuetz/code-buddy well maintained?

Package last updated on 17 Feb 2026