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 [e-mail]: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.

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:

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 DashClaw is unreachable (missing env vars, server down, network error), hooks exit 0 and allow tool execution. The hooks never break your development workflow.