FlexCrew

Purpose

FlexCrew is a model-agnostic coding agent and desktop execution environment built with LangChain JS and LangGraph JS. It ships as both a full-screen terminal CLI (Ink + React TUI) and a desktop application (Electron + React 19 + Tailwind CSS) that share a unified agent core, tool registry, and SQLite session store.

The project is built around the philosophy: “Your models. Your tools. Your crew.” It allows developers to pair with frontier commercial models (Anthropic Claude, OpenAI, Google Gemini) or private local models (Ollama, LM Studio, vLLM) across specialized workspaces for host shell coding, VM-isolated deliverables, visual design, browser data extraction, and scheduled background tasks.

Why I Built This

Coding with AI agents has historically been divided into two disconnected extremes:

1. Vendor-locked terminal tools: Tools like Claude Code provide fast terminal workflows, but they lock developers into a single API vendor, lack visual workspaces for documents and design, and cannot easily run isolated jobs or recurring automations.
2. Desktop chat interfaces: Standard GUI assistants cannot reliably manipulate local files, execute terminal builds, manage git workflows, or guarantee safe rollbacks when generating complex multi-file patches.
3. Execution safety and sandbox gaps: Autonomous agents running shell commands on the host machine risk accidental data loss without strict permission policies, checkpointing, and isolated execution options.

I built FlexCrew to unify terminal velocity and desktop flexibility into a single modular engine. Developers get a terminal TUI for keyboard-driven terminal workflows, alongside an Electron desktop app with dedicated workspaces for software engineering, containerized coworking, visual vector canvas design, and automated background jobs.

Monorepo Architecture

FlexCrew is architected as a modular TypeScript monorepo with clean separation between the headless core runtime, presentation layers, and distributions:

• packages/core: The runtime engine built on top of LangGraph. Manages stateful graph execution (executeGraph), the extensible tool registry, system prompt construction, SQLite database repositories (flexcrew.db), file checkpointing, permission evaluation, and token budget tracking.
• packages/client: Framework-agnostic React hooks (including useAgentTurn), state reducers, and bridge adapters (desktopBridge, vmBridge) that cleanly decouple user interface components from agent domain logic.
• packages/tui: An interactive terminal user interface built with React Ink and the Yoga flexbox layout engine. Operates in an alternate terminal screen buffer with scrollable message streams, live token counters, and interactive approval prompts.
• apps/cli: The terminal command-line binary (flexcrew). Supports full interactive TUI mode, headless interactive REPL, and pipeable one-shot command execution (-p / --print) with structured JSON output for scripts and CI.
• apps/desktop: An Electron desktop application powered by Vite, React 19, and Tailwind CSS. Features multi-mode workspaces, side-chat scratchpads, Monaco code preview, and native background task scheduling.
• apps/marketing: The static marketing website (https://flexcrew.app/) built with Astro, documenting features, architectures, and release instructions.

Desktop Workspaces & Modes

The FlexCrew desktop shell provides purpose-built workspaces tailored for different stages of the development lifecycle:

1. Build Mode (Host Shell Coding):

   • Driven by CodingAgent running directly on the host machine with permission guardrails.
   • Equipped with ripgrep text search, glob file matchers, AST symbol navigation, git branch and staged diff management, and unified patch review (propose_edit / apply_search_replace).
   • Designed for software development, debugging, test writing, and codebase refactoring.

2. Cowork Mode (VM-Isolated Deliverables):

   • Driven by CoworkAgent running inside an isolated VM or Docker container environment (Hypermachine).
   • Generates documents, spreadsheets, research reports, and presentation deliverables without touching host project files.
   • Includes specialized tools like organize_folder, export_deliverable, and seamless task delegation back to CodingAgent.

3. Code Workspace:

   • Integrated file context explorer, project TODOs tracker, and workspace directory switcher.
   • Monaco Editor preview with real-time syntax highlighting and diff comparisons.

4. Design Canvas:

   • Interactive vector design canvas supporting layer trees, artboards, and agent-driven visual layout updates.
   • Direct export capabilities to Figma (.fig), Adobe XD (.xd), and clean SVG formats.

5. DataHub & Finance:

   • DataHub: Dedicated workspace with browser automation tabs, dataset schema extraction, linked record explorers, and verified preview tables.
   • Finance: Financial modeling tools for cash-flow forecasting, three-statement financial models, cap table calculations, and operating budgets.

6. Projects & Background Scheduler:

   • Dashboard to create and organize isolated project workspaces with independent SQLite session stores.
   • Cron-based background task runner (node-cron) for automated repository maintenance, code health checks, and scheduled data extraction with persisted run logs.

Core Agent Capabilities

• Model Agnostic Engine: Universal provider routing supporting anthropic:claude-3-5-sonnet, openai:gpt-4o, google_genai:gemini-1.5-pro, ollama:llama3, and arbitrary OpenAI-compatible endpoints (OPENAI_BASE_URL for vLLM, LM Studio, or local servers).
• Checkpointed SQLite Sessions & Rewind: Sessions are streamed and saved in real time to local SQLite databases (~/.flexcrew/projects/<slug>/flexcrew.db). Before modifying files, FlexCrew captures filesystem snapshots, enabling /rewind to safely restore both chat conversation and code history.
• Interactive Approval Guardrails: Granular permission confirmation prompts (Once, Always, Deny) for shell operations and file writes. Rules can be permanently stored in permissions.json to auto-approve safe tasks and block destructive commands.
• Specialist Subagent Delegation: Primary agents can spawn isolated specialist subagents (e.g. data science, security audits, deep research) via SubagentRegistry to execute parallel subtasks without cluttering the main conversation context.
• Extensible Skills & MCP Tools: Over 100 built-in skills covering software architecture, test generation, diagrams, document drafting, and security threat modeling. Developers can add custom skills under .flexcrew/skills/, configure lifecycle hooks (pre-tool, post-tool, post-edit), or attach external tools via local and global Model Context Protocol (MCP) servers.
• Context Management & Compaction: Real-time token budget tracking, @file mentions for context attachment, /load and /detach pinned files, and /compact summarization to keep long multi-turn sessions responsive and cost-effective.