### Install @akonwi/opencode-kit

Source: https://github.com/akonwi/opencode-kit/blob/main/README.md

Install the package using the Bun package manager.

```bash
bun add @akonwi/opencode-kit
```

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

### KitConfig Type Definition and Example

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Defines the TypeScript interface for the configuration object, including constraints for bells, speech, and logging levels. Shows an example of a typed configuration object.

```typescript
import type { KitConfig, LogLevel } from "@akonwi/opencode-kit";

// Full type definition
interface KitConfig {
  bells: {
    enabled: boolean;          // Enable/disable terminal bells
    errorSound: "Funk";        // macOS system sound (only "Funk" supported)
  };
  speech: {
    enabled: boolean;          // Enable/disable text-to-speech
    maxChars: number;          // Max characters for speech (20-2000)
    voice: string | null;      // macOS voice name or null for default
  };
  debug: {
    logLevel: LogLevel;        // "debug" | "info" | "warn" | "error"
  };
}

// Example usage in typed code
const config: KitConfig = {
  bells: { enabled: true, errorSound: "Funk" },
  speech: { enabled: true, maxChars: 220, voice: "Samantha" },
  debug: { logLevel: "info" }
};
```

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

### HandoffResult Type Definition and Example

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Defines the TypeScript interface for the result of a handoff operation, including session IDs, summary, and the seeded prompt. Provides an example of a successful handoff result.

```typescript
import type { HandoffResult } from "@akonwi/opencode-kit";

// Type definition
interface HandoffResult {
  sourceSessionID: string;     // Original session ID
  newSessionID?: string;       // Created session ID (set after creation)
  summary: string;             // Compacted context from source session
  seededPrompt: string;        // Full prompt sent to new session
}

// Example result after successful handoff
const result: HandoffResult = {
  sourceSessionID: "sess_abc123",
  newSessionID: "sess_def456",
  summary: "User asked to implement auth... Assistant created login form...",
  seededPrompt: "Continue the work\n\n---\n\nHandoff context...\n\nSource session ID: sess_abc123"
};
```

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

### Sanitize Configuration Input

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Use `sanitizeConfig` to validate and normalize configuration objects. It handles partial or invalid inputs by applying default values. Pass `null` or an array to get full defaults.

```typescript
import { sanitizeConfig } from "@akonwi/opencode-kit";

// Sanitize partial or invalid input
const safe = sanitizeConfig({
  bells: { enabled: "yes" },  // invalid boolean -> true (default)
  speech: { maxChars: 50000 } // out of range -> 220 (default)
});

// Result:
// {
//   bells: { enabled: true, errorSound: "Funk" },
//   speech: { enabled: true, maxChars: 220, voice: null },
//   debug: { logLevel: "info" }
// }

// Handles completely invalid input
const fromNull = sanitizeConfig(null);        // returns full defaults
const fromArray = sanitizeConfig([1, 2, 3]);  // returns full defaults
```

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

### Configure opencode-kit

Source: https://github.com/akonwi/opencode-kit/blob/main/README.md

Define notification and logging settings in the kit.json configuration file.

```json
{
  "bells": {
    "enabled": true,
    "errorSound": "Funk"
  },
  "speech": {
    "enabled": true,
    "maxChars": 220,
    "voice": null
  },
  "debug": {
    "logLevel": "info"
  }
}
```

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

### /handoff Command

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Creates a new OpenCode session with compacted context from the current session.

```APIDOC
## /handoff [prompt]

### Description
Transfers context from the current session to a fresh session. It captures the current session ID, summarizes recent messages, and seeds the new session.

### Parameters
- **prompt** (string) - Optional - The initial prompt for the new session. Defaults to 'Continue from this handoff context.'
```

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

### Create New OpenCode Session with Context (/handoff)

Source: https://context7.com/akonwi/opencode-kit/llms.txt

The `/handoff` command creates a new OpenCode session, transferring context from the current session. It summarizes recent messages and seeds the new session with a prompt and the summarized context. If no prompt is given, a default prompt is used.

```bash
# Inside OpenCode chat, run:
/handoff Continue implementing the authentication feature

# What happens:
# 1. Captures the current session ID as source reference
# 2. Builds a compact summary from recent messages (up to 4 snippets, max 1400 chars)
# 3. Creates a new session via OpenCode API
# 4. Seeds the new session with your prompt + context + source session ID
# 5. Opens the TUI session selector so you can switch immediately

# The seeded prompt in the new session looks like:
# ---
# Continue implementing the authentication feature
#
# ---
#
# Handoff context from prior session:
#
# [Compacted summary of recent messages]
#
# Source session ID: abc123-def456
#
# Use this source session ID to retrieve prior session context if needed.
# ---

# If no prompt is provided:
/handoff
# Uses default: "Continue from this handoff context."
```

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

### Development commands

Source: https://github.com/akonwi/opencode-kit/blob/main/README.md

Standard development workflow commands for the project.

```bash
bun install
bun run format
bun run lint
bun run build
```

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

### Manage settings via CLI

Source: https://github.com/akonwi/opencode-kit/blob/main/README.md

Use the oc-kit command to toggle or check the status of bells and speech notifications.

```bash
oc-kit bells on
oc-kit bells off
oc-kit bells toggle
oc-kit bells status

oc-kit speech on
oc-kit speech off
oc-kit speech toggle
oc-kit speech status
```

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

### Configuration File Structure

Source: https://context7.com/akonwi/opencode-kit/llms.txt

The runtime configuration for OpenCode Kit is stored in `~/.config/opencode/kit.json`. Changes to this file take effect immediately without requiring a restart.

```APIDOC
## Configuration File

Runtime configuration is stored in `~/.config/opencode/kit.json`. The plugin reads this file on each event, so changes take effect immediately without restart.

```json
{
  "bells": {
    "enabled": true,
    "errorSound": "Funk"
  },
  "speech": {
    "enabled": true,
    "maxChars": 220,
    "voice": null
  },
  "debug": {
    "logLevel": "info"
  }
}
```
```

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

### Define kit.json configuration schema

Source: https://github.com/akonwi/opencode-kit/blob/main/opencode-kit-plan.md

The configuration file schema for managing sound, speech, and debug settings at runtime.

```json
{
  "sounds": {
    "enabled": true,
    "idleBell": true,
    "errorSound": "Funk",
    "speech": {
      "enabled": true,
      "maxChars": 220,
      "voice": null
    }
  },
  "debug": {
    "toasts": true,
    "logLevel": "info"
  }
}
```

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

### Read Configuration

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Retrieve and sanitize the current configuration from disk, returning default values if the file is missing or corrupted.

```typescript
import { readConfig, type KitConfig } from "@akonwi/opencode-kit";

// Read current configuration (async)
const config: KitConfig = await readConfig();

console.log(config.bells.enabled);      // boolean - whether bells are on
console.log(config.speech.enabled);     // boolean - whether speech is on
console.log(config.speech.maxChars);    // number - max characters for speech (20-2000)
console.log(config.speech.voice);       // string | null - macOS voice name
console.log(config.debug.logLevel);     // "debug" | "info" | "warn" | "error"

// If config file is missing or invalid, returns defaults:
// {
//   bells: { enabled: true, errorSound: "Funk" },
//   speech: { enabled: true, maxChars: 220, voice: null },
//   debug: { logLevel: "info" }
// }
```

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

### writeConfig()

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Writes a sanitized configuration to disk using atomic write (temp file + rename). Ensures the config directory exists before writing.

```APIDOC
## writeConfig()

Writes a sanitized configuration to disk using atomic write (temp file + rename). Ensures the config directory exists before writing.

```typescript
import { writeConfig, type KitConfig } from "@akonwi/opencode-kit";

const newConfig: KitConfig = {
  bells: { enabled: false, errorSound: "Funk" },
  speech: { enabled: true, maxChars: 300, voice: "Samantha" },
  debug: { logLevel: "debug" }
};

// Write atomically to ~/.config/opencode/kit.json
await writeConfig(newConfig);

// Config is sanitized before writing - invalid values are replaced with defaults
// The file is written with 2-space indentation and trailing newline
```
```

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

### createLogger()

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Creates a structured JSON-line logger that writes to the local filesystem.

```APIDOC
## createLogger(level)

### Description
Initializes a logger that writes structured JSON logs to `~/.config/opencode/logs/opencode-kit.log`.

### Parameters
- **level** (string) - Optional - The initial log level (debug, info, warn, error). Defaults to 'info'.
```

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

### readConfig()

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Reads and sanitizes the configuration from disk. Returns safe defaults if the file is missing or contains invalid data. All fields are validated and normalized.

```APIDOC
## readConfig()

Reads and sanitizes the configuration from disk. Returns safe defaults if the file is missing or contains invalid data. All fields are validated and normalized.

```typescript
import { readConfig, type KitConfig } from "@akonwi/opencode-kit";

// Read current configuration (async)
const config: KitConfig = await readConfig();

console.log(config.bells.enabled);      // boolean - whether bells are on
console.log(config.speech.enabled);     // boolean - whether speech is on
console.log(config.speech.maxChars);    // number - max characters for speech (20-2000)
console.log(config.speech.voice);       // string | null - macOS voice name
console.log(config.debug.logLevel);     // "debug" | "info" | "warn" | "error"

// If config file is missing or invalid, returns defaults:
// {
//   bells: { enabled: true, errorSound: "Funk" },
//   speech: { enabled: true, maxChars: 220, voice: null },
//   debug: { logLevel: "info" }
// }
```
```

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

### CLI: oc-kit speech

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Control text-to-speech announcements from the command line. Requires macOS.

```APIDOC
## oc-kit speech [action]

### Description
Controls text-to-speech announcements. Available actions: on, off, toggle, status.

### Parameters
- **action** (string) - Required - The action to perform on the speech setting.
```

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

### Register the OpencodeKit Plugin

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Import and register the plugin within the OpenCode configuration to enable automated notifications and command handling.

```typescript
// In your OpenCode plugin configuration, register the OpencodeKit plugin
import { OpencodeKit } from "@akonwi/opencode-kit";

// Or using default export
import OpencodeKit from "@akonwi/opencode-kit";

// The plugin automatically:
// - Plays terminal bell when session becomes idle
// - Speaks a summary of the last assistant message (macOS only)
// - Plays "Funk" sound on errors (macOS) or terminal bell (other platforms)
// - Registers the /handoff command for session handoffs
```

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

### Control Text-to-Speech Announcements via CLI

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Use the `oc-kit speech` command to manage text-to-speech announcements. This feature relies on the macOS `say` command and is only available on macOS. Supports enabling, disabling, toggling, and checking status.

```bash
# Enable speech
oc-kit speech on
# Output:
# updated speech.enabled=true
# status bells=on speech=on
# config=/Users/you/.config/opencode/kit.json

# Disable speech
oc-kit speech off
# Output:
# updated speech.enabled=false
# status bells=on speech=off
# config=/Users/you/.config/opencode/kit.json

# Toggle speech state
oc-kit speech toggle

# Check current status
oc-kit speech status
# Output:
# bells=on speech=off
# config=/Users/you/.config/opencode/kit.json
```

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

### Plugin Registration

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Register the OpencodeKit plugin with your OpenCode configuration to enable features like terminal bells, speech synthesis, and the /handoff command.

```APIDOC
## Plugin Registration

The main plugin export that integrates with OpenCode's plugin system. It provides event handling for session idle/error states, message tracking for speech synthesis, and command handling for the `/handoff` feature.

```typescript
// In your OpenCode plugin configuration, register the OpencodeKit plugin
import { OpencodeKit } from "@akonwi/opencode-kit";

// Or using default export
import OpencodeKit from "@akonwi/opencode-kit";

// The plugin automatically:
// - Plays terminal bell when session becomes idle
// - Speaks a summary of the last assistant message (macOS only)
// - Plays "Funk" sound on errors (macOS) or terminal bell (other platforms)
// - Registers the /handoff command for session handoffs
```
```

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

### Create Structured JSON-Line Logger

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Use `createLogger` to instantiate a logger that writes JSON-formatted logs to a file. Supports dynamic log level changes and includes contextual metadata with each log entry. Available levels are debug, info, warn, and error.

```typescript
import { createLogger, type Logger, type LogContext } from "@akonwi/opencode-kit";

// Create logger with default level (info)
const logger: Logger = createLogger();

// Create logger with specific level
const debugLogger = createLogger("debug");

// Set level dynamically
logger.setLevel("warn"); // only warn and error will be logged

// Log with event name, message, and optional context
logger.debug("cache.hit", "Found cached value", { key: "user_123" });
logger.info("request.start", "Processing request", { method: "GET", path: "/api" });
logger.warn("rate.limit", "Approaching rate limit", { remaining: 5 });
logger.error("db.connection", "Database connection failed", { host: "localhost" });

// Log output format (one JSON object per line):
// {"timestamp":"2024-01-15T10:30:00.000Z","level":"info","event":"request.start","message":"Processing request","context":{"method":"GET","path":"/api"}}

// Log levels and weights:
// debug: 10 - verbose debugging info
// info:  20 - general operational info
// warn:  30 - warning conditions
// error: 40 - error conditions
```

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

### Write Configuration

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Persist a sanitized configuration to disk using an atomic write operation to ensure data integrity.

```typescript
import { writeConfig, type KitConfig } from "@akonwi/opencode-kit";

const newConfig: KitConfig = {
  bells: { enabled: false, errorSound: "Funk" },
  speech: { enabled: true, maxChars: 300, voice: "Samantha" },
  debug: { logLevel: "debug" }
};

// Write atomically to ~/.config/opencode/kit.json
await writeConfig(newConfig);

// Config is sanitized before writing - invalid values are replaced with defaults
// The file is written with 2-space indentation and trailing newline
```

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

### sanitizeConfig()

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Validates and normalizes configuration input. This function is used internally but is exported for custom configuration handling.

```APIDOC
## sanitizeConfig(config)

### Description
Validates and normalizes configuration input, applying default values for invalid or out-of-range settings.

### Parameters
- **config** (object|null|any) - Required - The configuration object to sanitize.

### Response
- **Returns** (object) - A sanitized configuration object with default values applied where necessary.
```

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

### updateConfig()

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Atomically reads, mutates, and writes configuration. The mutator function receives the current config and returns the new config. Both input and output are sanitized.

```APIDOC
## updateConfig()

Atomically reads, mutates, and writes configuration. The mutator function receives the current config and returns the new config. Both input and output are sanitized.

```typescript
import { updateConfig } from "@akonwi/opencode-kit";

// Toggle bells off
const updated = await updateConfig((current) => ({
  ...current,
  bells: { ...current.bells, enabled: false }
}));

console.log(updated.bells.enabled); // false

// Toggle speech and change max characters
await updateConfig((current) => ({
  ...current,
  speech: {
    ...current.speech,
    enabled: !current.speech.enabled,
    maxChars: 500
  }
}));
```
```

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

### CLI: oc-kit bells

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Control terminal bell notifications from the command line. Changes are persisted to the configuration file.

```APIDOC
## oc-kit bells [action]

### Description
Controls terminal bell notifications. Available actions: on, off, toggle, status.

### Parameters
- **action** (string) - Required - The action to perform on the bells setting.
```

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

### KitConfig Type

Source: https://context7.com/akonwi/opencode-kit/llms.txt

TypeScript interface defining the configuration object for OpenCode Kit. All fields are required and have specific constraints.

```APIDOC
## KitConfig Type

### Description
TypeScript interface for the configuration object. All fields are required and have specific constraints.

### Type Definition
```typescript
interface KitConfig {
  bells: {
    enabled: boolean;          // Enable/disable terminal bells
    errorSound: "Funk";        // macOS system sound (only "Funk" supported)
  };
  speech: {
    enabled: boolean;          // Enable/disable text-to-speech
    maxChars: number;          // Max characters for speech (20-2000)
    voice: string | null;      // macOS voice name or null for default
  };
  debug: {
    logLevel: LogLevel;        // "debug" | "info" | "warn" | "error"
  };
}

// LogLevel type
type LogLevel = "debug" | "info" | "warn" | "error";
```

### Example Usage
```typescript
import type { KitConfig } from "@akonwi/opencode-kit";

const config: KitConfig = {
  bells: { enabled: true, errorSound: "Funk" },
  speech: { enabled: true, maxChars: 220, voice: "Samantha" },
  debug: { logLevel: "info" }
};
```
```

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

### Control Terminal Bell Notifications via CLI

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Use the `oc-kit bells` command to manage terminal bell notifications. Changes are saved to the config file and applied immediately. Supports enabling, disabling, toggling, and checking status.

```bash
# Enable bells
oc-kit bells on
# Output:
# updated bells.enabled=true
# status bells=on speech=on
# config=/Users/you/.config/opencode/kit.json

# Disable bells
oc-kit bells off
# Output:
# updated bells.enabled=false
# status bells=off speech=on
# config=/Users/you/.config/opencode/kit.json

# Toggle bells state
oc-kit bells toggle
# Output:
# updated bells.enabled=true
# status bells=on speech=on
# config=/Users/you/.config/opencode/kit.json

# Check current status
oc-kit bells status
# Output:
# bells=on speech=on
# config=/Users/you/.config/opencode/kit.json
```

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

### Update Configuration

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Perform an atomic read-mutate-write cycle to update specific configuration fields.

```typescript
import { updateConfig } from "@akonwi/opencode-kit";

// Toggle bells off
const updated = await updateConfig((current) => ({
  ...current,
  bells: { ...current.bells, enabled: false }
}));

console.log(updated.bells.enabled); // false

// Toggle speech and change max characters
await updateConfig((current) => ({
  ...current,
  speech: {
    ...current.speech,
    enabled: !current.speech.enabled,
    maxChars: 500
  }
}));
```

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

### Notify Idle with Speech and Bell

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Triggers an idle notification with optional terminal bell and spoken summary. Cleans markdown and truncates text for speech output. Requires macOS for speech.

```typescript
import { notifyIdle } from "@akonwi/opencode-kit";
import { readConfig } from "@akonwi/opencode-kit";
import { createLogger } from "@akonwi/opencode-kit";

const config = await readConfig();
const logger = createLogger();

// Notify with assistant's last message for speech
await notifyIdle(
  "I've completed the refactoring of the authentication module. The tests are passing.",
  config,
  logger
);

// What happens:
// 1. If bells.enabled: writes terminal bell character (\u0007)
// 2. If speech.enabled and text provided:
//    - Cleans markdown (removes code blocks, links, formatting)
//    - Truncates to speech.maxChars (default 220)
//    - Runs: say [-v voice] "cleaned text" (macOS only)

// Notify without speech text (bell only)
await notifyIdle("", config, logger);
```

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

### HandoffResult Type

Source: https://context7.com/akonwi/opencode-kit/llms.txt

TypeScript interface representing the result of a handoff operation, containing session IDs and generated context.

```APIDOC
## HandoffResult Type

### Description
TypeScript interface returned by the handoff operation. Contains references to both sessions and the generated context.

### Type Definition
```typescript
interface HandoffResult {
  sourceSessionID: string;     // Original session ID
  newSessionID?: string;       // Created session ID (set after creation)
  summary: string;             // Compacted context from source session
  seededPrompt: string;        // Full prompt sent to new session
}
```

### Example Result
```typescript
import type { HandoffResult } from "@akonwi/opencode-kit";

const result: HandoffResult = {
  sourceSessionID: "sess_abc123",
  newSessionID: "sess_def456",
  summary: "User asked to implement auth... Assistant created login form...",
  seededPrompt: "Continue the work\n\n---\n\nHandoff context...\n\nSource session ID: sess_abc123"
};
```
```

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

### notifyIdle() - Trigger Idle Notification

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Triggers an idle notification with optional terminal bell and speech. This function is called automatically when a session becomes idle.

```APIDOC
## notifyIdle()

### Description
Triggers an idle notification with optional terminal bell and speech. Called automatically by the plugin when a session becomes idle.

### Method
`await` (asynchronous function)

### Parameters
- **text** (string) - Optional - The text to be spoken. If provided, it will be cleaned and truncated before speech.
- **config** (KitConfig) - Required - The configuration object for the kit.
- **logger** (Logger) - Required - The logger instance.

### What happens:
1. If `bells.enabled`: writes terminal bell character (\u0007).
2. If `speech.enabled` and `text` is provided:
   - Cleans markdown (removes code blocks, links, formatting).
   - Truncates to `speech.maxChars` (default 220).
   - Runs: `say [-v voice] "cleaned text"` (macOS only).

### Request Example
```typescript
import { notifyIdle } from "@akonwi/opencode-kit";
import { readConfig } from "@akonwi/opencode-kit";
import { createLogger } from "@akonwi/opencode-kit";

const config = await readConfig();
const logger = createLogger();

// Notify with assistant's last message for speech
await notifyIdle(
  "I've completed the refactoring of the authentication module. The tests are passing.",
  config,
  logger
);

// Notify without speech text (bell only)
await notifyIdle("", config, logger);
```

### Response
This function does not return a value.
```

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

### Notify Error with System Sound or Bell

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Triggers an error notification using a system sound on macOS or a terminal bell on other platforms. Speech is intentionally not triggered for errors.

```typescript
import { notifyError } from "@akonwi/opencode-kit";
import { readConfig } from "@akonwi/opencode-kit";
import { createLogger } from "@akonwi/opencode-kit";

const config = await readConfig();
const logger = createLogger();

// Trigger error notification
await notifyError(config, logger);

// What happens:
// - On macOS with bells.enabled:
//   Plays /System/Library/Sounds/Funk.aiff via afplay
// - On other platforms with bells.enabled:
//   Writes terminal bell character (\u0007)
// - No speech is triggered for errors (intentional design)
```

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

### notifyError() - Trigger Error Notification

Source: https://context7.com/akonwi/opencode-kit/llms.txt

Triggers an error notification with a system sound or terminal bell. This function is called automatically when a session encounters an error.

```APIDOC
## notifyError()

### Description
Triggers an error notification with system sound or terminal bell. Called automatically by the plugin when a session encounters an error.

### Method
`await` (asynchronous function)

### Parameters
- **config** (KitConfig) - Required - The configuration object for the kit.
- **logger** (Logger) - Required - The logger instance.

### What happens:
- On macOS with `bells.enabled`: Plays `/System/Library/Sounds/Funk.aiff` via `afplay`.
- On other platforms with `bells.enabled`: Writes terminal bell character (\u0007).
- No speech is triggered for errors (intentional design).

### Request Example
```typescript
import { notifyError } from "@akonwi/opencode-kit";
import { readConfig } from "@akonwi/opencode-kit";
import { createLogger } from "@akonwi/opencode-kit";

const config = await readConfig();
const logger = createLogger();

// Trigger error notification
await notifyError(config, logger);
```

### Response
This function does not return a value.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.