devclaw

DevClaw

AI agent for tech teams. Single binary. Runs everywhere.

Open-source AI agent for tech teams — devs, DevOps, QA, PMs, designers, and everyone in between. Single Go binary with CLI, WebUI, MCP server, and messaging channels. Full system access, persistent memory, encrypted vault, and 70+ built-in tools.

Not a chatbot. Not an IDE. Not a framework. DevClaw is the AI backend that IDEs, terminals, and channels access — giving any tool persistent memory, infrastructure access, and integrations.

Docs | Getting Started | Skills | Releases

Quick Start

One-Command Install (Recommended)

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/jholhewres/devclaw/master/install/unix/install.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/jholhewres/devclaw/master/install/windows/install.ps1 | iex

The installer downloads the pre-built binary from GitHub Releases. If unavailable, it falls back to go install or building from source.

Docker

No Go, Node, or build tools required — just Docker:

git clone https://github.com/jholhewres/devclaw.git && cd devclaw
docker compose up -d

Open http://localhost:8090/setup to configure your API key and start using DevClaw.

The container includes bash, python, node, git, and other tools the agent needs to execute scripts.

From Source

Requires Go 1.24+ and Node 22+:

git clone https://github.com/jholhewres/devclaw.git && cd devclaw
make build                  # builds frontend + Go binary
./bin/devclaw serve         # starts server

See install/source/README.md for detailed build instructions.

Go Install

Requires Go 1.24+ (CGO enabled, SQLite dependency):

CGO_ENABLED=1 go install -tags 'sqlite_fts5' github.com/jholhewres/devclaw/cmd/devclaw@latest
devclaw serve

Note: This builds without the WebUI. For full functionality (dashboard, setup wizard), use Docker or build from source.

Setup Wizard

After starting the server, the setup wizard is available at:

http://localhost:8090/setup

It guides you through:

1. API provider and key configuration
2. Channel setup (WhatsApp, Discord, Telegram, Slack)
3. Security settings (vault password, access control)
4. Skills installation

All secrets are stored in the encrypted vault (.devclaw.vault), never in plain text.

Highlights

• Single binary — one go build, zero runtime dependencies
• 9 LLM providers — OpenAI, Anthropic, Ollama, Groq, Google AI, Z.AI, xAI, OpenRouter, and any OpenAI-compatible endpoint
• N-provider fallback chain — rate-limited model → fallback → local Ollama, with per-model cooldowns and budget tracking
• 90+ built-in tools — Git, Docker, databases, testing, deploy, DORA metrics, team coordination, and much more
• Native media — receive/send images, audio, documents with auto-enrichment (vision, transcription, text extraction)
• Teams system — persistent agents with roles, shared memory, tasks, documents, and @mention notifications
• MCP server — any IDE (Cursor, VSCode, Claude Code, Windsurf) connects via Model Context Protocol
• Pipe mode — git diff | devclaw diff or npm build 2>&1 | devclaw fix
• Quick commands — devclaw fix, devclaw explain ., devclaw commit, devclaw how "task"
• Extensible skills — install from devclaw-skills or create your own
• 4 channels — WhatsApp, Discord, Telegram, Slack
• WebUI — React dashboard with SSE streaming, session management, and setup wizard
• Gateway API — OpenAI-compatible HTTP API + WebSocket JSON-RPC
• Encrypted vault — AES-256-GCM + Argon2id for all secrets
• Persistent memory — SQLite FTS5 + vector embeddings for long-term context
• Daemon manager — start, monitor, and control background processes (dev servers, watchers)
• Subagents — spawn concurrent child agents for parallel tasks (research, code, deploy simultaneously)
• Plugin system — GitHub, Jira, Sentry integrations with webhook support
• Shell hook — auto-capture failed commands and suggest devclaw fix

How It Works

┌──────────────────────────────────────────────────────┐
│                    Interfaces                        │
│  CLI   WebUI   WhatsApp   Discord   Telegram   Slack │
└──────────────────────┬───────────────────────────────┘
                       │
        ┌──────────────▼──────────────┐
        │         Assistant           │
        │       (agent loop)          │
        └──┬──────┬──────────┬────┬───┘
           │      │          │    │
    ┌──────▼──┐ ┌─▼──────┐ ┌▼──────────┐
    │  Tools  │ │  LLM   │ │  Memory   │
    │  (90+)  │ │ Client │ │ (SQLite)  │
    └─────────┘ └────────┘ └───────────┘
           │
    ┌──────▼────────────────────────────┐
    │          Subagent Manager         │
    │  (up to 8 concurrent child agents │
    │   with isolated sessions + tools) │
    └───────────────────────────────────┘
           │
    ┌──────▼────────────────────────────┐
    │          Teams System             │
    │  (persistent agents with roles,   │
    │   shared memory, tasks, @mentions)│
    └───────────────────────────────────┘
           │
    ┌──────▼────────────────────────────────┐
    │            MCP Server                 │
    │  (stdio + SSE — for IDE integration)  │
    └───────────────────────────────────────┘
           │
    ┌──────▼──────────────────────────────┐
    │  Cursor  VSCode  Claude Code  Aider │
    │  OpenCode  Windsurf  Zed  Neovim    │
    └─────────────────────────────────────┘

Tools

90+ built-in tools across 22 categories:

MCP Server (IDE Integration)

DevClaw exposes all tools via the Model Context Protocol, making it a backend for any AI coding tool:

devclaw mcp serve    # starts MCP server on stdio

Cursor / VSCode (.cursor/mcp.json or .vscode/mcp.json):

{
  "mcpServers": {
    "devclaw": {
      "command": "devclaw",
      "args": ["mcp", "serve"]
    }
  }
}

Claude Code (.mcp.json):

{
  "mcpServers": {
    "devclaw": {
      "command": "devclaw",
      "args": ["mcp", "serve"]
    }
  }
}

Works with: Cursor, VSCode, Claude Code, OpenCode, Windsurf, Zed, Neovim, and any MCP-compatible client.

CLI Reference

devclaw serve                  Start daemon with channels + WebUI
devclaw chat "message"         Single message or interactive REPL
devclaw setup                  Web-based setup wizard
devclaw mcp serve              Start MCP server for IDE integration

devclaw fix [file]             Analyze and fix errors
devclaw explain [path]         Explain code, files, or directories
devclaw diff [--staged]        AI review of git changes
devclaw commit [--dry-run]     Generate commit message and commit
devclaw how "task"             Generate shell commands without executing

devclaw config init            Create default config.yaml
devclaw config vault-init      Initialize encrypted vault
devclaw config vault-set       Store API key in vault
devclaw skill install <name>   Install a skill
devclaw skill list             List installed skills
devclaw schedule list          Show scheduled jobs
devclaw health                 Health check (Docker/monitoring)
devclaw shell-hook bash        Generate shell integration
devclaw completion bash        Generate shell completions

Pipe mode:

git diff | devclaw "review this"
npm run build 2>&1 | devclaw fix
cat error.log | devclaw "what went wrong?"

Configuration

Minimal config.yaml:

name: "DevClaw"
trigger: "@devclaw"
model: "gpt-4.1-mini"

api:
  base_url: "https://api.openai.com/v1"
  api_key: "${DEVCLAW_API_KEY}"

webui:
  enabled: true
  address: ":8090"

See configs/devclaw.example.yaml for the full reference.

Database

DevClaw uses SQLite by default — zero configuration required. Just run and it works.

For production or multi-user setups, you can optionally switch to PostgreSQL or Supabase with pgvector support for faster vector search at scale.

The agent can manage the database through 8 built-in tools: check status, run queries, view schema, create backups, and more. All database operations include security protections against SQL injection and abuse.

Skills

Extend DevClaw with installable skills:

devclaw skill install github
devclaw skill install docker
devclaw skill search kubernetes
devclaw skill list

Browse the catalog: devclaw-skills

Subagents

DevClaw can spawn concurrent child agents to handle multiple tasks in parallel. The main agent delegates work to subagents, each running in its own goroutine with an isolated session and filtered tool set.

Main Agent
  ├── spawn_subagent("research API docs")     → runs concurrently
  ├── spawn_subagent("write unit tests")      → runs concurrently
  └── spawn_subagent("check deploy status")   → runs concurrently
         │
         ▼
  Results announced back to parent when done

How it works:

• spawn_subagent — creates a child agent with a specific task, returns a run_id immediately
• list_subagents — check status of all running/completed subagents
• wait_subagent — block until a subagent finishes and get its result
• stop_subagent — cancel a running subagent

Key properties:

• Up to 8 concurrent subagents (configurable)
• Each subagent gets its own isolated session and filtered tools (no recursion, no memory writes)
• Configurable timeout (default: 10min) and optional model override per subagent
• Results are persisted to SQLite — survive process restarts
• Push-style announce — parent is notified immediately when a subagent completes

Example use cases:

• Research multiple topics simultaneously while the main agent continues working
• Run tests in background while writing code
• Deploy to staging while generating release notes
• Audit dependencies across multiple languages in parallel

# config.yaml
subagents:
  enabled: true
  max_concurrent: 8
  timeout_seconds: 600
  denied_tools:
    - spawn_subagent    # no recursion
    - memory_save       # no memory pollution
    - cron_add          # no scheduling

Teams System

DevClaw Teams adds persistent agents with roles, shared memory, and real-time collaboration:

┌─────────────────────────────────────────────────────────┐
│                     TeamManager                          │
│  - Create teams and persistent agents                   │
│  - Agent roles: junior, mid, senior, lead               │
│  - Heartbeat scheduling for proactive behavior          │
│  - @mention parsing and active notification push        │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│                     TeamMemory                           │
│  - Tasks (CRUD, status workflow)                        │
│  - Messages (@mentions, thread subscriptions)           │
│  - Facts (shared key-value store)                       │
│  - Documents (deliverables with versioning)             │
│  - Working State (WORKING.md pattern)                   │
└──────────────────────────────────────────────────────────┘

Key features:

• Persistent agents: Long-lived agents with personalities and instructions
• Team memory: Shared tasks, facts, documents accessible by all team members
• Thread subscriptions: Auto-subscribe to threads for continuous notifications
• Working state: Agents persist work-in-progress across heartbeats
• Active push: Agents triggered immediately on @mentions (not just on heartbeat)

Example workflow:

# Create a team
team_create(name="Engineering", description="Dev team")

# Create agents with roles
team_create_agent(team_id="abc123", name="Friday", role="Squad Lead", level="lead")
team_create_agent(team_id="abc123", name="Hobbs", role="Writer", level="mid")

# Assign tasks with @mentions
team_create_task(title="Write API docs", assignees=["hobbs"])
team_comment(thread_id="task-123", content="@hobbs please start with auth endpoints")

# Agent receives notification immediately and on heartbeat

See docs/teams.md for full documentation.

Channels

See docs/channels.md for setup instructions.

Security

• Encrypted vault — AES-256-GCM + Argon2id, all secrets encrypted at rest
• Tool guard — ACL-based permission system with dangerous command blocking
• Sandbox — skill scripts run in isolated environment
• Audit logging — all tool executions logged
• SSRF protection — web_fetch blocks internal network access
• Budget tracking — monthly cost limits with configurable alerts

See docs/security.md for details.

Deployment

Docker Compose:

cd install/docker
docker compose up -d
docker compose logs -f devclaw

Data is persisted in a Docker volume (devclaw-state). Rebuilds (docker compose build) preserve all sessions, memory, and configuration.

To give the agent access to host directories, add bind mounts in docker-compose.yml:

volumes:
  - ./skills:/home/devclaw/skills
  - ./workspace:/home/devclaw/workspace
  - /path/to/projects:/home/devclaw/projects  # custom mount

Ansible (production):

Deploy to Linux servers with a single playbook:

cd install/providers/ansible
cp inventory.example inventory
# Edit inventory with your server details
ansible-playbook -i inventory playbook.yml

See install/providers/ansible/README.md for details.

systemd (Linux servers):

Recommended for production Linux servers. Provides automatic restart, logging, and resource management.

# Option 1: Create dedicated user (recommended)
sudo useradd -m -s /bin/bash devclaw

# Option 2: Use existing user (replace YOUR_USER)
# Skip useradd, use your username in the service file below

# Build and install
make build
sudo cp bin/devclaw /usr/local/bin/

# Setup directory and config
sudo mkdir -p /opt/devclaw
sudo cp config.yaml /opt/devclaw/
sudo chown -R devclaw:devclaw /opt/devclaw  # or YOUR_USER:YOUR_USER

Create service file /etc/systemd/system/devclaw.service:

[Unit]
Description=DevClaw - AI Agent for Tech Teams
After=network.target
Documentation=https://github.com/jholhewres/devclaw

[Service]
Type=simple
User=devclaw
Group=devclaw
WorkingDirectory=/opt/devclaw
ExecStart=/usr/local/bin/devclaw serve --config /opt/devclaw/config.yaml
Restart=on-failure
RestartSec=5

# Security options (adjust based on your needs)
NoNewPrivileges=false    # Set to true to disable sudo access
PrivateTmp=true
ProtectKernelTunables=true

# Resource limits
LimitNOFILE=65535

# Environment (optional - for vault password)
# EnvironmentFile=-/opt/devclaw/.env

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now devclaw

# Check status and logs
sudo systemctl status devclaw
sudo journalctl -u devclaw -f

Note: If you need the agent to run sudo commands, set NoNewPrivileges=false. For hardened security, set it to true and the agent will not be able to elevate privileges.

PM2 (Node.js process manager):

Good option for development or when you already use PM2 in your stack.

# Install PM2 if not already installed
npm install -g pm2

# Build DevClaw
make build

# Start with PM2
pm2 start ./bin/devclaw --name devclaw -- serve

# Save process list and enable auto-start on reboot
pm2 save
pm2 startup   # follow the command it prints

# Useful commands
pm2 logs devclaw      # view logs
pm2 restart devclaw   # restart
pm2 stop devclaw      # stop
pm2 delete devclaw    # remove from PM2
pm2 monit             # resource monitor

PM2 ecosystem file (ecosystem.config.js) for more control:

module.exports = {
  apps: [{
    name: 'devclaw',
    script: './bin/devclaw',
    args: 'serve',
    cwd: '/home/youruser/devclaw',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production'
    }
  }]
}

Then run: pm2 start ecosystem.config.js

Makefile (simple background):

# Run in background with nohup
make serve &

# Or with output redirect
nohup make serve > devclaw.log 2>&1 &

Documentation

Author

Jhol Hewres — @jholhewres

License

MIT