### Install Dependencies with Bun

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/apps/server/README.md

Installs project dependencies using the Bun package manager. Ensure Bun is installed on your system before running this command.

```bash
bun install
```

--------------------------------

### Run Server with Bun

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/apps/server/README.md

Executes the main server file (index.ts) using the Bun runtime. This command starts the server application.

```bash
bun run index.ts
```

--------------------------------

### Bun Server and API Example

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/apps/server/CLAUDE.md

Sets up a basic HTTP server using Bun.serve(), supporting routing, GET requests, and WebSockets. It also demonstrates automatic loading of environment variables and hot module replacement for development.

```typescript
import index from "./index.html"

Bun.serve({
  routes: {
    "/": index,
    "/api/users/:id": {
      GET: (req) => {
        return new Response(JSON.stringify({ id: req.params.id }));
      },
    },
  },
  // optional websocket support
  websocket: {
    open: (ws) => {
      ws.send("Hello, world!");
    },
    message: (ws, message) => {
      ws.send(message);
    },
    close: (ws) => {
      // handle close
    }
  },
  development: {
    hmr: true,
    console: true,
  }
})
```

--------------------------------

### Agent Decision Point HITL Integration Example (Python)

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/app_docs/how_human_in_the_loop_v1_works.md

Demonstrates how to integrate the HITL manager within an agent's decision point. It shows the initialization of the HITL manager, starting the WebSocket server, requesting approval for an environment file access, extracting the response, and acting based on the approval status or timeout.

```python
# In your agent's decision point
hitl_manager = HITLManager()

# Start WebSocket server (do this once at agent startup)
await hitl_manager.start_server(port=0)  # 0 = random port

# Request approval with explicit permission type
response_data = await hitl_manager.request_approval(
    permission_type=DECISION_POINT_ENV_FILE_ACCESS,
    question="May I access .env files in the working directory?",
    session_id="session-123",
    hitl_type="permission"
)

# Extract answer
if response_data:
    approved = hitl_manager.extract_answer(response_data, "permission")
    if approved:
        # Execute operation
        modify_env_file()
    else:
        # Block operation
        return {"error": "Permission denied"}
else:
    # Timeout - use default behavior
    return {"error": "No response - operation blocked"}
```

--------------------------------

### Development Workflow Commands with `just`

Source: https://context7.com/disler/claude-code-hooks-multi-agent-observability/llms.txt

Execute individual component management tasks for development, including installing dependencies, starting server or client in dev mode, type checking the server, and building the client for production.

```bash
# Install all dependencies
just install

# Start server only (dev mode with watch)
just server

# Start client only
just client

# Server typecheck
just server-typecheck

# Build client for production
just client-build
```

--------------------------------

### Start Server with 'just'

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/README.md

This 'just' recipe starts only the server process in development mode. It's useful for focusing on backend development without the client.

```bash
just server
```

--------------------------------

### Run System with Just

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/README.md

This command utilizes the 'just' command runner to execute the 'start' recipe, which is defined in the project's 'justfile'. This recipe is designed to start both the server and client components of the observability system, providing a convenient shortcut.

```bash
just start
```

--------------------------------

### Install Dependencies with 'just'

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/README.md

This 'just' recipe installs all project dependencies. It ensures that both the server and client have the necessary packages.

```bash
just install
```

--------------------------------

### Start Client with 'just'

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/README.md

This 'just' recipe starts only the client process. It's useful for focusing on frontend development or testing client-side interactions.

```bash
just client
```

--------------------------------

### Bun Frontend React Example

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/apps/server/CLAUDE.md

A React component example for a frontend application managed by Bun. It demonstrates importing CSS directly and rendering a React component using createRoot. This code is intended to be imported into an HTML file.

```tsx
import React from "react";

// import .css files directly and it works
import './index.css';

import { createRoot } from "react-dom/client";

const root = createRoot(document.body);

export default function Frontend() {
  return <h1>Hello, world!</h1>;
}

root.render(<Frontend />);
```

--------------------------------

### Start System Script

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/README.md

This shell script initiates the system by launching both the server and client processes. It serves as an alternative to the 'just start' command.

```bash
#!/bin/bash

# Start the server
./apps/server/start.sh &

# Start the client
./apps/client/start.sh &

wait

```

--------------------------------

### Start Observability System

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/README.md

This bash script initiates the multi-agent observability system, typically by starting both the server component (which receives hook events) and the client component (which visualizes the events). It's a quick way to get the entire system running for testing or development.

```bash
./scripts/start-system.sh
```

--------------------------------

### Plugin Manifest Example (plugin.json)

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/ai_docs/haiku45/answers.md

An example of a `plugin.json` file, which serves as the manifest for a Claude Code plugin. It includes essential metadata such as the plugin's name, description, version, and author information. This file is required within the `.claude-plugin` directory.

```json
{
  "name": "my-plugin-name",
  "description": "A brief description of what the plugin does.",
  "version": "1.0.0",
  "author": "Plugin Author Name <author@example.com>"
}
```

--------------------------------

### Start WebSocket Server for HITL Responses (Python)

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/app_docs/how_human_in_the_loop_v1_works.md

Initiates a WebSocket server to listen for responses from an observability server. It handles incoming messages, parses them to identify the permission type, and resolves pending asyncio Futures to unblock waiting code. This is crucial for receiving asynchronous HITL decisions.

```python
import asyncio
import json
from websockets.server import serve

class HITLManager:
    def __init__(self):
        self.pending_futures = {}  # permission_type -> asyncio.Future
        self.server_running = False

    async def start_server(self, port):
        """Start WebSocket server to receive responses"""

        async def handle_response(websocket):
            try:
                # Receive response from observability server
                message = await websocket.recv()
                response_data = json.loads(message)

                # Extract permission_type for matching
                original_event = response_data.get("hookEvent", {})
                payload = original_event.get("payload", {})
                permission_type = payload.get("permission_type", "")

                # Resolve pending future (wake up waiting code)
                if permission_type in self.pending_futures:
                    future = self.pending_futures.pop(permission_type)
                    if not future.done():
                        future.set_result(response_data)

                await websocket.close()

            except Exception as e:
                print(f"Error handling response: {e}")

        self.server_running = True
        async with serve(handle_response, "localhost", port):
            while self.server_running:
                await asyncio.sleep(1)
```

--------------------------------

### README.md Documentation Addition for New Features (Markdown)

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/specs/plan_new_feature_sonnet45.md

Example content to be added to the README.md file, documenting new features in version 1.2.0. It highlights the addition of new themes (Sunset, Cyberpunk, Forest) and the '10-Minute Activity Window' for the Live Pulse Chart.

```markdown
## New Features (v1.2.0)

### Extended Theme Collection
We've added three new beautiful themes to our collection:
- **Sunset**: Warm gradient theme with orange, pink, and purple tones
- **Cyberpunk**: Futuristic neon theme with purple, cyan, and magenta
- **Forest**: Natural theme with deep greens and earthy tones

### 10-Minute Activity Window
You can now view up to 10 minutes of agent activity in the Live Pulse Chart,
perfect for monitoring longer-running agent sessions.

```

--------------------------------

### Bun Test Example

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/apps/server/CLAUDE.md

Demonstrates how to write and run tests using Bun's built-in testing framework. It imports test functions from 'bun:test' and uses 'expect' for assertions.

```typescript
import { test, expect } from "bun:test";

test("hello world", () => {
  expect(1).toBe(1);
});
```

--------------------------------

### GET /api/themes - Search Themes

Source: https://context7.com/disler/claude-code-hooks-multi-agent-observability/llms.txt

Search and filter available themes with pagination and sorting options.

```APIDOC
## GET /api/themes - Search Themes

### Description
Search and filter available themes with pagination and sorting options.

### Method
GET

### Endpoint
`/api/themes`

### Parameters
#### Query Parameters
- **query** (string) - Optional - Search term for theme names or descriptions.
- **isPublic** (boolean) - Optional - Filter for public themes.
- **authorId** (string) - Optional - Filter themes by author ID.
- **sortBy** (string) - Optional - Field to sort themes by (e.g., 'downloads', 'rating', 'createdAt').
- **limit** (integer) - Optional - Maximum number of themes to return.
- **offset** (integer) - Optional - Number of themes to skip for pagination.

### Request Example
```bash
# Search public themes
curl "http://localhost:4000/api/themes?query=dark&isPublic=true&sortBy=downloads&limit=10"

# Get themes by author
curl "http://localhost:4000/api/themes?authorId=user-123"
```

### Response
#### Success Response (200 OK)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (array) - An array of theme objects matching the search criteria.
  - **id** (string) - The unique ID of the theme.
  - **name** (string) - The name of the theme.
  - **displayName** (string) - The display name of the theme.
  - **downloadCount** (integer) - Number of times the theme has been downloaded.
  - **rating** (float) - Average rating of the theme.
  - ... (other theme properties)

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "id": "theme-001",
      "name": "dark-mode",
      "displayName": "Dark Mode",
      "downloadCount": 150,
      "rating": 4.5
    }
  ]
}
```
```

--------------------------------

### Bun HTML Import Example

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/apps/server/CLAUDE.md

Illustrates how Bun handles HTML imports, allowing direct inclusion of HTML files in TypeScript. It shows how to link to JavaScript and CSS files, with Bun automatically transpiling and bundling them.

```html
<html>
  <body>
    <h1>Hello, world!</h1>
    <script type="module" src="./frontend.tsx"></script>
  </body>
</html>
```

--------------------------------

### Permission Type Matching

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/app_docs/how_human_in_the_loop_v1_works.md

Guidance on using explicit permission type constants for matching within the system, rather than relying on hashes.

```APIDOC
## Permission Type Matching

### Description
Specifies the use of explicit permission type constants for matching, ensuring clarity and avoiding potential issues with hash-based comparisons.

### Method
N/A (Code Convention)

### Endpoint
N/A

### Constants
- `DECISION_POINT_ENV_FILE_ACCESS`
- `DECISION_POINT_DELETE_FILES`
- `DECISION_POINT_INSTALL_PACKAGES`
- `DECISION_POINT_DEPLOY_PRODUCTION`
- `DECISION_POINT_DATABASE_MODIFY`

### Usage Example (Python)
```python
# Define permission type constants
DECISION_POINT_ENV_FILE_ACCESS = "env_file_access"
DECISION_POINT_DELETE_FILES = "delete_files"
DECISION_POINT_INSTALL_PACKAGES = "install_packages"
DECISION_POINT_DEPLOY_PRODUCTION = "deploy_production"
DECISION_POINT_DATABASE_MODIFY = "database_modify"

# Use in requests
permission_type = DECISION_POINT_ENV_FILE_ACCESS

# Match responses using permission_type from hookEvent.payload
payload = response_data.get("hookEvent", {}).get("payload", {})
permission_type = payload.get("permission_type", "")
```
```

--------------------------------

### Manage Observability System with `just`

Source: https://context7.com/disler/claude-code-hooks-multi-agent-observability/llms.txt

Quickly start, stop, restart, and check the health of the observability system using the `just` command runner. It also provides a command to open the dashboard in a web browser.

```bash
# List all available recipes
just

# Start server + client (foreground, Ctrl+C to stop)
just start

# Stop all processes and clean up
just stop

# Restart (stop then start)
just restart

# Check server/client health
just health
# Output:
# Server: UP (port 4000)
# Client: UP (port 5173)

# Open dashboard in browser
just open
```

--------------------------------

### Restart System with 'just'

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/README.md

This 'just' recipe performs a restart of the system by first stopping all processes and then starting them again. It's useful for applying configuration changes or recovering from issues.

```bash
just restart
```

--------------------------------

### Error Handling Strategies

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/app_docs/how_human_in_the_loop_v1_works.md

Defines the recommended strategies for handling network failures, timeouts, and malformed responses to ensure agent stability.

```APIDOC
## Error Handling

### Description
Strategies for managing network failures, timeouts, and malformed responses to maintain agent stability and prevent crashes.

### Method
N/A (Error Handling Strategy)

### Endpoint
N/A

### Strategies
#### Network Failure
- Auto-approve on send failure.
- Log the error but do not block the agent.

#### Timeout
- Clear pending future after timeout.
- Return `None` or default behavior.
- Do not crash the agent.

#### Malformed Response
- Validate JSON structure.
- Log a warning.
- Treat the response as a timeout.
```

--------------------------------

### Observability Server API

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/app_docs/how_human_in_the_loop_v1_works.md

The Observability Server provides an HTTP API for sending events and is fixed to a local port.

```APIDOC
## POST /events

### Description
Sends observability events to the server.

### Method
POST

### Endpoint
http://localhost:4000/events

### Parameters
#### Query Parameters
None

#### Request Body
(Structure not defined in provided text, assumed to contain event data)

### Request Example
(Not provided in source text)

### Response
#### Success Response (200)
(Details not provided in source text)

#### Response Example
(Not provided in source text)
```

--------------------------------

### Agent WebSocket Server Configuration

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/app_docs/how_human_in_the_loop_v1_works.md

Details on configuring the Agent's WebSocket server, which uses a dynamic, OS-assigned port to avoid conflicts.

```APIDOC
## Agent WebSocket Server

### Description
Configuration for the Agent's WebSocket server, which dynamically selects an available port.

### Method
N/A (Configuration)

### Endpoint
`ws://localhost:<port>` (where `<port>` is dynamically assigned)

### Notes
- Uses a random port assigned by the OS to prevent conflicts.
- Binds to `localhost` only for security.
- No authentication is required as it operates within a local trust model.

### Example Usage (Python)
```python
import socket

def find_free_port() -> int:
    """Find an available port for agent's WebSocket server"""
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
        s.bind(('', 0))  # 0 = let OS choose port
        s.listen(1)
        port = s.getsockname()[1]
    return port

# Example: port = 50123 (random)
# responseWebSocketUrl = f"ws://localhost:{port}"
```
```

--------------------------------

### Search Themes API Endpoint (Bash)

Source: https://context7.com/disler/claude-code-hooks-multi-agent-observability/llms.txt

Illustrates how to search and filter dashboard themes using GET requests to the /api/themes endpoint. Supports query parameters for searching by name, public status, author, and sorting by downloads.

```bash
# Search public themes
curl "http://localhost:4000/api/themes?query=dark&isPublic=true&sortBy=downloads&limit=10"

# Get themes by author
curl "http://localhost:4000/api/themes?authorId=user-123"
```

--------------------------------

### Plan with Team Command (Bash)

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/README.md

Example of using the '/plan_w_team' slash command to initiate the creation of a team-based implementation plan. This command generates a spec document for task breakdown and assignment.

```bash
/plan_w_team "Add a new feature for X"
```

--------------------------------

### Existing Project Hook Configuration (JSON)

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/README.md

Demonstrates the hook configuration for an already integrated project, showing commands for both validation and event sending. This setup ensures that hooks run for validation and observability.

```json
{
  "type": "command",
  "command": "uv run .claude/hooks/pre_tool_use.py"
},
{
  "type": "command",
  "command": "uv run .claude/hooks/send_event.py --source-app cc-hook-multi-agent-obvs --event-type PreToolUse"
}
```

--------------------------------

### Python HITL Event Payload Construction

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/app_docs/how_human_in_the_loop_v1_works.md

Demonstrates how to construct the payload for a Human-in-the-Loop (HITL) event request in Python. This example shows the structure required for sending event data, including custom payload and HITL-specific details, to the observability server.

```python
event_payload = {
    "source_app": f"big-three-agents: {agent_name}",
    "session_id": session_id,
    "hook_event_type": "DecisionPoint",
    "payload": {
        "agent_name": agent_name,
        "permission_type": permission_type,  # e.g., "env_file_access"
        "question": question
    },
    "humanInTheLoop": hitl_data.model_dump(by_alias=True),  # ✅ Valid
    "timestamp": int(time.time() * 1000),
    "summary": f"🔐 {permission_type}: {question[:100]}",
}
```

--------------------------------

### JSON HITL Event Request Structure

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/app_docs/how_human_in_the_loop_v1_works.md

Provides an example of the JSON structure for a Human-in-the-Loop (HITL) event request sent to the observability server. This format includes details about the source application, session, event type, custom payload, and HITL-specific parameters like the question and response WebSocket URL.

```json
{
  "source_app": "big-three-agents: alice",
  "session_id": "session-123",
  "hook_event_type": "DecisionPoint",
  "payload": {
    "agent_name": "alice",
    "permission_type": "env_file_access",
    "question": "May I access .env files in the working directory?"
  },
  "humanInTheLoop": {
    "question": "May I access .env files in the working directory?",
    "responseWebSocketUrl": "ws://localhost:50123",
    "type": "permission",
    "choices": null,
    "timeout": 300,
    "requiresResponse": true
  },
  "timestamp": 1734189234000,
  "summary": "🔐 env_file_access: May I access .env files..."
}
```

--------------------------------

### Subagent Start Hook Script

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/README.md

This Python script tracks the lifecycle start of a subagent. It's essential for monitoring and managing subagent processes.

```python
from claude.hooks.subagent_start import subagent_start

def main(subagent_id, agent_type):
    # Example: Log subagent start
    print(f"Subagent '{subagent_id}' ({agent_type}) started.")
    
    return {"status": "logged", "message": "Subagent start logged"}

if __name__ == '__main__':
    # Placeholder for actual arguments
    subagent_id = "data_analyzer_v2"
    agent_type = "analysis"
    result = main(subagent_id, agent_type)
    print(result)
```

--------------------------------

### POST /api/themes/import - Import Theme

Source: https://context7.com/disler/claude-code-hooks-multi-agent-observability/llms.txt

Import a previously exported theme file.

```APIDOC
## POST /api/themes/import - Import Theme

### Description
Import a previously exported theme file.

### Method
POST

### Endpoint
`/api/themes/import`

### Parameters
#### Query Parameters
- **authorId** (string) - Required - The ID of the author importing the theme.

#### Request Body
- **version** (string) - Required - The version of the import format.
- **theme** (object) - Required - The theme object to import.
  - **name** (string) - Required - The name of the theme.
  - **displayName** (string) - Required - The display name of the theme.
  - **colors** (object) - Required - The color configuration of the theme.

### Request Example
```bash
curl -X POST "http://localhost:4000/api/themes/import?authorId=user-456" \
  -H "Content-Type: application/json" \
  -d '{ 
    "version": "1.0.0",
    "theme": {
      "name": "imported-theme",
      "displayName": "Imported Theme",
      "colors": {
        "primary": "#6200EE",
        "primaryHover": "#3700B3",
        "primaryLight": "#BB86FC",
        "primaryDark": "#3700B3",
        "bgPrimary": "#FFFFFF",
        "bgSecondary": "#F5F5F5",
        "bgTertiary": "#E0E0E0",
        "bgQuaternary": "#BDBDBD",
        "textPrimary": "#212121",
        "textSecondary": "#424242",
        "textTertiary": "#616161",
        "textQuaternary": "#757575",
        "borderPrimary": "#BDBDBD",
        "borderSecondary": "#E0E0E0",
        "borderTertiary": "#F5F5F5",
        "accentSuccess": "#4CAF50",
        "accentWarning": "#FFC107",
        "accentError": "#F44336",
        "accentInfo": "#2196F3",
        "shadow": "rgba(0, 0, 0, 0.1)",
        "shadowLg": "rgba(0, 0, 0, 0.2)",
        "hoverBg": "rgba(98, 0, 238, 0.05)",
        "activeBg": "rgba(98, 0, 238, 0.1)",
        "focusRing": "rgba(98, 0, 238, 0.5)"
      }
    }
  }'
```

### Response
#### Success Response (200 OK)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - The imported theme object.
  - **id** (string) - The unique ID of the imported theme.
  - **message** (string) - A confirmation message.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "imported-theme-id-789"
  },
  "message": "Theme imported successfully"
}
```
```

--------------------------------

### List 'just' Recipes

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/README.md

The 'justfile' provides convenient recipes for common development operations. This command lists all available recipes.

```bash
just
```

--------------------------------

### GET /events/filter-options - Get Filter Options

Source: https://context7.com/disler/claude-code-hooks-multi-agent-observability/llms.txt

Returns available filter values for the dashboard including source apps, session IDs, and hook event types.

```APIDOC
## GET /events/filter-options - Get Filter Options

### Description
Returns available filter values for the dashboard including source apps, session IDs, and hook event types.

### Method
GET

### Endpoint
/events/filter-options

### Response
#### Success Response (200)
- **source_apps** (array of strings) - A list of available source application names.
- **session_ids** (array of strings) - A list of available session identifiers.
- **hook_event_types** (array of strings) - A list of available hook event types.

#### Response Example
```json
{
  "source_apps": ["my-project", "api-server", "frontend-app"],
  "session_ids": ["abc123-def456", "xyz789-ghi012", "..."],
  "hook_event_types": ["PreToolUse", "PostToolUse", "Stop", "Notification", "SubagentStart"]
}
```
```

--------------------------------

### Import Theme API Endpoint (Bash)

Source: https://context7.com/disler/claude-code-hooks-multi-agent-observability/llms.txt

Demonstrates importing a theme using a POST request to the /api/themes/import endpoint. Requires a JSON payload containing the theme version and its configuration, along with an authorId query parameter.

```bash
curl -X POST "http://localhost:4000/api/themes/import?authorId=user-456" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0.0",
    "theme": {
      "name": "imported-theme",
      "displayName": "Imported Theme",
      "colors": {...}
    }
  }'
```

--------------------------------

### POST /api/themes - Create Theme

Source: https://context7.com/disler/claude-code-hooks-multi-agent-observability/llms.txt

Creates a new custom theme for the dashboard with full color configuration.

```APIDOC
## POST /api/themes - Create Theme

### Description
Creates a new custom theme for the dashboard with full color configuration.

### Method
POST

### Endpoint
`/api/themes`

### Parameters
#### Request Body
- **name** (string) - Required - Unique identifier for the theme.
- **displayName** (string) - Required - User-friendly name for the theme.
- **description** (string) - Optional - A brief description of the theme.
- **isPublic** (boolean) - Optional - Whether the theme is publicly available.
- **authorId** (string) - Required - The ID of the author.
- **authorName** (string) - Required - The name of the author.
- **tags** (array of strings) - Optional - Tags associated with the theme.
- **colors** (object) - Required - An object containing all color configurations.
  - **primary** (string) - Required - Primary color hex code.
  - **primaryHover** (string) - Required - Primary hover color hex code.
  - **primaryLight** (string) - Required - Primary light color hex code.
  - **primaryDark** (string) - Required - Primary dark color hex code.
  - **bgPrimary** (string) - Required - Primary background color hex code.
  - **bgSecondary** (string) - Required - Secondary background color hex code.
  - **bgTertiary** (string) - Required - Tertiary background color hex code.
  - **bgQuaternary** (string) - Required - Quaternary background color hex code.
  - **textPrimary** (string) - Required - Primary text color hex code.
  - **textSecondary** (string) - Required - Secondary text color hex code.
  - **textTertiary** (string) - Required - Tertiary text color hex code.
  - **textQuaternary** (string) - Required - Quaternary text color hex code.
  - **borderPrimary** (string) - Required - Primary border color hex code.
  - **borderSecondary** (string) - Required - Secondary border color hex code.
  - **borderTertiary** (string) - Required - Tertiary border color hex code.
  - **accentSuccess** (string) - Required - Success accent color hex code.
  - **accentWarning** (string) - Required - Warning accent color hex code.
  - **accentError** (string) - Required - Error accent color hex code.
  - **accentInfo** (string) - Required - Info accent color hex code.
  - **shadow** (string) - Required - Shadow color rgba string.
  - **shadowLg** (string) - Required - Large shadow color rgba string.
  - **hoverBg** (string) - Required - Hover background color rgba string.
  - **activeBg** (string) - Required - Active background color rgba string.
  - **focusRing** (string) - Required - Focus ring color rgba string.

### Request Example
```json
{
  "name": "ocean-blue",
  "displayName": "Ocean Blue",
  "description": "A calm blue theme inspired by the ocean",
  "isPublic": true,
  "authorId": "user-123",
  "authorName": "John Doe",
  "tags": ["blue", "calm", "professional"],
  "colors": {
    "primary": "#0077B6",
    "primaryHover": "#0096C7",
    "primaryLight": "#48CAE4",
    "primaryDark": "#023E8A",
    "bgPrimary": "#CAF0F8",
    "bgSecondary": "#ADE8F4",
    "bgTertiary": "#90E0EF",
    "bgQuaternary": "#48CAE4",
    "textPrimary": "#03045E",
    "textSecondary": "#023E8A",
    "textTertiary": "#0077B6",
    "textQuaternary": "#0096C7",
    "borderPrimary": "#0077B6",
    "borderSecondary": "#00B4D8",
    "borderTertiary": "#48CAE4",
    "accentSuccess": "#06D6A0",
    "accentWarning": "#FFD166",
    "accentError": "#EF476F",
    "accentInfo": "#118AB2",
    "shadow": "rgba(0, 119, 182, 0.1)",
    "shadowLg": "rgba(0, 119, 182, 0.2)",
    "hoverBg": "rgba(0, 119, 182, 0.1)",
    "activeBg": "rgba(0, 119, 182, 0.2)",
    "focusRing": "rgba(0, 119, 182, 0.5)"
  }
}
```

### Response
#### Success Response (200 OK)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - The created theme object.
  - **id** (string) - The unique ID of the created theme.
  - **name** (string) - The name of the theme.
  - **displayName** (string) - The display name of the theme.
  - **createdAt** (integer) - Timestamp of creation.
  - **updatedAt** (integer) - Timestamp of last update.
  - ... (other theme properties)
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "abc123xyz",
    "name": "ocean-blue",
    "displayName": "Ocean Blue",
    "createdAt": 1699000000000,
    "updatedAt": 1699000000000
  },
  "message": "Theme created successfully"
}
```
```

--------------------------------

### Get Hook Event Filter Options via HTTP GET (Bash)

Source: https://context7.com/disler/claude-code-hooks-multi-agent-observability/llms.txt

This endpoint provides available filter options for the dashboard, including source applications, session IDs, and hook event types. This data is useful for populating dropdowns or filters in the UI.

```bash
curl http://localhost:4000/events/filter-options
```

--------------------------------

### Create Theme API Endpoint (Bash)

Source: https://context7.com/disler/claude-code-hooks-multi-agent-observability/llms.txt

Demonstrates how to create a new custom dashboard theme using a POST request to the /api/themes endpoint. Requires JSON payload with theme details and color configuration.

```bash
curl -X POST http://localhost:4000/api/themes \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ocean-blue",
    "displayName": "Ocean Blue",
    "description": "A calm blue theme inspired by the ocean",
    "isPublic": true,
    "authorId": "user-123",
    "authorName": "John Doe",
    "tags": ["blue", "calm", "professional"],
    "colors": {
      "primary": "#0077B6",
      "primaryHover": "#0096C7",
      "primaryLight": "#48CAE4",
      "primaryDark": "#023E8A",
      "bgPrimary": "#CAF0F8",
      "bgSecondary": "#ADE8F4",
      "bgTertiary": "#90E0EF",
      "bgQuaternary": "#48CAE4",
      "textPrimary": "#03045E",
      "textSecondary": "#023E8A",
      "textTertiary": "#0077B6",
      "textQuaternary": "#0096C7",
      "borderPrimary": "#0077B6",
      "borderSecondary": "#00B4D8",
      "borderTertiary": "#48CAE4",
      "accentSuccess": "#06D6A0",
      "accentWarning": "#FFD166",
      "accentError": "#EF476F",
      "accentInfo": "#118AB2",
      "shadow": "rgba(0, 119, 182, 0.1)",
      "shadowLg": "rgba(0, 119, 182, 0.2)",
      "hoverBg": "rgba(0, 119, 182, 0.1)",
      "activeBg": "rgba(0, 119, 182, 0.2)",
      "focusRing": "rgba(0, 119, 182, 0.5)"
    }
  }'
```

--------------------------------

### GET /api/themes/:id/export - Export Theme

Source: https://context7.com/disler/claude-code-hooks-multi-agent-observability/llms.txt

Exports a theme as a portable JSON file that can be shared and imported.

```APIDOC
## GET /api/themes/:id/export - Export Theme

### Description
Exports a theme as a portable JSON file that can be shared and imported.

### Method
GET

### Endpoint
`/api/themes/:id/export`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the theme to export.

### Request Example
```bash
curl http://localhost:4000/api/themes/abc123xyz/export
```

### Response
#### Success Response (200 OK)
- **version** (string) - The version of the export format.
- **theme** (object) - The theme object containing its configuration.
  - **name** (string) - The name of the theme.
  - **displayName** (string) - The display name of the theme.
  - **colors** (object) - The color configuration of the theme.
- **exportedAt** (string) - Timestamp when the theme was exported.
- **exportedBy** (string) - Identifier of the system or user that exported the theme.

#### Response Example
```json
{
  "version": "1.0.0",
  "theme": {
    "name": "ocean-blue",
    "displayName": "Ocean Blue",
    "colors": {
      "primary": "#0077B6",
      "primaryHover": "#0096C7",
      "primaryLight": "#48CAE4",
      "primaryDark": "#023E8A",
      "bgPrimary": "#CAF0F8",
      "bgSecondary": "#ADE8F4",
      "bgTertiary": "#90E0EF",
      "bgQuaternary": "#48CAE4",
      "textPrimary": "#03045E",
      "textSecondary": "#023E8A",
      "textTertiary": "#0077B6",
      "textQuaternary": "#0096C7",
      "borderPrimary": "#0077B6",
      "borderSecondary": "#00B4D8",
      "borderTertiary": "#48CAE4",
      "accentSuccess": "#06D6A0",
      "accentWarning": "#FFD166",
      "accentError": "#EF476F",
      "accentInfo": "#118AB2",
      "shadow": "rgba(0, 119, 182, 0.1)",
      "shadowLg": "rgba(0, 119, 182, 0.2)",
      "hoverBg": "rgba(0, 119, 182, 0.1)",
      "activeBg": "rgba(0, 119, 182, 0.2)",
      "focusRing": "rgba(0, 119, 182, 0.5)"
    }
  },
  "exportedAt": "2024-01-15T10:30:00.000Z",
  "exportedBy": "observability-system"
}
```
```

--------------------------------

### Open Dashboard with 'just'

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/README.md

This 'just' recipe opens the project's dashboard in the default web browser. It provides a convenient way to access the user interface.

```bash
just open
```

--------------------------------

### Field Name Convention

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/app_docs/how_human_in_the_loop_v1_works.md

Guidelines for using camelCase in API requests and responses, while using snake_case internally within the application.

```APIDOC
## Field Name Convention

### Description
Specifies the convention for field names: `camelCase` for API (JSON) and `snake_case` for internal use.

### Method
N/A (Code Convention)

### Endpoint
N/A

### Convention
- **API (JSON)**: `camelCase` (e.g., `responseWebSocketUrl`)
- **Internal**: `snake_case` (e.g., `response_websocket_url`)

### Example Usage (Python Pydantic)
```python
from pydantic import BaseModel, Field

class HumanInTheLoop(BaseModel):
    response_websocket_url: str = Field(..., alias="responseWebSocketUrl")
    requires_response: bool = Field(default=True, alias="requiresResponse")

    class Config:
        populate_by_name = True  # Allow both naming styles

# Serialization
hitl_data.model_dump(by_alias=True)  # Uses camelCase for API
```
```

--------------------------------

### List Hook Scripts with 'just'

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/README.md

This 'just' recipe lists all available hook scripts within the project. It helps in understanding the available automation and integration points.

```bash
just hooks
```

--------------------------------

### GET /events/recent - Retrieve Recent Events

Source: https://context7.com/disler/claude-code-hooks-multi-agent-observability/llms.txt

Fetches the most recent events from the database with optional limit parameter. Events are returned in chronological order.

```APIDOC
## GET /events/recent - Retrieve Recent Events

### Description
Fetches the most recent events from the database with optional limit parameter. Events are returned in chronological order.

### Method
GET

### Endpoint
/events/recent

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of events to retrieve. Defaults to 300.

### Response
#### Success Response (200)
- An array of event objects, each containing:
  - **id** (integer) - The unique identifier of the event.
  - **source_app** (string) - The application that generated the event.
  - **session_id** (string) - The unique identifier for the session.
  - **hook_event_type** (string) - The type of hook event.
  - **payload** (object) - The event-specific data.
  - **summary** (string) - Optional - A summary of the event.
  - **timestamp** (integer) - The Unix timestamp of the event.

#### Response Example
```json
[
  {
    "id": 1,
    "source_app": "my-project",
    "session_id": "abc123",
    "hook_event_type": "SessionStart",
    "payload": {"source": "vscode", "model": "claude-sonnet-4-20250514"},
    "timestamp": 1699000000000
  },
  {
    "id": 2,
    "source_app": "my-project",
    "session_id": "abc123",
    "hook_event_type": "PreToolUse",
    "payload": {"tool_name": "Read", "tool_input": {"file_path": "/src/main.ts"}},
    "summary": "Reading TypeScript source file",
    "timestamp": 1699000001000
  }
]
```
```

--------------------------------

### Test Observability System with `just`

Source: https://context7.com/disler/claude-code-hooks-multi-agent-observability/llms.txt

Run tests and debug the observability system. This includes sending a test event, directly testing specific hook scripts, and listing all available hook scripts.

```bash
# Send a test event to the server
just test-event

# Test a specific hook script directly
just hook-test pre_tool_use
just hook-test notification
just hook-test stop

# List all available hook scripts
just hooks
```

--------------------------------

### Agent WebSocket Response Handling

Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/blob/main/app_docs/how_human_in_the_loop_v1_works.md

Details on the structure of the response received by the agent via WebSocket after a human has responded to a HITL request.

```APIDOC
## Agent WebSocket Response Handling

### Description
Agents receive responses to their Human-in-the-Loop requests via a WebSocket connection established using the `responseWebSocketUrl` provided in the initial request. The structure of the received JSON message depends on the `type` of the HITL request.

### Method
WebSocket

### Endpoint
(Provided in `humanInTheLoop.responseWebSocketUrl` during POST /events)

### Parameters
(None - Data is pushed to the agent via WebSocket)

### Response Example
```json
{
  "permission": true,
  "response": "Use async/await approach",
  "choice": "Option B",
  "respondedAt": 1734189245000,
  "hookEvent": {
    "id": 9675,
    "source_app": "big-three-agents: alice",
    "session_id": "session-123",
    "payload": {
      "agent_name": "alice",
      "permission_type": "env_file_access",
      "question": "May I access .env files..."
    },
    "humanInTheLoop": {
      "question": "May I access .env files...",
      "responseWebSocketUrl": "ws://localhost:50123",
      "type": "permission"
    }
  }
}
```

### Response Fields by Type

**For `type: "permission"` requests:**
- **permission** (boolean) - `true` if approved, `false` if denied.

**For `type: "question"` requests:**
- **response** (string) - The text answer provided by the human.

**For `type: "choice"` requests:**
- **choice** (string) - The option selected by the human from the provided choices.

**All response types include:**
- **respondedAt** (number) - Unix timestamp (milliseconds) when the response was given.
- **hookEvent** (object) - The original `HookEvent` object that was sent to the server, echoed back.
```