Process Management
Relevant source files
The following files were used as context for generating this wiki page:
Process Management in Opcode is the system responsible for spawning, tracking, and communicating with external claude CLI subprocesses. It bridges the gap between the graphical user interface (GUI) and the underlying command-line tool, enabling real-time streaming of AI responses, command execution, and session isolation. Sources: web_server.design.md, src-tauri/src/commands/agents.rs:563-583
The architecture supports dual-mode operation: a desktop mode powered by Tauri and a web server mode using Axum. In both environments, the system manages process lifecycles, handles input/output (I/O) streaming via standard pipes (stdout/stderr) or WebSockets, and maintains a registry of active sessions to prevent process leakage. Sources: web_server.design.md, src-tauri/src/main.rs:136-137
Architecture and Subprocess Spawning
Opcode interacts with the claude binary by spawning it as a subprocess with specific arguments. The system uses a dedicated registry to maintain state for every running process, including its process ID (PID), project path, and associated task. Sources: src-tauri/src/commands/agents.rs:608-615, src/lib/api.ts:14-22
Process Execution Flow
The following diagram illustrates the sequence from a user prompt to the execution of a subprocess.
Process Configuration
When spawning a process, the system injects environment variables and command-line flags to ensure consistent behavior across different platforms (macOS, Linux, Windows). Key arguments include --system-prompt, --model, and --output-format stream-json. Sources: src-tauri/src/commands/agents.rs:589-601, src-tauri/src/commands/agents.rs:913-948
| Argument | Description | Source |
|---|---|---|
-p [task] | The user-provided task or prompt for the agent. | agents.rs:591 |
--system-prompt | Custom instructions defining the agent's persona. | agents.rs:593 |
--model | Specifies the Claude model (e.g., sonnet, opus). | agents.rs:595 |
--output-format | Forces JSONL output for easier parsing. | agents.rs:597 |
--dangerously-skip-permissions | Used in web/agent modes to bypass interactive prompts. | agents.rs:600 |
Process Registry and Lifecycle
The ProcessRegistryState is a global state object managed by the Tauri application. It tracks all agent_runs and ClaudeSession processes currently active on the system. Sources: src-tauri/src/main.rs:136-137, src/lib/api.ts:4-12
Monitoring and Cleanup
The system provides a cleanup mechanism to verify if processes are still alive. This is particularly important for detecting crashes or unexpected terminations. On Unix-like systems, this is performed via kill -0, while on Windows, tasklist is queried. Sources: src-tauri/src/commands/agents.rs:855-885
Cancellation Flow
Processes can be terminated by the user through the UI. The cancellation logic first attempts to kill the process via the registry; if that fails, it uses the PID stored in the database as a fallback. Sources: src-tauri/src/commands/agents.rs:813-840, web_server.design.md
Stream Processing and I/O Handling
Opcode captures the stdout and stderr of the Claude process to provide a real-time terminal-like experience in the GUI. Sources: src-tauri/src/commands/agents.rs:624-640
Output Processing Logic
- Stdout Capture: Lines are read asynchronously using
TokioBufReader. Sources: src-tauri/src/commands/agents.rs:645-650 - Session ID Extraction: The system parses the first few lines of output to extract the unique
session_idgenerated by Claude Code, which is then used to locate logs in~/.claude/projects/. Sources: src-tauri/src/commands/agents.rs:683-718 - Event Dispatching: Captured output is emitted to the frontend using scoped events (e.g.,
agent-output:{run_id}) to ensure that multiple concurrent sessions do not interfere with each other. Sources: src-tauri/src/commands/agents.rs:727-729, web_server.design.md
Error Handling
The stderr pipe is monitored specifically for execution errors. Any line received on this pipe is emitted as an agent-error event, triggering error states in the frontend components. Sources: src-tauri/src/commands/agents.rs:745-758, src/components/ClaudeCodeSession.tsx:422-428
API Integration
The frontend interacts with process management through a set of API calls defined in api.ts and facilitated by apiAdapter.ts. Sources: src/lib/api.ts, src/lib/apiAdapter.ts
| Command | Endpoint (Web) | Description |
|---|---|---|
execute_agent | /api/agents/{agentId}/execute | Launches a new autonomous agent process. |
kill_agent_session | /api/agents/sessions/{runId}/kill | Terminates a running agent process. |
get_live_session_output | /api/agents/sessions/{runId}/output/live | Retrieves currently buffered stdout. |
cancel_claude_execution | /api/sessions/{sessionId}/cancel | Stops an interactive Claude session. |
Sources: src/lib/apiAdapter.ts:145-165, src/lib/api.ts:515-540
Conclusion
Process Management in Opcode provides a robust abstraction for subprocess orchestration. By combining a global registry with asynchronous I/O streaming and cross-platform cleanup logic, the system ensures that CLI-based AI tools can be seamlessly integrated into a visual, multi-session application environment without compromising session isolation or system stability. Sources: web_server.design.md, src-tauri/src/commands/agents.rs:887-892