### Start the daemon

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Commands to install dependencies and launch the daemon with or without BLE support.

```bash
uv sync --extra ble
uv run vk-daemon serve
```

```bash
uv sync
uv run vk-daemon serve --no-ble
```

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

### SetupActionResult Message

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Returns the result of a setup action request.

```text
tag:u8 = 0x8D
request_id:u32
success:bool
```

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

### Install AI tool integrations

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Commands to set up AI tool integrations and verify their installation status.

```bash
uv run vk-daemon setup install claude-code
uv run vk-daemon setup install codex
uv run vk-daemon setup status
```

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

### Launch esptool

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/firmware/README.md

Execute this command to verify the installation and launch the esptool interface.

```bash
python3 -m esptool
```

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

### SetupStatusUpdate Message

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Returns the installation and detection state for AI tools.

```text
tag:u8 = 0x91
request_id:u32
count:u8
tools:SetupToolStatus[count]
```

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

### Install esptool via pip

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/firmware/README.md

Use these commands to upgrade pip and install the esptool utility for firmware management.

```bash
python3 -m pip install --upgrade pip
python3 -m pip install esptool
```

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

### Check setup status

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Verify the current configuration and permission status of the daemon.

```bash
uv run vk-daemon setup status
```

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

### SetupActionRequest Message Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Defines the structure for requesting a setup action, including supported daemon commands.

```text
tag:u8 = 0x08
request_id:u32
action_id:u8
tool:string
command:string
daemon_port:u16
```

```text
install_hook
uninstall_hook
install_tool
uninstall_tool
```

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

### Verify Daemon Configuration

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/migration.md

Use these commands to inspect the current daemon configuration and setup status.

```bash
uv run vk-daemon config show
uv run vk-daemon setup status
```

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

### SetupStatusRequest Message Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Defines the structure for requesting the daemon's current setup status.

```text
tag:u8 = 0x09
request_id:u32
daemon_port:u16
```

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

### Run Verification Commands

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/migration.md

Execute these commands from the project root to verify the environment, run tests, and start the daemon.

```bash
uv sync --extra dev --extra ble
uv run pytest
uv run ruff check .
uv run mypy src
python -m compileall src tests
uv run vk-daemon serve
```

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

### Development and Execution Commands

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/AGENTS.md

Use these commands to manage dependencies, run tests, perform static analysis, and start the daemon.

```bash
uv sync --extra dev --extra ble
uv run pytest
uv run ruff check .
uv run mypy src
uv run vk-daemon serve
```

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

### GET /device/state

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Retrieves an authoritative snapshot of the current device state.

```APIDOC
## GET /device/state

### Description
Read one authoritative snapshot of the device state.

### Method
GET

### Endpoint
/device/state
```

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

### GET /sessions

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Retrieves the list of active sessions.

```APIDOC
## GET /sessions

### Description
Read sessions only.

### Method
GET

### Endpoint
/sessions
```

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

### GET /notifications

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

Retrieves a list of pending notifications.

```APIDOC
## GET /notifications

### Description
Returns a JSON array of Notification objects. Unread notifications are ordered first by daemon priority, followed by read history.

### Method
GET

### Endpoint
/notifications

### Response
#### Success Response (200)
- **notifications** (array) - A list of notification objects.
```

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

### GET /notifications

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Retrieves the notification history.

```APIDOC
## GET /notifications

### Description
Read notification history.

### Method
GET

### Endpoint
/notifications
```

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

### POST /permissions/{id} Request

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

Example HTTP request to resolve a pending permission for a specific session ID.

```http
POST /permissions/17 HTTP/1.1
Host: 127.0.0.1:19280
Content-Type: application/json

{"action":"allow"}
```

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

### GET /device/state

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

Retrieves an atomic snapshot of the current device state, including BLE connection status, active sessions, and YOLO configuration.

```APIDOC
## GET /device/state

### Description
Returns an atomic snapshot of the daemon state. Use this endpoint for initial state and regular polling.

### Method
GET

### Endpoint
/device/state

### Response
#### Success Response (200)
- **active_session_id** (integer or null) - Daemon-selected session
- **ble_connected** (boolean) - Whether the daemon currently has a connected BLE peripheral
- **sessions** (Session array) - Same DTOs returned by GET /sessions
- **notifications** (Notification array) - Same DTOs returned by GET /notifications
- **pending_permissions** (Pending Permission array) - Unresolved permission requests
- **held_keys** (string array) - Sorted daemon-injected keys that are currently held
- **yolo** (YOLO Configuration) - Current effective automatic-decision configuration

#### Response Example
{
  "active_session_id": 17,
  "ble_connected": true,
  "sessions": [],
  "notifications": [],
  "pending_permissions": [],
  "held_keys": [],
  "yolo": {
    "active": false,
    "allow": ["Read(*)", "Glob(*)", "Grep(*)"],
    "deny": ["Bash(git push*)", "Bash(rm -rf*)", "Bash(sudo*)"],
    "notify_auto_allow": true,
    "auto_allow_log": true
  }
}
```

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

### GET /notifications

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

Retrieves unread and historical notifications.

```APIDOC
## GET /notifications

### Description
Read unread and historical notifications.

### Method
GET

### Endpoint
/notifications
```

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

### GET /device/state Response Format

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

The response is a JSON object representing the current state of the daemon, including active sessions, connectivity status, and security configurations.

```json
{
  "active_session_id": 17,
  "ble_connected": true,
  "sessions": [],
  "notifications": [],
  "pending_permissions": [],
  "held_keys": [],
  "yolo": {
    "active": false,
    "allow": ["Read(*)", "Glob(*)", "Grep(*)"],
    "deny": ["Bash(git push*)", "Bash(rm -rf*)", "Bash(sudo*)"],
    "notify_auto_allow": true,
    "auto_allow_log": true
  }
}
```

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

### Stable HTTP API Surface

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/migration.md

The official endpoints for interacting with the vk-daemon. Avoid using internal, diagnostic, or setup routes for client integration.

```text
GET  /device/state
GET  /sessions
GET  /notifications
POST /button
POST /knob
POST /permissions/{id}
```

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

### JSON Error Response Example

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

The standard format for error messages returned by the API. Clients should use the HTTP status code for logic branching rather than parsing the error string.

```json
{"error":"invalid permission action"}
```

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

### Initialize codec device and perform audio operations

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/src/bsp_codec/README.md

Creates the codec device handle and demonstrates basic playback and recording workflows.

```c
esp_codec_dev_cfg_t dev_cfg = {
	.codec_if = out_codec_if;              // codec interface from es8311_codec_new
	.data_if = data_if;                    // data interface from audio_codec_new_i2s_data
	.dev_type = ESP_CODEC_DEV_TYPE_IN_OUT; // codec support both playback and record
};
esp_codec_dev_handle_t codec_dev = esp_codec_dev_new(&dev_cfg);
// Below code shows how to play
esp_codec_dev_set_out_vol(codec_dev, 60.0);
esp_codec_dev_sample_info_t fs = {
	.sample_rate = 48000,
	.channel = 2,
	.bits_per_sample = 16,
};
esp_codec_dev_open(codec_dev, &fs);
uint8_t data[256];
esp_codec_dev_write(codec_dev, data, sizeof(data));

// Below code shows how to record
esp_codec_dev_set_in_gain(codec_dev, 30.0);
esp_codec_dev_read(codec_dev, data, sizeof(data));
esp_codec_dev_close(codec_dev);
```

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

### Define SetupToolStatus Record

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Structure definition for tool status and list of supported tool identifiers.

```text
id:string
name:string
detected:bool
hook_installed:bool
detail:string
```

```text
claude-code
codex
cursor
```

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

### vk-daemon CLI command reference

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Full list of available commands and arguments for the vk-daemon utility.

```text
vk-daemon [--config PATH] serve [--host HOST] [--port PORT] [--no-ble]
                          [--ble-scan-timeout SECONDS]
vk-daemon [--daemon-port PORT] session list
vk-daemon [--daemon-port PORT] session status ID
vk-daemon [--daemon-port PORT] focus ID
vk-daemon config show | set KEY VALUE | reset
vk-daemon setup status
vk-daemon setup install|uninstall claude-code|codex [--port PORT]
vk-daemon [--daemon-port PORT] notify test
```

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

### Create codec control and data interfaces

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/src/bsp_codec/README.md

Sets up the I2S data interface, I2C control interface, and GPIO interface for the codec.

```c
audio_codec_i2s_cfg_t i2s_cfg = {
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 0, 0)
    .rx_handle = i2s_keep[0]->rx_handle,
    .tx_handle = i2s_keep[0]->tx_handle,
#endif
};
const audio_codec_data_if_t *data_if = audio_codec_new_i2s_data(&i2s_cfg);

audio_codec_i2c_cfg_t i2c_cfg = {.addr = ES8311_CODEC_DEFAULT_ADDR};
const audio_codec_ctrl_if_t *out_ctrl_if = audio_codec_new_i2c_ctrl(&i2c_cfg);

const audio_codec_gpio_if_t *gpio_if = audio_codec_new_gpio();
```

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

### Development Environment Commands

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Commands to synchronize the development environment, run tests, and perform linting and type checking.

```bash
uv sync --extra dev --extra ble
uv run pytest
uv run ruff check .
uv run mypy src
```

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

### Run project verification commands

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/CONTRIBUTING.md

Execute these commands to run tests, linting, and type checking before submitting changes.

```bash
uv run pytest
uv run ruff check .
uv run mypy src
```

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

### API Connection and Encoding Configuration

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

Base configuration for connecting to the local daemon instance.

```text
Base URL: http://127.0.0.1:19280
Content-Type: application/json; charset=utf-8
```

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

### Initialize I2C and I2S drivers

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/src/bsp_codec/README.md

Initializes the codec control and data bus interfaces.

```c
ut_i2c_init(0);
ut_i2s_init(0);
```

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

### Manage vk-daemon configuration

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Commands to display, modify, and run the daemon with custom configuration files.

```bash
uv run vk-daemon config show
uv run vk-daemon config set yolo.active true
uv run vk-daemon config set ble.scan_timeout_seconds 10
uv run vk-daemon --config ./vk.toml serve --no-ble
```

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

### POST /button

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Sends a logical button action to the daemon.

```APIDOC
## POST /button

### Description
Send a logical button action.

### Method
POST

### Endpoint
/button
```

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

### Flash firmware to ESP32-S3

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/firmware/README.md

Use this command to write a firmware binary to an ESP32-S3 device with specific flash settings.

```bash
esptool --chip esp32s3  --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 80m 0x0 firmware.bin
```

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

### Verify voice permissions

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Expected log output confirming microphone and accessibility authorization.

```text
voice.microphone status=authorized
voice.accessibility status=authorized
```

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

### Device Snapshot Synchronization Flow

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Sequence diagram illustrating the synchronization process for subsequent updates after the initial connection.

```mermaid
sequenceDiagram
    participant D as vk-daemon
    participant P as BLE peripheral
    opt Session changed
        D->>P: SessionUpsert(changed_session, active)
    end
    opt Session ended
        D->>P: SessionRemove(ended_session_id)
    end
    D->>P: NotificationListUpdate
    D->>P: YoloConfigUpdate
    loop Every pending permission
        D->>P: PermissionRequest
    end
```

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

### POST /knob

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Sends a rotary input action to the daemon.

```APIDOC
## POST /knob

### Description
Send a rotary input.

### Method
POST

### Endpoint
/knob
```

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

### YOLO Configuration Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

Defines security rules for tool execution using glob matching. Deny rules take precedence over allow rules, and the total size must be under 500 bytes.

```json
{
  "active": false,
  "allow": ["Read(*)", "Glob(*)", "Grep(*)"],
  "deny": ["Bash(git push*)", "Bash(rm -rf*)", "Bash(sudo*)"],
  "notify_auto_allow": true,
  "auto_allow_log": true
}
```

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

### Package Directory Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Visual representation of the project's source code organization.

```text
src/vibe_keyboard/
  core/       dependency-free domain types
  protocol/   BLE message models and binary codec
  transport/  async transport contracts and optional BLE central
  daemon/     HTTP server, state, hooks, setup, and platform adapters
```

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

### SetLed Message

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Configures LED state for a specific button.

```text
tag:u8 = 0x84
button:ButtonId/u8
color:color
blink:bool
```

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

### SessionListUpdate Message

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Legacy full-list update for binary-codec compatibility.

```text
tag:u8 = 0x81
count:u8
sessions:SessionInfo[count]
active_index:u8
```

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

### BLE Session Synchronization Flow

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Sequence diagram illustrating the initial synchronization process upon establishing a new BLE connection.

```mermaid
sequenceDiagram
    participant D as vk-daemon
    participant P as BLE peripheral
    D->>P: TimeSync
    D->>P: SessionListClear(active_session_id)
    loop Every current session
        D->>P: SessionUpsert(session, active)
    end
    D->>P: NotificationListUpdate
    D->>P: YoloConfigUpdate
    loop Every pending permission
        D->>P: PermissionRequest
    end
```

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

### Define Custom Codec Configuration Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/src/bsp_codec/README.md

Use this structure to define the control and GPIO interfaces for a new codec device.

```c
typedef struct {
	const audio_codec_ctrl_if_t *ctrl_if;     /*!< Codec Control interface */
	const audio_codec_gpio_if_t *gpio_if;     /*!< If you want to operate GPIO */
	//...................................     Other settings
} my_codec_cfg_t;
const audio_codec_if_t *my_codec_new(my_codec_cfg_t *codec_cfg);
```

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

### Create ES8311 codec interface

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/src/bsp_codec/README.md

Configures the ES8311 codec with the previously created control and GPIO interfaces.

```c
es8311_codec_cfg_t es8311_cfg = {
    .codec_mode = ESP_CODEC_DEV_WORK_MODE_BOTH,
    .ctrl_if = out_ctrl_if,
    .gpio_if = gpio_if,
    .pa_pin = YOUR_PA_GPIO,
    .use_mclk = true,
};
const audio_codec_if_t *out_codec_if = es8311_codec_new(&es8311_cfg);
```

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

### Define SessionInfo Record

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Structure definition for session information, including the full record and the compacted version for BLE.

```text
id:u16
name:string
status:SessionStatus/u8
has_permission_request:bool
source:string
cwd:string
permission_mode:string
model:string
tokens_in:u64
tokens_out:u64
cost_usd:f64
context_pct:u8
last_message:string
last_ai_output:string
bundle_id:string
session_tty:string
started_at:u64
last_activity:u64
```

```text
name          max 35 UTF-8 bytes
source        max 23 UTF-8 bytes
model         max 23 UTF-8 bytes
last_message  max 128 UTF-8 bytes
```

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

### Simulate button click

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Send a JSON payload to the button endpoint to simulate a click action.

```bash
curl -sS \
  -H 'Content-Type: application/json' \
  -d '{"id":"send","action":"click"}' \
  http://127.0.0.1:19280/button
```

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

### FrameData Message

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Reserved legacy codec variant; peripherals may ignore this.

```text
tag:u8 = 0x88
width:u16
height:u16
pixel_byte_length:u32
pixels:byte[pixel_byte_length]
```

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

### Inspect daemon state

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Use curl to check the health, device state, and active sessions of the daemon.

```bash
curl -sS http://127.0.0.1:19280/health
curl -sS http://127.0.0.1:19280/device/state
curl -sS http://127.0.0.1:19280/sessions
```

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

### YoloConfigUpdate Data Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Defines the authoritative YOLO state snapshot structure used during device synchronization.

```text
tag:u8 = 0x93
active:bool
notify_auto_allow:bool
allow_count:u8
allow:string[allow_count]
deny_count:u8
deny:string[deny_count]
```

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

### Retrieve Sessions

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

Fetches a list of active sessions from the daemon.

```http
GET /sessions HTTP/1.1
Host: 127.0.0.1:19280
```

```json
[]
```

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

### SessionListClear Message

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Initiates a BLE session resync by clearing the local table.

```text
tag:u8 = 0x8E
active_session_id:u16
```

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

### SetVolume Message

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Sets the device volume level.

```text
tag:u8 = 0x8A
volume:u8
```

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

### POST /knob Success Response

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

Standard success response for the /knob endpoint.

```json
{"ok": true}
```

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

### 0x93 YoloConfigUpdate

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

The YoloConfigUpdate message is used to synchronize the authoritative YOLO state, including allow and deny lists, from the daemon to the peripheral.

```APIDOC
## 0x93 YoloConfigUpdate

### Description
Returns the authoritative YOLO state during every device snapshot synchronization. The peripheral must replace its local YOLO state and rule lists with this snapshot.

### Payload Structure
- **tag** (u8) - 0x93
- **active** (bool) - Current active state
- **notify_auto_allow** (bool) - Auto-allow notification setting
- **allow_count** (u8) - Number of items in allow list
- **allow** (string[allow_count]) - List of allowed items
- **deny_count** (u8) - Number of items in deny list
- **deny** (string[deny_count]) - List of denied items
```

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

### ButtonPress Message Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Defines the structure for a button press event.

```text
tag:u8 = 0x01
button:ButtonId/u8
```

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

### YoloConfigRequest Message Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Defines the structure for requesting the current YOLO configuration.

```text
tag:u8 = 0x0B
```

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

### Send Button Action

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

Triggers a logical button action by specifying an ID and action type.

```json
{
  "id": "send",
  "action": "click"
}
```

```json
{"ok": true}
```

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

### Define SessionStatus Enum

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Enumeration of possible session states.

```text
0 thinking
1 tool_use
2 writing
3 done
4 error
5 idle
6 permission_needed
```

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

### PermissionRequest Message

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Request operator permission; truncated to 500 bytes for BLE GATT compatibility.

```text
tag:u8 = 0x83
session_id:u16
action_desc:string
```

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

### Define Primitive Data Types

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Lists the supported primitive data types and their byte representations for little-endian encoding.

```text
u8       1 byte unsigned integer
i16      2 byte signed integer, little-endian, two's complement
u16      2 byte unsigned integer, little-endian
u32      4 byte unsigned integer, little-endian
u64      8 byte unsigned integer, little-endian
f64      8 byte IEEE-754 float, little-endian
bool     u8, 0 = false, nonzero = true
color    3 bytes: r:u8, g:u8, b:u8
string   len:u16 followed by len bytes of UTF-8
```

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

### POST /knob Request Body

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

Payload for sending rotary encoder actions to the daemon.

```json
{
  "action": "cw",
  "steps": 1
}
```

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

### SetSoundMapping Message

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Maps a sound type to a specific sound ID.

```text
tag:u8 = 0x8C
sound_type:SoundType/u8
sound_id:string
```

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

### POST /permissions/{id}

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/README.md

Resolves a pending permission request by ID.

```APIDOC
## POST /permissions/{id}

### Description
Resolve one pending request.

### Method
POST

### Endpoint
/permissions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the permission request.
```

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

### SessionSwitch Message Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Defines the structure for a session switch event.

```text
tag:u8 = 0x07
session_id:u16
```

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

### Define PermissionAction Enum

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Enumeration of permission handling actions.

```text
0 allow
1 deny
2 always
```

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

### ButtonRelease Message Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Defines the structure for a button release event.

```text
tag:u8 = 0x02
button:ButtonId/u8
```

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

### TimeSync Message

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Synchronizes the peripheral clock with the daemon's UTC time.

```text
tag:u8 = 0x92
unix_time_ms:u64
utc_offset_minutes:i16
```

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

### Define SoundType Enum

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Enumeration of available sound types.

```text
0 permission_alert
1 session_complete
2 error
3 click
```

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

### SessionStatusChange Message

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Small status-only update for session state changes.

```text
tag:u8 = 0x82
session_id:u16
status:SessionStatus/u8
```

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

### YoloConfigSet Message Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Defines the structure for updating the YOLO configuration.

```text
tag:u8 = 0x0C
active:bool
notify_auto_allow:bool
allow_count:u8
allow:string[allow_count]
deny_count:u8
deny:string[deny_count]
```

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

### PermissionResponse Message Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Defines the structure for a permission response message.

```text
tag:u8 = 0x06
session_id:u16
action:PermissionAction/u8
```

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

### Define NotificationInfo Record

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Structure definition for notification data.

```text
id:u32
session_id:u16
session_name:string
status:SessionStatus/u8
description:string
timestamp:u64
read:bool
```

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

### SetKnobRing Message

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Sets the color of the knob ring.

```text
tag:u8 = 0x85
color:color
```

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

### Pending Permission Data Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

Represents a request for permission to execute a specific tool. The session_id is used as the identifier in the permission decision endpoint.

```json
{
  "session_id": 17,
  "tool_name": "Bash",
  "tool_input": "uv run pytest"
}
```

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

### Session Data Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

Represents the current state of an AI session. Status fields use specific enums and time fields are represented in Unix seconds.

```json
{
  "id": 17,
  "name": "Implement HTTP simulator",
  "status": "permission_needed",
  "has_permission": true,
  "source": "codex",
  "cwd": "/Users/example/project",
  "permission_mode": "default",
  "model": "gpt-5",
  "tokens_in": 3200,
  "tokens_out": 840,
  "cost_usd": 0.12,
  "context_pct": 18,
  "last_message": "Run the tests",
  "last_ai_output": "I need approval to continue.",
  "bundle_id": "com.example.terminal",
  "session_tty": "/dev/ttys004",
  "started_at": 1784700000,
  "last_activity": 1784700060
}
```

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

### TimeSyncRequest Message Structure

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/ble_protocol.md

Defines the structure for requesting a time synchronization from the daemon.

```text
tag:u8 = 0x0A
```

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

### Retrieve Notifications

Source: https://github.com/xinyuan-lilygo/lilygolib/blob/master/examples/VibeKeyboard/tools/vk-daemon/docs/http_api.md

Fetches a list of pending notifications ordered by priority and history.

```http
GET /notifications HTTP/1.1
Host: 127.0.0.1:19280
```

```json
[]
```