Setup Dashclaw

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

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.

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

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

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

2. Add hook configuration to .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python .claude/hooks/dashclaw_pretool.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python .claude/hooks/dashclaw_posttool.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

Hook Modes

• observe — Logs all decisions but never blocks. Use this first to understand what would be caught.
• enforce — Blocks tool execution when guard returns block or approval is denied/times out.

Action Type Mapping (Pretool)

The pretool automatically classifies tool calls:

Bash commands:

File operations (Edit/Write/MultiEdit):

Approval Timeout

When the guard returns require_approval, the pretool polls for 30 seconds. If no decision is made, the tool is blocked (enforce mode) or allowed (observe mode).

Use dashclaw approvals in another terminal to approve in real-time.

Graceful Degradation

If DashClaw is unreachable (missing env vars, server down, network error), hooks exit 0 and allow tool execution. The hooks never break your development workflow.