claude-dojo 1.1.0 → 1.1.2

package/README.md

@@ -1,82 +1,198 @@
 # Claude Dojo
 
-A visual dashboard for Claude AI - watch agents work in a 3D hex-grid interface.
+A visual agent dashboard for Claude AI - watch agents work in an interactive 3D hex-grid interface.
 
-## Requirements
+![Claude Dojo](https://img.shields.io/badge/Claude-Dojo-blueviolet)
+![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)
+![License](https://img.shields.io/badge/license-MIT-blue)
 
-- Node.js >= 18.0.0
-- Anthropic API key
+## Features
 
-## Setup
+- **3D Hex Grid Visualization** - Watch multiple Claude sessions as interactive hexagonal tiles with real-time status updates
+- **Subagent System** - Visualize spawned subagents (Explore, Plan, Bash, Read, Write, Glob) orbiting their parent session
+- **Real Tool Execution** - Claude can read/write files and execute shell commands on your system
+- **Permission System** - Approve or deny file writes and command execution (like Claude Code CLI)
+- **Real-time Streaming** - Watch responses stream in as Claude generates them
+- **Token Tracking** - Visual context bar showing token usage with color-coded thresholds
+- **Session Persistence** - Sessions survive server restarts
+- **Slash Commands** - 14 built-in commands with autocomplete
+- **Markdown Rendering** - Rich formatting with syntax-highlighted code blocks
+- **Resizable Panels** - Drag to adjust the canvas/chat split
 
-Set your Anthropic API key:
+## Quick Start
 
-```bash
-export ANTHROPIC_API_KEY="your-api-key-here"
-```
+### Requirements
 
-## Usage
+- Node.js >= 18.0.0
+- Anthropic API key (or AWS credentials for Bedrock)
+
+### Installation
 
 ```bash
+# Set your API key
+export ANTHROPIC_API_KEY="your-api-key-here"
+
+# Run with npx (no install needed)
 npx claude-dojo
 ```
 
-This starts the server and opens the dashboard in your browser.
-
-## Upgrading
+This starts the server and opens the dashboard in your browser at `http://localhost:3001`.
 
-To update to the latest version:
+### Upgrading
 
 ```bash
 npx claude-dojo@latest
 ```
 
-Or if you installed globally:
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ANTHROPIC_API_KEY` | Your Anthropic API key | Required (unless using Bedrock) |
+| `PORT` | Server port | `3001` |
+| `ANTHROPIC_MODEL` | Claude model to use | `claude-sonnet-4-20250514` |
+| `CLAUDE_CODE_USE_BEDROCK` | Use AWS Bedrock instead of Anthropic API | `false` |
+| `AWS_REGION` | AWS region for Bedrock | `us-east-1` |
+| `CLAUDE_DOJO_NO_BROWSER` | Don't auto-open browser on start | `false` |
+
+### AWS Bedrock Support
+
+To use Claude via AWS Bedrock instead of the Anthropic API:
 
 ```bash
-npm update -g claude-dojo
-```
+# Set environment variables
+export CLAUDE_CODE_USE_BEDROCK=1
+export AWS_REGION=us-east-1
+export ANTHROPIC_MODEL=anthropic.claude-sonnet-4-20250514-v1:0
 
-## Features
+# Ensure AWS credentials are configured
+aws configure
 
-- **3D Hex Grid** - Visualize multiple Claude sessions as interactive hexagonal tiles
-- **Real-time Streaming** - Watch responses stream in as Claude generates them
-- **Multi-session Support** - Run multiple conversations in parallel
-- **Subagents** - Spawn specialized agents (Explore, Plan, Bash, general-purpose)
-- **Token Tracking** - Visual context bar showing token usage
-- **Session Persistence** - Sessions survive server restarts
-- **Resizable Panels** - Drag to resize the canvas/chat split
-- **Markdown Rendering** - Rich formatting in chat messages
+# Run Claude Dojo
+npx claude-dojo
+```
+
+The Bedrock SDK is included - no additional installation needed.
 
 ## Slash Commands
 
+Type `/` in the input to see available commands with autocomplete.
+
 | Command | Description |
 |---------|-------------|
-| `/help` | Show available commands |
-| `/status` | Display session status and token usage |
+| `/help` | Show available commands and usage |
+| `/status` | Display session status, token usage, and system info |
 | `/clear` | Clear conversation history |
-| `/compact` | Compress context by summarizing messages |
-| `/todos` | Manage session todo list |
+| `/compact` | Compress context by summarizing older messages |
+| `/todos` | View and manage the task list |
 | `/resume` | List and resume previous sessions |
-| `/rewind` | Undo recent messages |
-| `/export` | Export conversation to markdown |
-| `/model` | Change the Claude model |
-| `/settings` | View/modify settings |
+| `/rewind` | Undo recent messages or restore snapshots |
+| `/export` | Export conversation to JSON or Markdown |
+| `/model` | View or change the Claude model |
+| `/system` | View or modify the system prompt |
+| `/settings` | View and modify session settings |
+| `/file` | Read a file into the conversation |
+| `/search` | Search for patterns in files |
+| `/run` | Execute a shell command |
 
 ## Keyboard Shortcuts
 
 | Key | Action |
 |-----|--------|
-| `1-9` | Select session by index |
+| `1-9` | Select session by index (when not typing) |
 | `Esc` | Deselect current session |
-| `/` | Focus input and start command |
+| `/` | Start typing a command |
 | `Enter` | Send message |
 | `Shift+Enter` | New line in message |
+| `Tab` | Accept autocomplete suggestion |
+| `↑/↓` | Navigate autocomplete options |
+
+## Permission System
+
+When Claude tries to write files or execute commands, a permission dialog appears:
+
+- **Allow Once** - Permit this specific operation
+- **Allow Always** - Remember permission for similar operations this session
+- **Deny** - Block the operation
+
+Dangerous commands (like `rm -rf`, `sudo`) show enhanced warnings.
+
+## Tool Capabilities
+
+Claude has access to real tools that execute on your system:
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read file contents |
+| `write_file` | Write content to files (requires permission) |
+| `bash` | Execute shell commands (requires permission) |
+| `glob` | Find files matching patterns |
+| `task` | Spawn specialized subagents |
 
 ## Data Storage
 
-Sessions are persisted to `.claude-dojo/sessions/` in the project directory. Panel width preferences are stored in browser localStorage.
+- **Sessions**: Persisted to `.claude-dojo/sessions/` in your working directory
+- **Panel width**: Stored in browser localStorage
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/anthropics/claude-dojo.git
+cd claude-dojo
+
+# Install dependencies
+npm install
+
+# Run in development mode (hot reload)
+npm run dev
+
+# Build for production
+npm run build
+
+# Start production server
+npm start
+```
+
+## Architecture
+
+```
+claude-dojo/
+├── client/          # React frontend with Three.js 3D visualization
+│   ├── src/
+│   │   ├── components/  # UI components (HexGrid, SessionPanel, etc.)
+│   │   ├── hooks/       # Custom React hooks
+│   │   ├── stores/      # Zustand state management
+│   │   └── types/       # TypeScript types
+│   └── dist/        # Production build
+├── server/          # Express backend
+│   ├── src/
+│   │   ├── commands/    # Slash command handlers
+│   │   ├── claudeService.ts  # Claude API integration
+│   │   └── sessionManager.ts # Session persistence
+│   └── dist/        # Compiled server
+└── bin/             # CLI entry point
+```
+
+## Troubleshooting
+
+### Port already in use
+
+```bash
+# Use a different port
+PORT=3002 npx claude-dojo
+```
+
+### Sessions not persisting
+
+Ensure you have write permissions to the `.claude-dojo/` directory in your working directory.
 
 ## License
 
 MIT
+
+## Credits
+
+Built with [Claude Code](https://claude.ai/claude-code) (claude-opus-4-5-20250514)

package/bin/claude-dojo.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const PORT = process.env.PORT || 3001;
+const OPEN_BROWSER = process.env.CLAUDE_DOJO_NO_BROWSER !== '1';
+
+// Find the server entry point
+const serverPath = join(__dirname, '..', 'server', 'dist', 'index.js');
+
+if (!existsSync(serverPath)) {
+  console.error('Error: Server not built. Run "npm run build" first.');
+  console.error(`Expected server at: ${serverPath}`);
+  process.exit(1);
+}
+
+// Check for client build
+const clientPath = join(__dirname, '..', 'client', 'dist', 'index.html');
+if (!existsSync(clientPath)) {
+  console.error('Error: Client not built. Run "npm run build" first.');
+  console.error(`Expected client at: ${clientPath}`);
+  process.exit(1);
+}
+
+console.log(`
+╔═══════════════════════════════════════════════════════════╗
+║                                                           ║
+║   ██████╗██╗      █████╗ ██╗   ██╗██████╗ ███████╗        ║
+║  ██╔════╝██║     ██╔══██╗██║   ██║██╔══██╗██╔════╝        ║
+║  ██║     ██║     ███████║██║   ██║██║  ██║█████╗          ║
+║  ██║     ██║     ██╔══██║██║   ██║██║  ██║██╔══╝          ║
+║  ╚██████╗███████╗██║  ██║╚██████╔╝██████╔╝███████╗        ║
+║   ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝        ║
+║                                                           ║
+║   ██████╗  ██████╗      ██╗ ██████╗                       ║
+║   ██╔══██╗██╔═══██╗     ██║██╔═══██╗                      ║
+║   ██║  ██║██║   ██║     ██║██║   ██║                      ║
+║   ██║  ██║██║   ██║██   ██║██║   ██║                      ║
+║   ██████╔╝╚██████╔╝╚█████╔╝╚██████╔╝                      ║
+║   ╚═════╝  ╚═════╝  ╚════╝  ╚═════╝                       ║
+║                                                           ║
+║   Visual Agent Dashboard for Claude                       ║
+║                                                           ║
+╚═══════════════════════════════════════════════════════════╝
+`);
+
+console.log(`Starting server on http://localhost:${PORT}...`);
+
+// Start the server
+const server = spawn('node', [serverPath], {
+  stdio: 'inherit',
+  env: { ...process.env, PORT: String(PORT) },
+});
+
+server.on('error', (err) => {
+  console.error('Failed to start server:', err.message);
+  process.exit(1);
+});
+
+// Open browser after a short delay to let server start
+if (OPEN_BROWSER) {
+  setTimeout(async () => {
+    try {
+      const open = (await import('open')).default;
+      await open(`http://localhost:${PORT}`);
+      console.log(`\nOpened browser at http://localhost:${PORT}`);
+    } catch (err) {
+      console.log(`\nOpen http://localhost:${PORT} in your browser`);
+    }
+  }, 1500);
+}
+
+// Handle shutdown
+process.on('SIGINT', () => {
+  console.log('\nShutting down...');
+  server.kill('SIGINT');
+  process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+  server.kill('SIGTERM');
+  process.exit(0);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-dojo",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "A visual agent dashboard for Claude - watch AI agents work in a 3D hex-grid interface",
   "type": "module",
   "bin": {

package/server/dist/claudeService.d.ts

@@ -2,6 +2,7 @@ import type { Message, ToolCall, Session, PermissionRequest, PermissionResponse
 type BroadcastCallback = (sessionId: string, session: Session) => void;
 declare class ClaudeService {
     private client;
+    private clientInitPromise;
     private conversationHistory;
     private onSubagentCreated;
     private onSubagentUpdated;
@@ -10,6 +11,7 @@ declare class ClaudeService {
     private grantedPermissions;
     private useBedrock;
     constructor();
+    private getClient;
     private getModel;
     setOnSubagentCreated(callback: BroadcastCallback): void;
     setOnSubagentUpdated(callback: (sessionId: string, updates: Partial<Session>) => void): void;

package/server/dist/claudeService.js

@@ -1,5 +1,4 @@
 import Anthropic from '@anthropic-ai/sdk';
-import AnthropicBedrock from '@anthropic-ai/bedrock-sdk';
 import { sessionManager } from './sessionManager.js';
 import { v4 as uuidv4 } from 'uuid';
 import * as fs from 'fs/promises';
@@ -8,11 +7,25 @@ import { exec } from 'child_process';
 import { promisify } from 'util';
 import { glob } from 'glob';
 const execAsync = promisify(exec);
-// Check if we should use Bedrock
+// Check if we should use Bedrock (only if explicitly set)
 const USE_BEDROCK = process.env.CLAUDE_CODE_USE_BEDROCK === '1' || process.env.CLAUDE_CODE_USE_BEDROCK === 'true';
 // Model mapping for Bedrock
 const BEDROCK_MODEL = process.env.ANTHROPIC_MODEL || 'anthropic.claude-sonnet-4-20250514-v1:0';
 const ANTHROPIC_MODEL = process.env.ANTHROPIC_MODEL || 'claude-sonnet-4-20250514';
+// Dynamic import for Bedrock SDK (only loaded if needed)
+async function createBedrockClient() {
+    try {
+        const { default: AnthropicBedrock } = await import('@anthropic-ai/bedrock-sdk');
+        return new AnthropicBedrock({
+            awsRegion: process.env.AWS_REGION || 'us-east-1',
+        });
+    }
+    catch (error) {
+        console.error('Failed to load @anthropic-ai/bedrock-sdk. Install it with: npm install @anthropic-ai/bedrock-sdk');
+        console.error('Falling back to Anthropic API directly.');
+        return new Anthropic();
+    }
+}
 // Tool definitions for Claude
 const TOOLS = [
     {
@@ -79,7 +92,8 @@ const TOOLS = [
     },
 ];
 class ClaudeService {
-    client;
+    client = null;
+    clientInitPromise = null;
     conversationHistory = new Map();
     onSubagentCreated = null;
     onSubagentUpdated = null;
@@ -91,15 +105,25 @@ class ClaudeService {
         this.useBedrock = USE_BEDROCK;
         if (this.useBedrock) {
             console.log('Using AWS Bedrock for Claude API');
-            this.client = new AnthropicBedrock({
-                awsRegion: process.env.AWS_REGION || 'us-east-1',
-            });
         }
         else {
             console.log('Using Anthropic API directly');
             this.client = new Anthropic();
         }
     }
+    // Lazy initialization of client (needed for async Bedrock import)
+    async getClient() {
+        if (this.client) {
+            return this.client;
+        }
+        if (!this.clientInitPromise) {
+            this.clientInitPromise = createBedrockClient().then(client => {
+                this.client = client;
+                return client;
+            });
+        }
+        return this.clientInitPromise;
+    }
     getModel() {
         return this.useBedrock ? BEDROCK_MODEL : ANTHROPIC_MODEL;
     }
@@ -421,7 +445,8 @@ class ClaudeService {
                 if (abortSignal?.aborted) {
                     throw new Error('Request aborted');
                 }
-                const response = await this.client.messages.create({
+                const client = await this.getClient();
+                const response = await client.messages.create({
                     model: this.getModel(),
                     max_tokens: 4096,
                     system: `You are a helpful coding assistant working in directory: ${session.cwd}. Help the user with their software engineering tasks. Be concise and direct.