Repository navigation
docs: auto-update documentation (2026-10-26) #479
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -465,10 +465,91 @@ Every discovered session is attributed to an **origin** that describes how it wa | |
| | `discord` | Started by the agent's Discord bot | | ||
| | `slack` | Started by the agent's Slack bot | | ||
| | `schedule` | Started by a scheduled job (`trigger_type: schedule`) | | ||
| | `adopted` | Pre-existing session explicitly claimed via the adoption API | | ||
| | `native` | Started by running `claude` directly in the terminal, in a working directory that an herdctl agent also uses. Jobs with other trigger types (manual, webhook, chat, fork) are also grouped here. These sessions are discovered and displayed but not managed by herdctl. | | ||
|
|
||
| Attribution is determined by cross-referencing herdctl's job metadata files and the platform session records under `.herdctl/`. A native session can also be continued interactively from the web dashboard ("ad hoc" continuation) — herdctl then creates a new interactive session that picks up the conversation. | ||
|
|
||
| ## Session Adoption | ||
|
|
||
| The session adoption API allows you to claim pre-existing Claude Code sessions—conversations started outside herdctl—and make them discoverable, attributed, and resumable under a specific agent. This is useful when you have existing Claude Code terminal sessions for a project and want to bring them into herdctl for visibility and management. | ||
|
|
||
| :::note[Library API Only] | ||
| Session adoption is currently a **library API only** — there is no `herdctl sessions adopt` CLI command. Use `FleetManager.adoptSession()`, `adoptSessionsFrom()`, or `listAdoptableSessions()` programmatically. | ||
| ::: | ||
|
|
||
| ### Why Adopt Sessions? | ||
|
|
||
| When you run `claude` directly in your terminal before setting up herdctl, those sessions are stored in `~/.claude/projects/` but have no association with any herdctl agent. Session adoption: | ||
|
|
||
| - Makes those conversations **visible** in the web dashboard under the agent | ||
| - Preserves full **conversation history** for future reference | ||
| - Enables **resuming** those sessions as if they were started by herdctl | ||
| - Provides **proper attribution** (origin: `adopted`) so you can distinguish imported vs. new sessions | ||
|
|
||
| ### Listing Adoptable Sessions | ||
|
|
||
| The `listAdoptableSessions()` method scans a working directory's Claude Code transcript folder to find sessions that can be adopted: | ||
|
|
||
| ```typescript | ||
| const adoptable = await manager.listAdoptableSessions('my-agent'); | ||
|
|
||
| for (const session of adoptable) { | ||
| console.log(session.sessionId); | ||
| console.log(` Auto-name: ${session.autoName}`); | ||
| console.log(` Modified: ${session.mtime}`); | ||
| } | ||
| ``` | ||
|
|
||
| This returns only **adoptable** sessions — native, non-sidechain transcripts that are not already adopted and not attributed to a real run. See [`listAdoptableSessions()` in the FleetManager reference](/library-reference/fleet-manager/#listadoptablesessionsname-fromworkingdir) for details. | ||
|
|
||
| ### Adopting a Single Session | ||
|
|
||
| Use `adoptSession()` to claim one session by ID: | ||
|
|
||
| ```typescript | ||
| await manager.adoptSession('my-agent', '0f3c8b2a-...'); | ||
| ``` | ||
|
|
||
| This records an adoption claim in `.herdctl/adopted-sessions/` and makes the session appear under the agent with `origin: "adopted"`. **No files are moved** — the transcript stays where it is. | ||
|
|
||
| ### Bulk Adoption | ||
|
|
||
| The `adoptSessionsFrom()` method adopts every adoptable session found in a directory, optionally moving or linking the transcript files into the agent's own folder: | ||
|
|
||
| ```typescript | ||
| const result = await manager.adoptSessionsFrom('my-agent', { | ||
| fromWorkingDir: '/Users/ed/Code/myproject', | ||
| mode: 'copy', // 'copy' | 'move' | 'link' | ||
| dryRun: false, | ||
| }); | ||
|
|
||
| console.log(`Adopted ${result.adopted.length} sessions`); | ||
| for (const skip of result.skipped) { | ||
| console.warn(`Skipped ${skip.sessionId}: ${skip.reason}`); | ||
| } | ||
| ``` | ||
|
|
||
| Placement modes: | ||
|
|
||
| | Mode | Effect | | ||
| |------|--------| | ||
| | `copy` (default) | Duplicate the transcript file, preserving the original | | ||
| | `move` | Relocate the file (disappears from the user's terminal history) | | ||
| | `link` | Hard-link (same inode, so resumes append to the original too) | | ||
|
|
||
| See [`adoptSessionsFrom()` in the FleetManager reference](/library-reference/fleet-manager/#adoptsessionsfromname-opts) for full details. | ||
|
|
||
| ### Releasing an Adoption | ||
|
|
||
| The `unadoptSession()` method releases a session this agent had adopted: | ||
|
|
||
| ```typescript | ||
| const released = await manager.unadoptSession('my-agent', '0f3c8b2a-...'); | ||
| ``` | ||
|
|
||
| This removes the adoption record only — **the transcript stays on disk**. The session reverts to an ordinary unattributed native session: visible in all-sessions views, invisible under the agent. | ||
|
|
||
| Attribution matters because it tells you at a glance whether a session is something herdctl is responsible for or something a developer started independently. In the dashboard, sessions are labeled with their origin so you can filter and distinguish between managed and unmanaged activity. | ||
|
|
||
| ## Sidechain Sessions | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -15,6 +15,7 @@ Every schedule needs a trigger to determine when it runs. The trigger type you c | |
| | **Cron** | Precise timing (daily reports, scheduled maintenance) | Available | | ||
| | **Webhook** | Event-driven automation (deployments, external events) | Future | | ||
| | **Chat** | Interactive responses (support, commands) | Available | | ||
| | **Spawned** | Sub-agent jobs created via the Task tool | System-generated | | ||
|
Contributor
There was a problem hiding this comment. 🔎 Supported by static analysis
Remove the automatic No non-test code sets the trigger type to Either revise the Spawned row and the new section in
 |
||
|
|
||
| ## Interval Triggers | ||
|
|
||
|
|
@@ -456,6 +457,31 @@ Users can ask the bot questions like "What's the current price?" between schedul | |
| - Background automation (use cron or interval) | ||
| - Event-driven workflows (use webhook when available) | ||
|
|
||
| ## Spawned Trigger Type | ||
|
|
||
| The `spawned` trigger type is a system-generated marker for jobs created by sub-agents via the Task tool. You cannot create a schedule with `type: spawned` — this trigger type exists only as job metadata to record provenance. | ||
|
|
||
| When an agent uses the Task tool to spawn a sub-agent, herdctl creates a job with `trigger_type: spawned`. This allows you to: | ||
|
|
||
| - **Filter jobs** by spawn origin in job listings | ||
| - **Track delegation** patterns — which agents spawn sub-agents and how often | ||
| - **Distinguish** between user-initiated and agent-initiated work | ||
|
|
||
| The `spawned` type is an enum value in the job metadata schema, ensuring type safety and enabling downstream consumers (like dashboards or analytics tools) to distinguish spawned jobs from scheduled, manual, or chat-triggered runs. | ||
|
|
||
| ### Example Job Metadata | ||
|
|
||
| ```yaml | ||
| id: job-2024-01-19-xyz789 | ||
| agent: my-subagent | ||
| trigger_type: spawned # Set by the Task tool | ||
| status: completed | ||
| started_at: "2024-01-19T10:30:00Z" | ||
| finished_at: "2024-01-19T10:32:15Z" | ||
| ``` | ||
|
|
||
| This trigger type is purely informational — it has no scheduling logic of its own. | ||
|
|
||
| ## Choosing the Right Trigger | ||
|
|
||
| ### Decision Guide | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -87,6 +87,20 @@ Claude Code files a remote server's stored OAuth token under a key derived from | |
|
|
||
| --- | ||
|
|
||
| ## Inline Images from MCP Tools | ||
|
|
||
| MCP tools can return image content as part of their results. When a tool returns an image (for example, a Playwright screenshot or a generated diagram), herdctl extracts the image and makes it available to the agent. In the web dashboard, these images are displayed inline in the chat conversation, providing visual context directly in the message feed. | ||
|
|
||
| **Example use cases:** | ||
|
|
||
| - **Screenshot tools**: A Playwright-based MCP server captures a screenshot of a web page and returns it as an image | ||
| - **Diagram generators**: A tool that creates architecture diagrams, charts, or graphs | ||
| - **Computer vision**: Tools that process images and return annotated versions | ||
|
|
||
| The agent sees the image content as part of the tool result and can reference it in its response. The web dashboard automatically renders these images inline, making visual information immediately accessible. | ||
|
|
||
| For more details on inline image display, see the [Web Dashboard: Inline Images](/integrations/web-dashboard/#inline-images) section. | ||
|
|
||
| ## Tool Naming Convention | ||
|
|
||
| MCP tools are namespaced using the `mcp__<server>__<tool>` pattern: | ||
|
|
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Describe usage as conditional, not universal.
Line 381 claims that every completed job persists usage.
job-executor.tsaddsusageonly whenrunUsageexists, andextractRunUsagereturnsundefinedwhen no terminal result or usable accounting exists. A completed job can therefore omitusage. Qualify this sentence and the later availability wording to include runs without recorded usage.