<div align="center"> <br/> <!-- Badges -->

<a href="https://github.com/lulu-sk/CodexFlow/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/lulu-sk/CodexFlow?style=for-the-badge&logo=undertale&logoColor=red&color=orange"/></a> <a href="https://github.com/lulu-sk/CodexFlow/releases"><img alt="Downloads" src="https://img.shields.io/github/downloads/lulu-sk/CodexFlow/total?style=for-the-badge&label=Downloads"/></a> <img alt="Platform" src="https://img.shields.io/badge/Windows%2011+WSL-Recommended-blue?style=for-the-badge&logo=windows"/> <img alt="Electron" src="https://img.shields.io/badge/Electron-App-informational?style=for-the-badge&logo=electron"/> <img alt="React" src="https://img.shields.io/badge/React-18-informational?style=for-the-badge&logo=react"/> <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/License-Apache--2.0-success?style=for-the-badge"/></a>

</div> <br/>

| English | 简体中文 | | --- | --- |

CodexFlow

A "Unified Workbench" crafted for AI Coding Agents — switch between Codex / Claude / Gemini (and custom engines) in one click, organize sessions and history by project directories, run parallel tasks with Git Worktree, browse and resume conversations with Markdown rendering, and provide a graphical input box for CLI with support for pasting images / dragging files / @project files / full-screen input for efficient prompting.

• Platform Recommendation: Windows 11 + WSL (Default Distro: Ubuntu-24.04); provides the best experience when WSL is installed and engines are available within it. PowerShell Mode (PS5 / PS7 / CMD) is also fully supported.
• Project Structure: UI Host with a Minimal Terminal Bridge (Electron + React + Vite + node-pty + xterm).

---

Table of Contents

• Core Features
• Interface Overview
• Quick Start
• Usage Tips
• Development & Build
• Internationalization (i18n)
• Directory Structure (Summary)
• Runtime Notes & Indexes
• Verification Steps
• Security & Paths
• Diagnostics & Logs
• Community & Contributions
• License
• Resources & Conventions

---

✨ Core Features

1. Unified Multi-Engine Workbench (Codex / Claude / Gemini / Terminal + Custom) Switch engines instantly via the top bar. Built-in engines support usage monitoring and completion notifications (taskbar badges/system notifications/alert sounds). Each engine can be independently configured with startup commands, light/dark icons, and execution environments (WSL / Windows / Windows PowerShell / PowerShell 7 / specific WSL distro), with support for custom engine extensions.
2. Cross-Engine History Center Read-only incremental indexing of native session records across multiple engines (Codex / Claude / Gemini) with full support for both Windows and WSL paths. Sessions are aggregated by project directory with one-click creation of new sessions. Features include filtering, quick search, and time-grouped previews. The detail view supports Markdown rendering (with syntax highlighting) and in-page search highlighting for efficient history lookups.
3. Native Git Worktree Parallel Workflow (Designed for Parallel Agents, Recommended) Create or reuse worktrees directly from branches (branch badge ⎇). Supports single or hybrid parallel workflows across multiple engines (Codex / Claude / Gemini) with a concurrent progress panel, cancellation, and rollback cleanup. Provides a seamless loop of "Create → Run → Merge → Clean" after task completion.
4. GUI Input for CLI: @Files / @Rules / Images / Drag-and-Drop The input box supports pasting images (with inline previews), dragging files/directories, and @ quick selection for project files/directories. AGENTS.md / CLAUDE.md / GEMINI.md can be quickly edited and referenced. Supports full-screen expansion for crafting long and complex prompts.
5. One-Click Resume for History Sessions Compatible with various CLI resume strategies; handles WSL/Windows path differences gracefully. Allows resuming conversations within the app or in an external console with one click.
6. Engine Completion Notifications Integrated system notifications, alert sounds, and taskbar badges with project-level navigation. When an engine finishes its task, you can jump directly back to the corresponding project and tab, ensuring you never miss a completion message.
7. Usage & Account Management Real-time monitoring of quotas and usage for each engine in the top bar. Supports multi-account configuration and quick switching (independent management of history and sessions per engine).
8. Polished Experience & Deep Customization Supports Light/Dark/System-matching themes. Customizable terminal fonts, themes, scrollbars, and overall appearance. Project management includes sorting, hiding, drag-and-drop grouping, and custom nicknames. Full network proxy support is also included.

---

🖼️ Interface Overview

1) Overview (Engine Switcher + Project Tabs + History Entry)

2) Git Worktree Workflow (Create / Parallel / Merge & Recycle)

3) History Center (Pagination + Markdown Rendering + Search Highlighting)

4) One-Click Resume + Input Enhancement (@Files/@Rules + Drag + Paste Image)

5) Settings & Engines (Custom Engines, Icons, Execution Environment)

---

🚀 Quick Start

Environment Preparation

• Windows 11 with WSL installed (Default distro Ubuntu-24.04, configurable in settings; falls back to system default if specified distro is invalid).
• At least one AI Programming Agent CLI runnable in WSL or PowerShell (e.g., codex, claude, or gemini).
• For codex, WSL Terminal Mode is recommended; PowerShell Mode (PS5 / PS7) is also available.

Setup Tutorials

• Install WSL (Ubuntu) and Codex CLI on Windows

Installation

• If a release version is available, download the latest installer from Releases.
• Otherwise, follow the "Development & Build" section below to package it locally.

First-Time Use

1. Click the Settings (gear icon) in the top right to configure the environment: Select WSL / PowerShell, specify the correct WSL distro, and save.
2. Choose your desired engine from the top bar (Codex / Claude / Gemini / Terminal / Custom).
3. Select (or add) a project directory and click + to start a new session.
4. Log in or provide API credentials in the terminal as required.
5. Paste images, use @ for project files or rules, drag files in, and start your collaborative coding journey.

---

🧪 Usage Tips

• One-Click Resume: Select any conversation from the history list and click "Continue" to pick up where you left off — supported across all engines.
• Filter & Copy History: Supports filtering and direct copying of rendered content; Markdown rendering makes history easy to read.
• Input Boosters: Pasted images automatically show inline previews; use full-screen mode for composing long prompts.
• Worktree Workflow: Create worktrees from the project sidebar to run agents in parallel, then merge results back to the base branch.
• Multi-Project Management: The left sidebar shows active session counts, helping you keep track of multiple tasks.
• Multiple Instances (Profiles): Enable "Experimental Features" in settings (requires restart) to open multiple application instances. For a persistent profile, use --profile <name> (e.g., CodexFlow.exe --profile work).
• Keyboard Shortcuts: Hover over list items to see available shortcuts; dialogs support keyboard navigation.

---

🛠️ Development & Build

Development Environment

• Node.js ≥ 18
• WSL installed with an available distro (Default: Ubuntu-24.04)

Start Development

# Install dependencies (compiles Electron main process and rebuilds native modules)
npm i

# Launch Vite (web) and Electron (main process) concurrently
npm run dev
# During development, the main process loads from DEV_SERVER_URL=http://localhost:5173

Production Build

# Equivalent to: npm run build:web && electron-builder
npm run build

• The postinstall script compiles the main process to dist/electron and rebuilds native modules (like node-pty) before packaging.
• On Windows, you can run build-release.bat (passing skip-install to skip reinstalling dependencies).
• If you modify /electron/* source code, rerun npm i or manually run npx tsc -p tsconfig.json to refresh dist/electron. If node-pty reports an ABI mismatch, run npm run postinstall to rebuild native dependencies.

Common Scripts

npm run test        # Run unit tests with Vitest
npm run i18n:report # Check key differences against the English baseline
npm run i18n:check  # Strict key validation used in CI

---

🌐 Internationalization (i18n)

• Tech Stack: i18next + react-i18next + ICU; namespaces are split by module: common, settings, projects, terminal, history, at.
• Component Usage Example:

import { useTranslation } from 'react-i18next'
const { t } = useTranslation('settings')
t('settings:language.label')

• Resource Directory: `web/src/locale