From 915dc066ddde051f85130cead1daaffbf5198cde Mon Sep 17 00:00:00 2001 From: Ed Zynda Date: Sat, 21 Mar 2026 21:15:27 +0300 Subject: [PATCH] docs: update documentation for recent features - Document theme persistence in themes.md and README.md - Document session commands (/resume, /export, /import, /name) in commands.md and sessions.md - Document prompt history (up/down arrows) in commands.md - Document SubscribeSubagent API in sdk/callbacks.md and advanced/subagents.md --- README.md | 2 ++ www/pages/advanced/subagents.md | 25 +++++++++++++++++++++++++ www/pages/cli/commands.md | 9 ++++++++- www/pages/sdk/callbacks.md | 22 ++++++++++++++++++++++ www/pages/sessions.md | 17 +++++++++++++++++ www/pages/themes.md | 12 ++++++++++++ 6 files changed, 86 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 37d0a50e..f8db7b17 100644 --- a/README.md +++ b/README.md @@ -232,6 +232,8 @@ Kit ships with 22 built-in color themes that control all UI elements. Switch at /theme tokyonight ``` +Theme selections are automatically saved and restored on next launch (stored in `~/.config/kit/preferences.yml`). + ### Custom themes Drop a `.yml` file in `~/.config/kit/themes/` (user) or `.kit/themes/` (project): diff --git a/www/pages/advanced/subagents.md b/www/pages/advanced/subagents.md index 53870bc9..0acd5d29 100644 --- a/www/pages/advanced/subagents.md +++ b/www/pages/advanced/subagents.md @@ -71,3 +71,28 @@ result, err := host.Subagent(ctx, kit.SubagentConfig{ Timeout: 5 * time.Minute, }) ``` + +### Real-time subagent events + +Use `SubscribeSubagent` to receive real-time events from LLM-initiated subagents (i.e., when the model uses the `spawn_subagent` tool). Register inside an `OnToolCall` handler using the tool call ID: + +```go +host.OnToolCall(func(e kit.ToolCallEvent) { + if e.ToolName == "spawn_subagent" { + host.SubscribeSubagent(e.ToolCallID, func(event kit.Event) { + switch ev := event.(type) { + case kit.MessageUpdateEvent: + fmt.Print(ev.Chunk) // streaming text from child + case kit.ToolCallEvent: + fmt.Printf("Child calling: %s\n", ev.ToolName) + case kit.ToolResultEvent: + fmt.Printf("Child result: %s\n", ev.ToolName) + } + }) + } +}) +``` + +The listener receives the same event types as `Subscribe()` (`ToolCallEvent`, `MessageUpdateEvent`, `ReasoningDeltaEvent`, etc.) but scoped to the child agent's activity. Listeners are cleaned up automatically when the subagent completes. + +If no listeners are registered for a tool call, no event dispatching overhead is incurred. diff --git a/www/pages/cli/commands.md b/www/pages/cli/commands.md index 9be87e14..c2eeac58 100644 --- a/www/pages/cli/commands.md +++ b/www/pages/cli/commands.md @@ -75,10 +75,17 @@ These commands are available inside the Kit TUI during an interactive session: | `/tree` | Navigate session tree | | `/fork` | Branch from an earlier message | | `/new` | Start a new session | -| `/name` | Set session display name | +| `/name [name]` | Set or show session display name | +| `/resume` | Open session picker to switch sessions (alias: `/r`) | | `/session` | Show session info | +| `/export [path]` | Export session as JSONL (default: auto-generated path) | +| `/import ` | Import a session from a JSONL file | | `/quit` | Exit Kit | +### Prompt history + +Use **↑** and **↓** arrow keys to navigate through previously submitted prompts. Kit keeps the last 100 entries. Consecutive duplicates are skipped. + ## ACP server Run Kit as an [ACP (Agent Client Protocol)](https://agentclientprotocol.com) agent server. ACP-compatible clients communicate with Kit over JSON-RPC 2.0 on stdin/stdout. diff --git a/www/pages/sdk/callbacks.md b/www/pages/sdk/callbacks.md index a1cdbf09..3f53c11c 100644 --- a/www/pages/sdk/callbacks.md +++ b/www/pages/sdk/callbacks.md @@ -113,3 +113,25 @@ host.OnAfterTurn(0, func(ctx context.Context) error { ``` The first argument is a priority (lower = runs first). + +## Subagent event monitoring + +Monitor real-time events from LLM-initiated subagents (when the model uses the `spawn_subagent` tool): + +```go +host.OnToolCall(func(e kit.ToolCallEvent) { + if e.ToolName == "spawn_subagent" { + host.SubscribeSubagent(e.ToolCallID, func(event kit.Event) { + // Receives the same event types as Subscribe(), scoped to the child agent + switch ev := event.(type) { + case kit.MessageUpdateEvent: + fmt.Print(ev.Chunk) + case kit.ToolCallEvent: + fmt.Printf("Subagent calling: %s\n", ev.ToolName) + } + }) + } +}) +``` + +`SubscribeSubagent` returns an unsubscribe function. Listeners are also cleaned up automatically when the subagent completes. See [Subagents](/advanced/subagents) for more details. diff --git a/www/pages/sessions.md b/www/pages/sessions.md index a6010b1e..4d409f9e 100644 --- a/www/pages/sessions.md +++ b/www/pages/sessions.md @@ -39,6 +39,8 @@ kit --resume kit -r ``` +The session picker supports search, scope/filter toggles (all sessions vs. current directory), and session deletion. You can also open it during a session with the `/resume` slash command. + ### Open a specific session ```bash @@ -46,6 +48,21 @@ kit --session path/to/session.jsonl kit -s path/to/session.jsonl ``` +## Session commands + +These slash commands are available during an interactive session: + +| Command | Description | +|---------|-------------| +| `/name [name]` | Set or display the session's display name | +| `/session` | Show session info (path, ID, message count) | +| `/resume` | Open the session picker to switch sessions | +| `/export [path]` | Export session as JSONL (auto-generates path if omitted) | +| `/import ` | Import and switch to a session from a JSONL file | +| `/tree` | Navigate the session tree | +| `/fork` | Branch from an earlier message | +| `/new` | Start a fresh session | + ## Ephemeral mode Run without creating a session file: diff --git a/www/pages/themes.md b/www/pages/themes.md index 4f6b8658..467fac53 100644 --- a/www/pages/themes.md +++ b/www/pages/themes.md @@ -19,6 +19,8 @@ Switch themes at runtime with the `/theme` command: Run `/theme` with no arguments to list all available themes. +**Theme selections are automatically saved** to `~/.config/kit/preferences.yml` and restored on next launch. You don't need to add anything to your config file — just `/theme ` and it sticks. + ## Built-in themes | Theme | Style | @@ -276,4 +278,14 @@ When multiple sources define the same theme name, later sources win: 3. Project-local themes (`.kit/themes/`) 4. Extension-registered themes (highest) +### Startup theme resolution + +At startup, Kit determines which theme to apply: + +1. **`.kit.yml` `theme:` key** — explicit config always wins (highest priority) +2. **`~/.config/kit/preferences.yml`** — persisted `/theme` selection +3. **Default `kitt` theme** — fallback + +The preferences file is updated automatically whenever you use `/theme` or `ctx.SetTheme()`. It is separate from `.kit.yml` so it never clobbers your config comments or formatting. + Theme changes via `/theme` or `ctx.SetTheme()` take effect immediately on all UI elements, including previously rendered messages.