Runtime Walkthrough
End-to-end runtime timeline from task input to plan output.
This walkthrough traces a single task from initial capture through file discovery, plan generation, and terminal execution. Each stage maps to specific job types and produces artifacts stored in SQLite.
High-level runtime sequence
- 1.User enters or dictates a task description in the desktop UI via TaskDescriptionEditor component.
- 2.Optional: text_improvement job refines the raw input through TextImprovementProcessor.
- 3.User triggers file discovery workflow via the Implementation Plans panel start_file_finder_workflow command.
- 4.WorkflowOrchestrator in desktop/src-tauri/src/jobs/workflow_orchestrator/ creates a workflow record and schedules stage 1.
- 5.Stage 1 (root_folder_selection): RootFolderSelectionProcessor sends directory tree to LLM, stores selected roots in IntermediateData.selectedRoots.
- 6.Stage 2 (regex_file_filter): RegexFileFilterProcessor generates patterns, runs git ls-files, stores matches in IntermediateData.locallyFilteredFiles.
- 7.Stage 3 (file_relevance_assessment): FileRelevanceAssessmentProcessor chunks file contents, scores relevance, stores in IntermediateData.aiFilteredFiles.
- 8.Stage 4 (extended_path_finder): ExtendedPathFinderProcessor expands context with imports and dependencies, stores in IntermediateData.verifiedPaths.
- 9.UI receives workflow-completed event via event_emitter.rs, updates file selection display.
- 10.User triggers plan generation with selected files via generate_implementation_plan command.
- 11.ImplementationPlanProcessor in desktop/src-tauri/src/jobs/processors/implementation_plan_processor.rs streams XML plan content to Monaco viewer via job:stream-progress events.
- 12.User reviews plan in VirtualizedCodeViewer component, can edit directly or request merge.
- 13.Approved plan is copied to terminal via copy-button templates or exported for external agents.
- 14.Terminal session in terminal_commands.rs captures PTY output, detects agent attention states.
- 15.All artifacts persist in SQLite background_jobs and terminal_sessions tables for audit and session recovery.
Runtime timeline
Visual timeline showing task input, workflow stages, and plan output.
Job type mapping
- text_improvement → TextImprovementProcessor → refined task descriptions
- root_folder_selection → RootFolderSelectionProcessor → selected directories
- regex_file_filter → RegexFileFilterProcessor → pattern-matched files
- file_relevance_assessment → FileRelevanceAssessmentProcessor → scored files
- extended_path_finder → ExtendedPathFinderProcessor → expanded context
- implementation_plan → ImplementationPlanProcessor → XML plan documents
- implementation_plan_merge → ImplementationPlanMergeProcessor → merged plans
Task input capture
Tasks enter the system through multiple input surfaces: typed text in TaskDescriptionEditor, voice dictation via useVoiceTranscription hook, or video analysis through VideoAnalysisDialog.
Each input type produces artifacts stored in SQLite - task_description in sessions table, transcription results in background_jobs, and video frames in associated job metadata.
Input refinement
The text_improvement job type refines raw input through TextImprovementProcessor, wrapping text in XML and sending to the LLM for grammar, clarity, and structure improvements.
Refined text is stored in background_jobs.response and can update sessions.task_description via the React provider.
File discovery workflow
FileFinderWorkflow runs four sequential stages: root_folder_selection narrows directories, regex_file_filter applies patterns, file_relevance_assessment scores content, and extended_path_finder expands with dependencies.
Each stage stores results in IntermediateData structures passed between processors, with final file selections persisted to sessions.included_files.
Plan generation
The implementation_plan job type uses ImplementationPlanProcessor to generate XML-formatted plans with plan_step elements containing file paths, operation types, and code changes.
Plan content streams to the UI via job:stream-progress Tauri events, displayed in the VirtualizedCodeViewer Monaco component with syntax highlighting.
Plan merging
The implementation_plan_merge job combines multiple plans using source_plans XML tags and user-provided merge instructions to resolve conflicts and consolidate changes.
Merged plans maintain traceability to source plans and include merged_from metadata in the final background_jobs record.
Plan review
Plans open in the Monaco-based VirtualizedCodeViewer for review. Users can edit plan text directly, request modifications, or approve for execution.
All review actions are logged with timestamps and user context, providing an audit trail of plan evolution.
Execution handoff
Approved plans are copied to the integrated terminal via copy-button templates, or exported for external agents like Claude Code, Cursor, or Codex.
Terminal sessions in terminal_commands.rs capture PTY output, detect agent attention states, and log all execution activity to terminal_sessions table.
State persistence
All job artifacts persist in background_jobs table with session_id, task_type, status, prompt, response, token counts, and cost tracking.
On app restart, the Rust core rehydrates session state from SQLite, marks stale running jobs as failed, and restores terminal output logs.
Explore the architecture
Understand how the components fit together in detail.