/setup-dashclaw

name: setup-dashclaw
description: Set up a DashClaw instance, install the CLI tool, and configure Claude Code hooks
license: MIT
metadata:
  author: ucsandman
  version: "1.0.0"
  category: setup

Set Up DashClaw

Three ways to get DashClaw running, plus CLI and Claude Code hook setup.

---

Instance Setup

Option 1: Local Development

# Clone the repo
git clone git@github.com:ucsandman/DashClaw.git
cd DashClaw

# Install dependencies
npm install

# Run interactive setup (creates .env, initializes database)
node scripts/setup.mjs

# Start dev server
npm run dev
# → http://localhost:3000

**Required environment variables (.env):**

DATABASE_URL=postgresql://user:pass@localhost:5432/dashclaw
ENCRYPTION_KEY=<32-char-random-string>
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=<32-char-random-string>
DASHCLAW_API_KEY=<your-api-key>
DASHCLAW_MODE=self_host

Option 2: Cloud (Vercel + Neon)

1. Fork the DashClaw repo on GitHub 2. Deploy to Vercel (connect the fork) 3. Create a free Neon Postgres database 4. Set `DATABASE_URL` in Vercel environment variables 5. Run `node scripts/setup.mjs` locally pointing to your cloud instance 6. Grab your API key from the dashboard

Option 3: Demo Mode

npx dashclaw-demo
# Runs a local demo instance with fixture data
# Opens Decision Replay automatically
# Agent attempts risky deployment, DashClaw blocks it

Demo mode is read-only — no writes allowed. Good for exploring the UI.

Verify Setup

# Health check
curl http://localhost:3000/api/health

# Expected response:
# { "status": "ok", "database": "connected", "version": "2.x.x" }

Visit `http://localhost:3000/setup` for the instance readiness verification page.

---

CLI Installation

The `@dashclaw/cli` provides terminal-based approval workflows.

Install

npm install -g @dashclaw/cli

Configure

export DASHCLAW_BASE_URL=http://localhost:3000
export DASHCLAW_API_KEY=your-api-key
# Optional: export DASHCLAW_AGENT_ID=cli-operator

Commands

# Interactive approval inbox (TUI with live updates)
dashclaw approvals

# Approve a specific action
dashclaw approve act_abc123 --reason "Reviewed and safe"

# Deny a specific action
dashclaw deny act_abc123 --reason "Risk too high for current sprint"

# Help
dashclaw help

Interactive Mode Keyboard Shortcuts

| Key | Action | |-----|--------| | `↑/↓` | Navigate approvals | | `A` | Approve selected | | `D` | Deny selected | | `R` | Refresh list | | `O` | Open replay link in browser | | `Q` | Quit |

Risk scores are color-coded: green (<40), yellow (40-70), red (70+).

---

Claude Code Hooks

DashClaw provides pre/post tool hooks for Claude Code that create a policy-enforced execution pipeline. Hooks v2 govern 40+ tool types (not just Bash/Edit/Write/MultiEdit) with semantic classification via the bundled `dashclaw_agent_intel` module.

How It Works

Claude Code Tool Call (Bash/Edit/Write/MultiEdit)
        ↓
[PreToolUse: dashclaw_pretool.py]
   → Classify action (type, risk, systems)
   → POST to /api/guard
   → Allow / Warn / Block / Require Approval
   → Store action_id in temp file
        ↓
[Tool Executes] (unless blocked)
        ↓
[PostToolUse: dashclaw_posttool.py]
   → Read action_id from temp file
   → Determine outcome (completed/failed)
   → PATCH /api/actions/:id with result
        ↓
Full audit trail in DashClaw dashboard

Install Hooks

**Recommended:** use the one-command installer from your DashClaw checkout:

node /path/to/DashClaw/scripts/install-hooks.mjs --target=.

This copies all three governance hooks (`dashclaw_pretool.py`, `dashclaw_posttool.py`, `dashclaw_stop.py`) and the `dashclaw_agent_intel/` Python module into `.claude/hooks/`, then merges the `PreToolUse` / `PostToolUse` / `Stop` blocks into `.claude/settings.json`. Idempotent — safe to re-run after each `git pull`.

**Manual install** (if you need to control file placement):

1. Copy hook files into your project's `.claude/hooks/` directory:

mkdir -p .claude/hooks
cp /path/to/DashClaw/hooks/dashclaw_pretool.py .claude/hooks/
cp /path/to/DashClaw/hooks/dashclaw_posttool.py .claude/hooks/
cp /path/to/DashClaw/hooks/dashclaw_stop.py    .claude/hooks/
cp -r /path/to/DashClaw/hooks/dashclaw_agent_intel .claude/hooks/

The `dashclaw_agent_intel/` module is required — `dashclaw_pretool.py` imports it for semantic tool classification, so omitting it raises `ImportError` on the first governed tool call.

2. Add hook configuration to `.claude/settings.json` — three entries are needed: `PreToolUse` (governance gate), `PostToolUse` (outcome recorder), and `Stop` (LLM token + cost capture, plus auto-close fallback for any actions that PostToolUse missed):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python .claude/hooks/dashclaw_pretool.py",
            "timeout": 3660
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python .claude/hooks/dashclaw_posttool.py"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python .claude/hooks/dashclaw_stop.py"
          }
        ]
      }
    ]
  }
}

3. Set environment variables:

export DASHCLAW_BASE_URL=http://localhost:3000
export DASHCLAW_API_KEY=your-api-key
export DASHCLAW_AGENT_ID=claude-code
export DASHCLAW_HOOK_MODE=observe    # Start with observe, switch to enforce later
export DASHCLAW_RISK_THRESHOLD=60    # Default risk threshold
export DASHCLAW_GOVERNED_CATEGORIES=all  # Comma-separated tool categories or "all" (see below before narrowing)
export DASHCLAW_PERMISSION_MODE=standard # s