add documentation
This commit is contained in:
Osman Mehmood
77
docs-site/docs/workflows.md
Normal file
77
docs-site/docs/workflows.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# End-to-end workflows
|
||||
|
||||
!!! warning "Recovered source"
|
||||
Behavior described here is inferred from `src/`; the shipping product may differ by version or build flags.
|
||||
|
||||
## Interactive terminal session
|
||||
|
||||
1. **Process start** — `main.tsx` evaluates side-effect imports (profiler, MDM, keychain prefetch), then parses argv with Commander.
|
||||
2. **`preAction` hook** — Trust dialog state, global config, remote-managed settings, policy limits, GrowthBook/feature flags, OAuth/API key paths, MCP official registry prefetch, plugin initialization, and similar steps run before the subcommand handler.
|
||||
3. **REPL launch** — `replLauncher.tsx` creates the Ink root and renders providers (`AppState`, keybindings, MCP manager, etc.) and mounts `screens/REPL.tsx`.
|
||||
4. **Input** — User typing, paste, voice (if `VOICE_MODE`), teammate messages, and task notifications enqueue work.
|
||||
5. **Queue** — `utils/queueProcessor.ts` dequeues slash commands and bash lines individually; batches other same-mode items and calls `executeInput`.
|
||||
6. **Query** — `query.ts` `queryLoop` streams model output, schedules tool calls, applies permission checks, and updates transcript state.
|
||||
7. **Tools** — `services/tools/toolExecution.ts` / `StreamingToolExecutor` and per-tool modules under `tools/*` perform filesystem, shell, web, MCP, and agent operations.
|
||||
8. **Compaction** — When context limits approach, `services/compact/*` reduces history per compaction policy.
|
||||
|
||||
**Official parallels:** [Interactive mode](https://code.claude.com/docs/en/interactive-mode), [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works).
|
||||
|
||||
## Print mode / stream-json / programmatic control
|
||||
|
||||
1. **Routing** — `main.tsx` selects the print/headless path instead of the full REPL when `-p` / related flags are used.
|
||||
2. **Structured I/O** — `cli/structuredIO.ts` parses lines into typed events; `cli/print.ts` `runHeadlessStreaming` runs the async loop that consumes user/control messages and emits stdout messages.
|
||||
3. **Engine** — `QueryEngine.submitMessage` builds `processUserInputContext` for non-interactive sessions and streams SDK-style messages.
|
||||
|
||||
**Official parallels:** [Run Claude Code programmatically](https://code.claude.com/docs/en/headless), [Agent SDK overview](https://platform.claude.com/docs/en/agent-sdk/overview) (external platform docs).
|
||||
|
||||
## Teammates / agent teams
|
||||
|
||||
1. **Spawn** — Swarm backends (`utils/swarm/backends/*`) create tmux panes, iTerm panes, or in-process runners.
|
||||
2. **Teammate loop** — `utils/swarm/inProcessRunner.ts` runs a `while` loop: build prompt messages, check compaction/token limits, call into shared query/tool paths, sync permissions via `leaderPermissionBridge`, etc.
|
||||
3. **REPL integration** — `REPL.tsx` wires `useInboxPoller`, `useMailboxBridge`, and `handleIncomingPrompt` so teammate messages become user turns.
|
||||
|
||||
**Official parallels:** [Agent teams](https://code.claude.com/docs/en/agent-teams), [Subagents](https://code.claude.com/docs/en/sub-agents).
|
||||
|
||||
## Hooks (user-configured)
|
||||
|
||||
1. **Session start** — `utils/sessionStart.ts` `processSessionStartHooks` / `processSetupHooks` run after configuration is known; wired from startup paths in `main.tsx` and related modules.
|
||||
2. **Per-event hooks** — Additional hook types align with the schema described in the official [Hooks reference](https://code.claude.com/docs/en/hooks); implementation is spread across hook runners and tool lifecycle code.
|
||||
|
||||
**Official parallels:** [Hooks guide](https://code.claude.com/docs/en/hooks-guide), [Hooks reference](https://code.claude.com/docs/en/hooks).
|
||||
|
||||
## Compaction and context
|
||||
|
||||
1. **Triggers** — Token estimation and session memory modules decide when to compact.
|
||||
2. **Pipeline** — `services/compact/compact.ts`, `autoCompact.ts`, `microCompact.ts`, and related files rewrite or summarize message history.
|
||||
3. **Post-compact** — Cleanup hooks update UI and storage.
|
||||
|
||||
**Official parallels:** [Context window](https://code.claude.com/docs/en/context-window), [Checkpointing](https://code.claude.com/docs/en/checkpointing), [Costs](https://code.claude.com/docs/en/costs).
|
||||
|
||||
## MCP and external tools
|
||||
|
||||
1. **Config** — `services/mcp/config.ts`, env expansion, enterprise allowlists.
|
||||
2. **Connection** — `MCPConnectionManager.tsx`, stdio and SDK transports.
|
||||
3. **Tool surface** — `tools/MCPTool`, `ReadMcpResourceTool`, `ListMcpResourcesTool`, `McpAuthTool`.
|
||||
|
||||
**Official parallels:** [MCP](https://code.claude.com/docs/en/mcp), [Channels](https://code.claude.com/docs/en/channels).
|
||||
|
||||
## Optional sequence (interactive turn)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant REPL as REPL.tsx
|
||||
participant Queue as queueProcessor
|
||||
participant Query as queryLoop
|
||||
participant API as services/api
|
||||
participant Tool as tools/*
|
||||
User->>REPL: input / slash command
|
||||
REPL->>Queue: enqueue
|
||||
Queue->>REPL: executeInput
|
||||
REPL->>Query: onQuery messages
|
||||
Query->>API: stream completion
|
||||
API-->>Query: tool_use
|
||||
Query->>Tool: execute
|
||||
Tool-->>Query: result
|
||||
Query-->>REPL: update transcript
|
||||
```
|
||||
Reference in New Issue
Block a user