kesteva/cyboflow

Purpose and entry points

Cyboflow is a self-contained macOS Electron desktop application for orchestrating multi-agent software workflows over local Git repositories. It supports built-in Planner, Sprint, Compound, Ship, verification setup, custom workflows, and ad-hoc sessions. Electron starts in main/src/index.ts; the privileged bridge is main/src/preload.ts; the React renderer starts at frontend/src/main.tsx and renders from frontend/src/App.tsx.

Desktop boundary and API surface

The renderer does not directly own filesystem, processes, Git, or persistence. It calls typed APIs through Electron IPC and tRPC: IPC registration/handlers live in main/src/ipc/index.ts and main/src/ipc/cyboflow.ts; the orchestrator-facing RPC router is main/src/orchestrator/trpc/router.ts, with renderer client wiring in frontend/src/trpc/client.ts. This is the primary trust boundary between UI and local-machine capabilities.

Workflow orchestration

main/src/orchestrator/Orchestrator.ts is the central application coordinator. It launches, resumes, pauses, retries, rewinds, cancels, and recovers runs; main/src/orchestrator/runLauncher.ts and main/src/orchestrator/runExecutor.ts drive execution. Workflow definitions, built-in bundles, agents, and prompt rendering are represented by main/src/orchestrator/workflowRegistry.ts, main/src/orchestrator/workflows/workflowBundle.ts, and main/src/orchestrator/workflowPromptRenderer.ts. Runs can use programmatic DAG-like control and human/visual gates via main/src/orchestrator/programmatic/workflowController.ts.

Agent execution substrates and event ingestion

Each isolated session can run Claude Code through SDK/chat or interactive PTY paths. Substrate selection/dispatch is handled by main/src/services/substrateDispatchFacade.ts; Claude process management is in main/src/services/panels/claude/claudeCodeManager.ts; Codex SDK/PTY support exists in main/src/services/panels/codex/codexSdkManager.ts and main/src/services/panels/codex/codexPtyManager.ts. Provider stream events are normalized, persisted/projected, and routed to orchestration/UI through main/src/services/streamParser/eventRouter.ts, main/src/services/streamParser/messageProjection.ts, and main/src/orchestrator/runEventBridge.ts.

State, isolation, and local infrastructure

SQLite is the durable system of record, with schema/migration evolution in main/src/database/database.ts, main/src/database/schema.sql, and main/src/database/migrations/. It stores projects, sessions, runs, workflow steps, tasks, review items, artifacts, usage, experiments, and integrations. Git worktrees isolate parallel work through main/src/services/worktreeManager.ts; Git status/diffs are managed by main/src/services/gitStatusManager.ts and main/src/services/gitDiffManager.ts. Terminal/PTY lifecycle is managed in main/src/services/terminalSessionManager.ts.

Human control, review, and verification

Agent permissions, questions, approvals, and review items are first-class workflow gates. Core routing/bridges reside in main/src/orchestrator/approvalRouter.ts, main/src/orchestrator/questionRouter.ts, and main/src/orchestrator/reviewItemRouter.ts. The renderer’s central operational surfaces include frontend/src/components/ReviewQueueView.tsx and frontend/src/components/cyboflow/RunView.tsx. Verification is a separate scheduling pipeline with runbook, snapshot, dependency, agent, and verdict stages in main/src/orchestrator/verify/verificationScheduler.ts, main/src/orchestrator/verify/runbookStore.ts, and main/src/orchestrator/verify/verdictDelivery.ts.

Renderer composition and integrations

The React UI is state-store driven; workflow/run/session state centers on frontend/src/stores/cyboflowStore.ts, frontend/src/stores/sessionStore.ts, and frontend/src/stores/workflowsStore.ts. The Cyboflow workspace root and workflow editor are frontend/src/components/cyboflow/CyboflowRoot.tsx and frontend/src/components/cyboflow/WorkflowEditorModal.tsx; task planning is surfaced through frontend/src/components/BacklogPane.tsx. External/local integrations include Claude Code, Codex runtimes, MCP via main/src/orchestrator/mcpServer/cyboflowMcpServer.ts, Linear and Plane tracker sync via main/src/services/trackerSync/trackerSyncService.ts, visual verification using Playwright/Peekaboo adapters, and Electron auto-updates via main/src/services/appUpdater.ts.