claude-frontend-control

┌─────────────┐     WebSocket      ┌─────────────┐    Claude API    ┌─────────┐
│  Frontend   │ ←───────────────→  │   Backend   │ ←──────────────→ │ Claude  │
│  (React/    │                    │  (Node/     │                  │   API   │
│   Vue/etc)  │                    │   Python)   │                  │         │
└─────────────┘                    └─────────────┘                  └─────────┘
      ↑                                   │
      │                                   │
      └───── Tool execution results ──────┘

┌─────────────┐    Claude API     ┌─────────┐
│  Frontend   │ ←───────────────→ │ Claude  │
│             │   (tool_use)      │   API   │
└─────────────┘                   └─────────┘

{
  "name": "navigate",
  "description": "Navigate to a different page or route in the application",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "The route path, e.g., '/dashboard', '/settings/profile'"
      }
    },
    "required": ["path"]
  }
}

{
  "name": "update_ui_state",
  "description": "Update a piece of UI state in the application",
  "input_schema": {
    "type": "object",
    "properties": {
      "key": {
        "type": "string",
        "description": "State key path, e.g., 'sidebar.open', 'theme'"
      },
      "value": {
        "description": "New value for the state"
      }
    },
    "required": ["key", "value"]
  }
}

{
  "name": "show_dialog",
  "description": "Display a dialog or modal to the user",
  "input_schema": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "enum": ["info", "warning", "error", "confirm"],
        "description": "Type of dialog"
      },
      "title": {
        "type": "string",
        "description": "Dialog title"
      },
      "content": {
        "type": "string",
        "description": "Dialog message or content"
      },
      "actions": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "label": { "type": "string" },
            "action": { "type": "string" }
          }
        },
        "description": "Optional action buttons"
      }
    },
    "required": ["type", "title", "content"]
  }
}

{
  "name": "fill_form",
  "description": "Fill in form fields with specified values",
  "input_schema": {
    "type": "object",
    "properties": {
      "form_id": {
        "type": "string",
        "description": "Identifier for the form"
      },
      "fields": {
        "type": "object",
        "description": "Key-value pairs of field names and values"
      }
    },
    "required": ["form_id", "fields"]
  }
}

{
  "name": "highlight_element",
  "description": "Visually highlight an element to draw user attention",
  "input_schema": {
    "type": "object",
    "properties": {
      "selector": {
        "type": "string",
        "description": "CSS selector or element ID"
      },
      "duration_ms": {
        "type": "number",
        "description": "How long to highlight in milliseconds"
      },
      "style": {
        "type": "string",
        "enum": ["pulse", "glow", "outline", "shake"],
        "description": "Highlight animation style"
      }
    },
    "required": ["selector"]
  }
}

// Frontend tool executor
class ToolExecutor {
  private handlers: Map<string, (input: any) => Promise<any>> = new Map();

  register(name: string, handler: (input: any) => Promise<any>) {
    this.handlers.set(name, handler);
  }

  async execute(toolName: string, input: any): Promise<any> {
    const handler = this.handlers.get(toolName);
    if (!handler) {
      throw new Error(`Unknown tool: ${toolName}`);
    }
    return handler(input);
  }
}

// Register handlers
const executor = new ToolExecutor();

executor.register('navigate', async ({ path }) => {
  router.push(path);
  return { success: true, navigated_to: path };
});

executor.register('show_dialog', async ({ type, title, content }) => {
  const result = await dialogService.show({ type, title, content });
  return { success: true, user_action: result };
});

executor.register('update_ui_state', async ({ key, value }) => {
  store.set(key, value);
  return { success: true, updated: key };
});

// Messages from backend to frontend
interface ToolCallMessage {
  type: 'tool_call';
  call_id: string;
  tool_name: string;
  input: any;
}

// Messages from frontend to backend
interface ToolResultMessage {
  type: 'tool_result';
  call_id: string;
  result: any;
  error?: string;
}

executor.register('delete_item', async ({ item_id }) => {
  const confirmed = await confirmDialog(`Delete item ${item_id}?`);
  if (!confirmed) {
    return { success: false, reason: 'User cancelled' };
  }
  await api.deleteItem(item_id);
  return { success: true };
});

const rateLimiter = new RateLimiter({ maxCalls: 10, windowMs: 1000 });

async function executeWithLimit(tool: string, input: any) {
  if (!rateLimiter.allow()) {
    return { error: 'Rate limited', retry_after_ms: rateLimiter.retryAfter() };
  }
  return executor.execute(tool, input);
}