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

1. 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"
          }
        ]
      }
    ]
  }
}

1. 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 # standard | elevated | admin

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:
| Pattern | Action Type | Risk | Reversible |
|---------|------------|------|------------|
| git push, git merge, git rebase | deploy | 80 | false |
| npm run deploy, vercel deploy | deploy | 75-85 | false |
| terraform apply | deploy | 85 | false |
| rm -rf, DROP TABLE | security | 90 | false |
| .env, secret, key file access | security | 85 | false |
| npm install, pip install | build | 30 | true |
| curl, wget | api | 40 | true |

File operations (Edit/Write/MultiEdit):
| File Pattern | Action Type | Risk |
|-------------|------------|------|
| .env, secrets, credentials | security | 85 |
| migration, schema | migrate | 70 |
| auth, middleware | security | 75 |
| Other files | file_write | 15 |

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 the hook is unconfigured (no DASHCLAW_BASE_URL/DASHCLAW_API_KEY), it exits 0 and the tool runs ungoverned; half-configured warns on stderr and still exits 0. But a server down or network error is not the same case: in enforce mode the hook fails closed and blocks (exit 2), because an action that could not be governed must not proceed. Override with DASHCLAW_GUARD_UNAVAILABLE_POLICY=warn|allow (not recommended). Observe mode never blocks either way, and every outage is written to ~/.dashclaw/orphan-actions.jsonl for backfill on recovery.

Governed categories — narrowing the scope is visible

DASHCLAW_GOVERNED_CATEGORIES decides which tool categories call the guard at all. This is a scope knob, not a mode knob, and it is sharper than it looks: for a category it excludes, the hook exits before the network call, so those tool calls produce no decision row, no witness and no signal. Their absence from /decisions is indistinguishable from an agent that simply did nothing.

Default governed set: execution,orchestration,file_io,interactive,mcp. search and system are ungoverned out of the box by design. Unknown tools that match no category fail safe to governed.

Since v5.20 the hook declares the categories it is not governing on the calls it does still make, and any category dropped below that default set raises the red Governance scope narrowed (ungoverned_scope) signal naming what is unwatched. A healthy default install declares nothing and raises nothing. This is a visibility guarantee, not an enforcement one — the variable lives on the agent's own machine — but it catches the case that actually happens: a misconfigured agent, or a typo that silently dropped a real category (file-io is not file_io).

Related policy types

Hooks v2 enrichment feeds three guard policy types (these are policies you configure, not signals the dashboard emits):

• permission_escalation — matches when the action requires elevated permissions
• green_contract — requires a test-verification level before deploys
• branch_freshness — matches deploys from a stale or diverged branch

Blocked decisions may also carry a recovery recipe: actionable remediation steps returned alongside the verdict. Monitor the resulting risk signals in the dashboard or via /api/signals.

Session Setup (Recommended)

For long-running Claude Code sessions, create a session to enable lifecycle tracking and recovery:

# Sessions are created automatically by hooks when DASHCLAW_SESSION_TRACKING=true
export DASHCLAW_SESSION_TRACKING=true

Session tracking is optional. When enabled, the pretool hook creates a session on first invocation and reports status updates throughout the session. If a session is interrupted, DashClaw records the last checkpoint for recovery.