luca 3.0.0 → 3.1.0

package/docs/apis/features/agi/claude-code.md

@@ -1,884 +0,0 @@
-# ClaudeCode (features.claudeCode)
-
-Claude Code CLI wrapper feature. Spawns and manages Claude Code sessions as subprocesses, streaming structured JSON events back through the container's event system. Sessions are long-lived: each call to `run()` spawns a `claude -p` process with `--output-format stream-json`, parses NDJSON from stdout line-by-line, and emits typed events on the feature's event bus.
-
-## Usage
-
-```ts
-container.feature('claudeCode', {
-  // Claude CLI session ID to resume by default
-  session,
-  // Path to the claude CLI binary
-  claudePath,
-  // Default model to use for sessions
-  model,
-  // Default working directory for sessions
-  cwd,
-  // Default system prompt prepended to all sessions
-  systemPrompt,
-  // Default append system prompt for all sessions
-  appendSystemPrompt,
-  // Default permission mode for Claude CLI sessions
-  permissionMode,
-  // Default allowed tools for sessions
-  allowedTools,
-  // Default disallowed tools for sessions
-  disallowedTools,
-  // Whether to stream partial messages token-by-token
-  streaming,
-  // MCP config file paths to pass to sessions
-  mcpConfig,
-  // MCP server configs keyed by name, injected into sessions via temp config file
-  mcpServers,
-  // Path to write a parseable NDJSON session log file
-  fileLogPath,
-  // Verbosity level for file logging. Defaults to "normal"
-  fileLogLevel,
-  // Default effort level for Claude reasoning
-  effort,
-  // Maximum cost budget in USD per session
-  maxBudgetUsd,
-  // Fallback model when the primary model is unavailable
-  fallbackModel,
-  // Default agent to use
-  agent,
-  // Disable session persistence across runs
-  noSessionPersistence,
-  // Default tools to make available
-  tools,
-  // Require strict MCP config validation
-  strictMcpConfig,
-  // Path to a custom settings file
-  settingsFile,
-  // Directories containing Claude Code skills to load into sessions
-  skillsFolders,
-  // Launch Claude Code with a Chrome browser tool
-  chrome,
-})
-```
-
-## Options (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `session` | `string` | Claude CLI session ID to resume by default |
-| `claudePath` | `string` | Path to the claude CLI binary |
-| `model` | `string` | Default model to use for sessions |
-| `cwd` | `string` | Default working directory for sessions |
-| `systemPrompt` | `string` | Default system prompt prepended to all sessions |
-| `appendSystemPrompt` | `string` | Default append system prompt for all sessions |
-| `permissionMode` | `string` | Default permission mode for Claude CLI sessions |
-| `allowedTools` | `array` | Default allowed tools for sessions |
-| `disallowedTools` | `array` | Default disallowed tools for sessions |
-| `streaming` | `boolean` | Whether to stream partial messages token-by-token |
-| `mcpConfig` | `array` | MCP config file paths to pass to sessions |
-| `mcpServers` | `object` | MCP server configs keyed by name, injected into sessions via temp config file |
-| `fileLogPath` | `string` | Path to write a parseable NDJSON session log file |
-| `fileLogLevel` | `string` | Verbosity level for file logging. Defaults to "normal" |
-| `effort` | `string` | Default effort level for Claude reasoning |
-| `maxBudgetUsd` | `number` | Maximum cost budget in USD per session |
-| `fallbackModel` | `string` | Fallback model when the primary model is unavailable |
-| `agent` | `string` | Default agent to use |
-| `noSessionPersistence` | `boolean` | Disable session persistence across runs |
-| `tools` | `array` | Default tools to make available |
-| `strictMcpConfig` | `boolean` | Require strict MCP config validation |
-| `settingsFile` | `string` | Path to a custom settings file |
-| `skillsFolders` | `array` | Directories containing Claude Code skills to load into sessions |
-| `chrome` | `boolean` | Launch Claude Code with a Chrome browser tool |
-
-## Methods
-
-### assertMinVersion
-
-Assert that the detected CLI version meets a minimum major.minor requirement. Throws if the CLI version is below the specified minimum.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `major` | `number` | ✓ | Minimum major version |
-| `minor` | `number` | ✓ | Minimum minor version |
-
-**Returns:** `void`
-
-
-
-### checkAvailability
-
-Check if the Claude CLI is available and capture its version.
-
-**Returns:** `Promise<boolean>`
-
-```ts
-const available = await cc.checkAvailability()
-if (!available) throw new Error('Claude CLI not found')
-```
-
-
-
-### writeMcpConfig
-
-Write an MCP server config map to a temp file suitable for `--mcp-config`.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `servers` | `Record<string, McpServerConfig>` | ✓ | Server configs keyed by name |
-
-**Returns:** `Promise<string>`
-
-```ts
-const configPath = await cc.writeMcpConfig({
- 'my-api': { type: 'http', url: 'https://api.example.com/mcp' },
- 'local-tool': { type: 'stdio', command: 'bun', args: ['run', 'server.ts'] }
-})
-```
-
-
-
-### run
-
-Run a prompt in a new Claude Code session. Spawns a subprocess, streams NDJSON events, and resolves when the session completes.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `prompt` | `string` | ✓ | The instruction/prompt to send |
-| `options` | `RunOptions` |  | Session configuration overrides |
-
-`RunOptions` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `model` | `string` | Override model for this session. |
-| `cwd` | `string` | Override working directory. |
-| `systemPrompt` | `string` | System prompt for this session. |
-| `appendSystemPrompt` | `string` | Append system prompt for this session. |
-| `permissionMode` | `'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk'` | Permission mode override. |
-| `allowedTools` | `string[]` | Allowed tools override. |
-| `disallowedTools` | `string[]` | Disallowed tools override. |
-| `streaming` | `boolean` | Whether to stream partial messages. |
-| `resumeSessionId` | `string` | Resume a previous session by ID. |
-| `continue` | `boolean` | Continue the most recent conversation. |
-| `addDirs` | `string[]` | Additional directories to allow tool access to. |
-| `skillsFolders` | `string[]` | Directories containing Claude Code skills (SKILL.md files) to load into sessions. Merged with addDirs as --add-dir. |
-| `mcpConfig` | `string[]` | MCP config file paths. |
-| `mcpServers` | `Record<string, McpServerConfig>` | MCP servers to inject, keyed by server name. |
-| `dangerouslySkipPermissions` | `boolean` | Skip all permission checks (only for sandboxed environments). |
-| `extraArgs` | `string[]` | Additional arbitrary CLI flags. |
-| `fileLogPath` | `string` | Path to write a parseable NDJSON session log file. Overrides feature-level fileLogPath. |
-| `fileLogLevel` | `FileLogLevel` | Verbosity level for file logging. Overrides feature-level fileLogLevel. |
-| `effort` | `'low' | 'medium' | 'high'` | Effort level for Claude reasoning. |
-| `maxBudgetUsd` | `number` | Maximum cost budget in USD. |
-| `fallbackModel` | `string` | Fallback model when the primary is unavailable. |
-| `jsonSchema` | `string | object` | JSON schema for structured output validation. |
-| `agent` | `string` | Agent to use for this session. |
-| `sessionId` | `string` | Resume or fork a specific Claude session by ID. |
-| `noSessionPersistence` | `boolean` | Disable session persistence for this run. |
-| `forkSession` | `boolean` | Fork from an existing session instead of resuming. |
-| `tools` | `string[]` | Tools to make available. |
-| `strictMcpConfig` | `boolean` | Require strict MCP config validation. |
-| `debug` | `string | boolean` | Enable debug output. Pass a string for specific debug channels, or true for all. |
-| `debugFile` | `string` | Path to write debug output to a file. |
-| `settingsFile` | `string` | Path to a custom settings file. |
-| `chrome` | `boolean` | Launch Claude Code with a Chrome browser tool. |
-
-**Returns:** `Promise<ClaudeSession>`
-
-```ts
-// Simple one-shot
-const session = await cc.run('What files are in this project?')
-console.log(session.result)
-
-// With options
-const session = await cc.run('Refactor the auth module', {
- model: 'opus',
- cwd: '/path/to/project',
- permissionMode: 'acceptEdits',
- streaming: true
-})
-
-// With injected MCP servers
-const session = await cc.run('Use the database tools to list tables', {
- mcpServers: {
-   'db-tools': { type: 'stdio', command: 'bun', args: ['run', 'db-mcp.ts'] },
-   'api': { type: 'http', url: 'https://api.example.com/mcp' }
- }
-})
-
-// Resume a previous session
-const session = await cc.run('Now add tests for that', {
- resumeSessionId: previousSession.sessionId
-})
-```
-
-
-
-### start
-
-Run a prompt without waiting for completion. Returns the session ID immediately so you can subscribe to events.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `prompt` | `string` | ✓ | The instruction/prompt to send |
-| `options` | `RunOptions` |  | Session configuration overrides |
-
-`RunOptions` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `model` | `string` | Override model for this session. |
-| `cwd` | `string` | Override working directory. |
-| `systemPrompt` | `string` | System prompt for this session. |
-| `appendSystemPrompt` | `string` | Append system prompt for this session. |
-| `permissionMode` | `'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk'` | Permission mode override. |
-| `allowedTools` | `string[]` | Allowed tools override. |
-| `disallowedTools` | `string[]` | Disallowed tools override. |
-| `streaming` | `boolean` | Whether to stream partial messages. |
-| `resumeSessionId` | `string` | Resume a previous session by ID. |
-| `continue` | `boolean` | Continue the most recent conversation. |
-| `addDirs` | `string[]` | Additional directories to allow tool access to. |
-| `skillsFolders` | `string[]` | Directories containing Claude Code skills (SKILL.md files) to load into sessions. Merged with addDirs as --add-dir. |
-| `mcpConfig` | `string[]` | MCP config file paths. |
-| `mcpServers` | `Record<string, McpServerConfig>` | MCP servers to inject, keyed by server name. |
-| `dangerouslySkipPermissions` | `boolean` | Skip all permission checks (only for sandboxed environments). |
-| `extraArgs` | `string[]` | Additional arbitrary CLI flags. |
-| `fileLogPath` | `string` | Path to write a parseable NDJSON session log file. Overrides feature-level fileLogPath. |
-| `fileLogLevel` | `FileLogLevel` | Verbosity level for file logging. Overrides feature-level fileLogLevel. |
-| `effort` | `'low' | 'medium' | 'high'` | Effort level for Claude reasoning. |
-| `maxBudgetUsd` | `number` | Maximum cost budget in USD. |
-| `fallbackModel` | `string` | Fallback model when the primary is unavailable. |
-| `jsonSchema` | `string | object` | JSON schema for structured output validation. |
-| `agent` | `string` | Agent to use for this session. |
-| `sessionId` | `string` | Resume or fork a specific Claude session by ID. |
-| `noSessionPersistence` | `boolean` | Disable session persistence for this run. |
-| `forkSession` | `boolean` | Fork from an existing session instead of resuming. |
-| `tools` | `string[]` | Tools to make available. |
-| `strictMcpConfig` | `boolean` | Require strict MCP config validation. |
-| `debug` | `string | boolean` | Enable debug output. Pass a string for specific debug channels, or true for all. |
-| `debugFile` | `string` | Path to write debug output to a file. |
-| `settingsFile` | `string` | Path to a custom settings file. |
-| `chrome` | `boolean` | Launch Claude Code with a Chrome browser tool. |
-
-**Returns:** `Promise<string>`
-
-```ts
-const sessionId = cc.start('Build a REST API for users')
-
-cc.on('session:delta', ({ sessionId: sid, text }) => {
- if (sid === sessionId) process.stdout.write(text)
-})
-
-cc.on('session:result', ({ sessionId: sid, result }) => {
- if (sid === sessionId) console.log('\nDone:', result)
-})
-```
-
-
-
-### abort
-
-Kill a running session's subprocess.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `sessionId` | `string` | ✓ | The local session ID to abort |
-
-**Returns:** `void`
-
-```ts
-const sessionId = cc.start('Do something long')
-// ... later
-cc.abort(sessionId)
-```
-
-
-
-### getSession
-
-Get a session by its local ID.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `sessionId` | `string` | ✓ | The local session ID |
-
-**Returns:** `ClaudeSession | undefined`
-
-```ts
-const session = cc.getSession(sessionId)
-if (session?.status === 'completed') {
- console.log(session.result)
-}
-```
-
-
-
-### waitForSession
-
-Wait for a running session to complete.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `sessionId` | `string` | ✓ | The local session ID |
-
-**Returns:** `Promise<ClaudeSession>`
-
-```ts
-const id = cc.start('Build something cool')
-const session = await cc.waitForSession(id)
-console.log(session.result)
-```
-
-
-
-### usage
-
-Get aggregated usage statistics across all sessions, or for a specific session.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `sessionId` | `string` |  | Optional session ID to get usage for a single session |
-
-**Returns:** `{ totalCostUsd: number; totalInputTokens: number; totalOutputTokens: number; totalCacheReadTokens: number; totalCacheCreationTokens: number; totalTurns: number; sessionCount: number; sessions: Array<{ id: string; costUsd: number; turns: number; inputTokens: number; outputTokens: number; status: string`
-
-```ts
-const stats = cc.usage()
-console.log(`Total cost: $${stats.totalCostUsd.toFixed(4)}`)
-console.log(`Tokens: ${stats.totalInputTokens} in / ${stats.totalOutputTokens} out`)
-
-// Single session
-const sessionStats = cc.usage(sessionId)
-```
-
-
-
-### sessionHistoryToMarkdown
-
-Export session history as a readable markdown document. Reads from a raw JSONL file (Claude CLI session log or this feature's NDJSON log) so it works independently of in-memory state. Can also accept a local session ID to export from in-memory state as a fallback.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `source` | `string` |  | Path to a JSONL file, a local session ID, or omit for the most recent session |
-
-**Returns:** `Promise<string>`
-
-```ts
-// From a JSONL file (works without any prior state)
-const md = await cc.sessionHistoryToMarkdown('/path/to/session.jsonl')
-
-// From the most recent in-memory session
-const md = await cc.sessionHistoryToMarkdown()
-
-// From a specific local session ID
-const md = await cc.sessionHistoryToMarkdown(localSessionId)
-```
-
-
-
-### listProcessSessions
-
-List all Claude Code processes currently registered in ~/.claude/sessions/. Returns each session's metadata along with whether the process is still alive.
-
-**Returns:** `Promise<Array<{
-    pid: number
-    sessionId: string
-    cwd: string
-    startedAt: number
-    kind: string
-    entrypoint: string
-    alive: boolean
-  }>>`
-
-```ts
-const sessions = await cc.listProcessSessions()
-for (const s of sessions) {
- console.log(`[${s.alive ? 'LIVE' : 'dead'}] PID ${s.pid} in ${s.cwd}`)
-}
-```
-
-
-
-### getProcessSession
-
-Read a single process session by PID from ~/.claude/sessions/<pid>.json.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `pid` | `number` | ✓ | The process ID |
-
-**Returns:** `Promise<{
-    pid: number
-    sessionId: string
-    cwd: string
-    startedAt: number
-    kind: string
-    entrypoint: string
-  } | null>`
-
-```ts
-const session = await cc.getProcessSession(12345)
-console.log(session?.cwd)
-```
-
-
-
-### getConversationHistory
-
-Read the conversation history for a Claude Code session from its JSONL file in ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl. Returns an array of parsed message objects (user, assistant, tool_use, tool_result).
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `sessionId` | `string` | ✓ | The Claude CLI session ID (from listProcessSessions or getProcessSession) |
-| `cwd` | `string` |  | The working directory of the session (used to locate the project folder) |
-
-**Returns:** `Promise<any[]>`
-
-```ts
-const sessions = await cc.listProcessSessions()
-const s = sessions[0]
-const history = await cc.getConversationHistory(s.sessionId, s.cwd)
-console.log(history.length, 'turns')
-```
-
-
-
-### listSessionsForCwd
-
-List all conversation sessions stored for a given working directory. Reads ~/.claude/projects/<encoded-cwd>/ and returns metadata for each .jsonl file.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `cwd` | `string` |  | The working directory path to look up |
-
-**Returns:** `Promise<Array<{
-    sessionId: string
-    filePath: string
-    messageCount: number
-  }>>`
-
-```ts
-const sessions = await cc.listSessionsForCwd('/Users/me/my-project')
-for (const s of sessions) {
- console.log(s.sessionId, s.messageCount, 'messages')
-}
-```
-
-
-
-### cleanupMcpTempFiles
-
-Clean up any temp MCP config files created during sessions.
-
-**Returns:** `Promise<void>`
-
-
-
-### enable
-
-Initialize the feature.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `options` | `any` |  | Enable options |
-
-**Returns:** `Promise<this>`
-
-
-
-## Getters
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `claudePath` | `string` |  |
-| `parsedVersion` | `{ major: number; minor: number; patch: number } | undefined` | Parsed semver components from the detected CLI version, or undefined if not yet checked. |
-| `sessionId` | `string | undefined` | The Claude CLI session ID of the most recently initialized session, or the session set via the `session` option. Useful for resuming later. |
-
-## Events (Zod v4 schema)
-
-### session:warning
-
-Fired when the log reader encounters a warning
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `sessionId` | `string` |  |
-| `message` | `string` |  |
-
-
-
-### session:log-error
-
-Fired when the log reader encounters an error
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `sessionId` | `string` |  |
-| `error` | `any` |  |
-
-
-
-### session:event
-
-Fired for every parsed JSON event from the CLI stream
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `sessionId` | `string` |  |
-| `event` | `any` |  |
-
-
-
-### session:init
-
-Fired when the CLI emits its init system event
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `sessionId` | `string` |  |
-| `init` | `any` |  |
-
-
-
-### session:delta
-
-Fired for each text delta from an assistant message
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `sessionId` | `string` |  |
-| `text` | `string` |  |
-| `role` | `string` |  |
-
-
-
-### session:stream
-
-Fired for stream_event type events from the CLI
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `sessionId` | `string` |  |
-| `streamEvent` | `any` |  |
-
-
-
-### session:message
-
-Fired when a complete assistant message is received
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `sessionId` | `string` |  |
-| `message` | `any` |  |
-
-
-
-### session:result
-
-Fired when a session completes with a final result
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `sessionId` | `string` |  |
-| `result` | `string` |  |
-
-
-
-### session:start
-
-Fired when a new Claude Code session is spawned
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `sessionId` | `string` |  |
-| `prompt` | `string` |  |
-
-
-
-### session:error
-
-Fired when a session encounters an error
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `sessionId` | `string` |  |
-| `error` | `any` |  |
-| `exitCode` | `number` |  |
-
-
-
-### session:parse-error
-
-Fired when a JSON line from the CLI cannot be parsed
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `sessionId` | `string` |  |
-| `line` | `string` |  |
-
-
-
-### session:abort
-
-Fired when a session is aborted by the user
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `sessionId` | `string` |  |
-
-
-
-## State (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `enabled` | `boolean` | Whether this feature is currently enabled |
-| `sessions` | `object` | Map of session IDs to ClaudeSession objects |
-| `activeSessions` | `array` | List of currently running session IDs |
-| `claudeAvailable` | `boolean` | Whether the Claude CLI binary is available |
-| `claudeVersion` | `string` | Detected Claude CLI version string |
-
-## Environment Variables
-
-- `TMPDIR`
-
-## Examples
-
-**features.claudeCode**
-
-```ts
-const cc = container.feature('claudeCode')
-
-// Listen for events
-cc.on('session:delta', ({ sessionId, text }) => process.stdout.write(text))
-cc.on('session:result', ({ sessionId, result }) => console.log('Done:', result))
-
-// Run a prompt
-const session = await cc.run('Explain the architecture of this project')
-console.log(session.result)
-```
-
-
-
-**checkAvailability**
-
-```ts
-const available = await cc.checkAvailability()
-if (!available) throw new Error('Claude CLI not found')
-```
-
-
-
-**writeMcpConfig**
-
-```ts
-const configPath = await cc.writeMcpConfig({
- 'my-api': { type: 'http', url: 'https://api.example.com/mcp' },
- 'local-tool': { type: 'stdio', command: 'bun', args: ['run', 'server.ts'] }
-})
-```
-
-
-
-**run**
-
-```ts
-// Simple one-shot
-const session = await cc.run('What files are in this project?')
-console.log(session.result)
-
-// With options
-const session = await cc.run('Refactor the auth module', {
- model: 'opus',
- cwd: '/path/to/project',
- permissionMode: 'acceptEdits',
- streaming: true
-})
-
-// With injected MCP servers
-const session = await cc.run('Use the database tools to list tables', {
- mcpServers: {
-   'db-tools': { type: 'stdio', command: 'bun', args: ['run', 'db-mcp.ts'] },
-   'api': { type: 'http', url: 'https://api.example.com/mcp' }
- }
-})
-
-// Resume a previous session
-const session = await cc.run('Now add tests for that', {
- resumeSessionId: previousSession.sessionId
-})
-```
-
-
-
-**start**
-
-```ts
-const sessionId = cc.start('Build a REST API for users')
-
-cc.on('session:delta', ({ sessionId: sid, text }) => {
- if (sid === sessionId) process.stdout.write(text)
-})
-
-cc.on('session:result', ({ sessionId: sid, result }) => {
- if (sid === sessionId) console.log('\nDone:', result)
-})
-```
-
-
-
-**abort**
-
-```ts
-const sessionId = cc.start('Do something long')
-// ... later
-cc.abort(sessionId)
-```
-
-
-
-**getSession**
-
-```ts
-const session = cc.getSession(sessionId)
-if (session?.status === 'completed') {
- console.log(session.result)
-}
-```
-
-
-
-**waitForSession**
-
-```ts
-const id = cc.start('Build something cool')
-const session = await cc.waitForSession(id)
-console.log(session.result)
-```
-
-
-
-**usage**
-
-```ts
-const stats = cc.usage()
-console.log(`Total cost: $${stats.totalCostUsd.toFixed(4)}`)
-console.log(`Tokens: ${stats.totalInputTokens} in / ${stats.totalOutputTokens} out`)
-
-// Single session
-const sessionStats = cc.usage(sessionId)
-```
-
-
-
-**sessionHistoryToMarkdown**
-
-```ts
-// From a JSONL file (works without any prior state)
-const md = await cc.sessionHistoryToMarkdown('/path/to/session.jsonl')
-
-// From the most recent in-memory session
-const md = await cc.sessionHistoryToMarkdown()
-
-// From a specific local session ID
-const md = await cc.sessionHistoryToMarkdown(localSessionId)
-```
-
-
-
-**listProcessSessions**
-
-```ts
-const sessions = await cc.listProcessSessions()
-for (const s of sessions) {
- console.log(`[${s.alive ? 'LIVE' : 'dead'}] PID ${s.pid} in ${s.cwd}`)
-}
-```
-
-
-
-**getProcessSession**
-
-```ts
-const session = await cc.getProcessSession(12345)
-console.log(session?.cwd)
-```
-
-
-
-**getConversationHistory**
-
-```ts
-const sessions = await cc.listProcessSessions()
-const s = sessions[0]
-const history = await cc.getConversationHistory(s.sessionId, s.cwd)
-console.log(history.length, 'turns')
-```
-
-
-
-**listSessionsForCwd**
-
-```ts
-const sessions = await cc.listSessionsForCwd('/Users/me/my-project')
-for (const s of sessions) {
- console.log(s.sessionId, s.messageCount, 'messages')
-}
-```
-
-
-
-**sessionId**
-
-```ts
-const cc = container.feature('claudeCode')
-await cc.run('Do something')
-console.log(cc.sessionId) // the Claude CLI session ID
-```
-