crystal

Manages multiple concurrent AI coding sessions (Claude Code and OpenAI Codex) running in parallel on the same repository by automatically creating isolated Git worktrees for each session. Uses Electron's multi-process architecture (main process handles SessionManager and WorktreeManager services) with IPC-based coordination to prevent file conflicts and state collisions. Each session maintains its own filesystem context while sharing the parent repository metadata.

Enables multiple independent AI conversation threads (panels) to run concurrently within a single session context, each maintaining separate conversation history and state. The Panel System Architecture routes AI requests through a unified interface that dispatches to Claude or Codex APIs while maintaining panel-specific context windows and conversation state in the database layer. Panels share the same worktree filesystem but maintain isolated conversation threads.

Implements a publish-subscribe event system that emits state changes from backend services (SessionManager, WorktreeManager, DatabaseService) to the UI renderer process. Services emit typed events when state changes (e.g., session created, file modified, command executed), and the renderer subscribes to these events to update the UI reactively. Events are routed through IPC, enabling real-time UI updates without polling.

Provides a workflow for creating new AI sessions with configurable parameters (model selection, system prompts, branch/worktree settings). The Session Creation and Configuration subsystem validates inputs, initializes a new session record in the database, creates an associated Git worktree, and sets up initial panel contexts. Users can configure per-session settings like AI model (Claude vs Codex), temperature, max tokens, and custom system prompts.

Organizes multiple sessions within projects using a hierarchical UI structure. Projects group related sessions, and sessions contain multiple panels for different conversation threads. The Navigation and Layout subsystem renders a sidebar with project/session/panel hierarchy, enabling quick switching between contexts. Session metadata (creation time, model, status) is displayed in the UI for easy identification.

Manages application-wide settings (API keys, default models, UI preferences) through a ConfigManager service that persists settings to disk. Settings include API credentials for Claude and Codex, default AI model selection, UI theme, and logging level. Settings are loaded on application startup and can be modified through a settings UI panel. Sensitive settings (API keys) are stored securely using OS-level credential storage when available.

Provides file read/write operations within worktrees through IPC-based file access APIs. The File Operations and IPC subsystem exposes file operations (read, write, delete, list directory) through the preload script, allowing the renderer to request file operations from the main process. File operations are scoped to the active worktree, preventing access outside the session context. All file I/O is handled by the main process, maintaining security boundaries.

Integrates Claude Code CLI (≥2.0.0) as a native AI backend with real-time streaming output rendering in the UI. The Claude Integration layer in the main process spawns Claude Code CLI as a child process, captures streaming responses via PTY (pseudo-terminal) management, and pipes structured output to the renderer process via IPC. AI Output Rendering components parse and display Claude's responses with syntax highlighting and interactive code blocks.

Integrates OpenAI Codex as an alternative AI backend using REST API calls, with request/response handling managed by the main process and rendered in the UI. The Codex Integration layer constructs API requests with code context from the worktree, sends them to OpenAI's API, and streams responses back to the renderer via IPC. Unlike Claude Code CLI integration, Codex integration is API-first without subprocess management.

Automatically creates, manages, and cleans up Git worktrees for each session using the WorktreeManager service. When a session is created, WorktreeManager spawns a new worktree from the parent repository, assigns it a unique filesystem path, and tracks its lifecycle in the database. On session deletion, the worktree is pruned and its filesystem is cleaned up. Worktree state is monitored via file watching and Git status polling.

Monitors Git status in real-time for each worktree using file watching and Git status polling, then renders diffs visually in the UI. The Git Status and File Watching subsystem watches the worktree filesystem for changes, polls git status periodically, and emits events via the Event System. The Diff Visualization component parses git diffs and renders them with syntax highlighting, showing added/removed/modified lines with context.

Records the execution history of each AI session (prompts, responses, file changes, commands executed) in the SQLite database and enables replay/review of past interactions. The Diff Visualization and Execution History subsystem logs each AI interaction with timestamps, model used, and resulting file modifications. Users can browse historical sessions, view what prompts led to which outputs, and understand the evolution of changes over time.

Manages pseudo-terminal (PTY) instances for executing commands within worktrees, enabling interactive terminal sessions and real-time output streaming. The Terminal and PTY Management subsystem spawns PTY processes for each session, handles stdin/stdout/stderr streams, and pipes output to the UI via IPC. Supports both Claude Code CLI subprocess execution and general command execution within the worktree context.

Implements secure IPC between Electron's main process (backend services) and renderer process (UI) using Electron's contextBridge and preload script. The preload script (main/src/preload.ts) exposes a typed API surface that allows the renderer to invoke main process services (SessionManager, WorktreeManager, DatabaseService) without direct access to Node.js APIs. All IPC calls are routed through the preload bridge, enforcing security boundaries.

Persists all session metadata, conversation history, execution logs, and configuration in a SQLite database managed by the DatabaseService. The database schema stores sessions, panels, worktree metadata, AI interactions, and file change history. State changes are persisted immediately to the database, enabling recovery of session state across application restarts. The Event System emits database change events to keep the UI in sync.