claude-board 0.1.5

Physical console for Claude Code - approve/deny permissions from your phone or hardware device

Claude Board

A permission approval console for Claude Code - approve or deny permission requests from your phone or (future) a physical hardware device.

Requirements

Important: Claude Board works with Claude Code CLI only.

Environment	Supported	Notes
Terminal (claude command)	✅ Yes	Full support
VS Code Extension	✅ Yes	Full support
Claude Desktop (CLI mode)	✅ Yes	When using built-in CLI
Claude Desktop (Chat interface)	❌ No	Does not support hooks

Why doesn't Claude Desktop chat work?

Claude Desktop's chat interface and Claude Code CLI are different products with different architectures:

• Claude Code CLI uses ~/.claude/settings.json and supports Hooks for permission interception
• Claude Desktop uses claude_desktop_config.json and supports MCP Servers for tool extension

Hooks are a Claude Code CLI-specific feature. The Claude Desktop chat interface has no "permission request" concept, so there's no PermissionRequest event to intercept.

Features

• Web UI: Approve/deny requests from any device with a browser (phone, tablet, desktop)
• Real-time updates: WebSocket-based instant notifications
• Sound & vibration: Get alerted when permission is needed
• YOLO mode: Auto-approve all requests with one click
• TODO tracking: See Claude's task list in real-time
• Keyboard shortcuts: Y/Enter to approve, N/Escape to deny

Installation

Using pip

pip install claude-board

Using uv

uv tool install claude-board

From source

git clone https://github.com/pescn/claude-board.git
cd claude-board
pip install -e .

Quick Start

1. Install hooks into Claude Code

claude-board install

This adds hooks to ~/.claude/settings.json. Your existing hooks are preserved.

2. Start the server

claude-board serve

3. Open the URL on your phone

The server will display a URL like http://192.168.x.x:8765 - open it on your phone.

4. Restart Claude Code

Claude Code needs to be restarted to load the new hooks.

That's it! Now when Claude Code needs permission to run a command, you'll get a notification on your phone.

Commands

# Start the web server
claude-board serve [--port 8765] [--open]

# Install hooks (preserves existing hooks)
claude-board install [--scope user|local]

# Uninstall hooks
claude-board uninstall [--scope user|local] [--all]

# Check status
claude-board status

# View/modify configuration
claude-board config [--port PORT] [--yolo/--no-yolo]

# Show version
claude-board --version

Configuration

Environment Variables

• CLAUDE_BOARD_HOST: Server host (default: 127.0.0.1)
• CLAUDE_BOARD_PORT: Server port (default: 8765)

Safe Tools (Auto-Approved)

These tools are automatically approved without sending to your phone:

• Glob, Grep - File searching
• TodoWrite, TodoRead - Task management
• Task - Subagent tasks
• WebSearch, WebFetch - Web operations
• Read (within project directory)

Dangerous Tools (Require Approval)

• Bash - Shell commands
• Write - Creating/overwriting files
• Edit - Modifying files

Roadmap

Phase 0 (Current): Web UI ✅

Pure software solution with web-based approval.

Phase 1: Raspberry Pi (Planned)

Physical console with:

• Mechanical key switches (Approve, Deny, Retry, YOLO)
• E-ink display for task status
• Wired connection

Phase 2: Bluetooth (Planned)

Wireless physical console with BLE connectivity.

Phase 3: ESP32 Standalone (Planned)

Battery-powered portable device.

Development

# Clone and install in development mode
git clone https://github.com/pescn/claude-board.git
cd claude-board
pip install -e ".[dev]"

# Run tests
pytest

# Start server in development
claude-board serve --port 8765

License

MIT

Contributing

Contributions are welcome! Please open an issue or pull request.