README.md

AI-Powered Parallel Worktree Automation

Write tasks. Let AI execute them in parallel. Review and merge.

English · 한국어

While you sleep, your AI is working.

In the age of AI-generated code, the developer's role is shifting toward supervision and review. But vibe coding without understanding eventually hits a wall.

CLITrigger takes the tasks you queued before bed and runs them overnight — multiple AI coding agents (Claude Code · Codex · Gemini CLI) working in parallel, each in its own isolated git worktree. Next morning, you just review the stack of diffs and accept / reject.

Parallel AI execution — without losing context.

AI CLIs working simultaneously across isolated git worktrees

Why CLITrigger?

Boris Cherny, creator of Claude Code, emphasizes parallelism as the key to AI-assisted development. Waiting for one task to finish before starting the next is the new bottleneck.

At the same time, most AI services have rate limits — you can burn through your daily quota by noon and be stuck waiting until midnight.

CLITrigger solves both problems:

• Right now — Multiple tasks run in isolated git worktrees, with Claude / Gemini / Codex executing in parallel
• Without hitting limits — Schedule tasks for off-peak hours to make the most of your token quota
• Better output — Multiple AI agents debate and review before implementation, producing higher-quality results than a single AI working alone

How It Works

[Write TODOs in the browser]
         ↓
┌──────────────────────────────────────────────────────────────┐
│  TODO 1: Implement login      → worktree/feature-login     → Claude CLI → auto-commit  │
│  TODO 2: Signup page          → worktree/feature-signup    → Gemini CLI → auto-commit  │
│  TODO 3: Dashboard layout     → worktree/feature-dashboard → Claude CLI → auto-commit  │
└──────────────────────────────────────────────────────────────┘
         ↓
[Live log streaming → Review diffs → Merge to main]

Each TODO runs in its own isolated git worktree — no conflicts, separate branches, independent commit history. You review the results and decide what to merge.

The Workflow — Hand Off, Then Review

CLITrigger is built for "delegate and review" — not for staring at a progress bar.

Scenario 1: The AI night shift — hand off at bedtime, pick up in the morning

Before bed, dump unfinished work and sudden ideas into the Planner, convert them into TODOs or scheduled runs, then close the laptop. While you sleep, Claude / Gemini / Codex burn through your token quota in parallel worktrees. Next morning, sit down with coffee and review the diffs holistically — accept what makes sense, reject what doesn't, merge what's ready.

Your tokens never sleep. Neither does your codebase.

Scenario 2: The background worker

Stay focused on your main work while CLITrigger handles side quests in the background. Refactors, test coverage, doc updates, speculative features — the stuff you never have time for — gets done while you ship the critical path. Browser notifications (or phone alerts via Cloudflare Tunnel) surface completed tasks only when they need your attention.

The Core Loop

    Evening                 Overnight / Sidelined              Morning / Break
  ───────────              ───────────────────────          ────────────────────
   Capture         →         AI executes in parallel   →    Review holistically
   • Planner                 • Worktree isolation           • Diff by diff
   • TODOs                   • Rate-limit auto-recovery     • Log by log
   • Schedules               • Multi-agent discussion       • Accept / Reject / Merge

Every feature — Planner, Scheduler, worktree isolation, rate-limit auto-recovery, multi-agent discussion, the built-in Git client — exists to support this loop: capture → delegate → review.

Features

Wiki (Karpathy LLM-Wiki Pattern)

A per-project knowledge graph (nodes + typed edges) that you curate once and selectively inject into TODO and discussion prompts. Stop pasting the same domain context every run. Toggle between List and Graph views (@xyflow/react + dagre auto-layout, drag-to-connect edges, cycle guards on precedes/refines), pick None / All / Selected / Auto per task — Auto runs a one-shot LLM retrieval right before each call to pick only the relevant entries, saving tokens. Preview the exact <long_term_memory> block (with char/token estimates) before sending; export DB → .clitrigger/wiki/<entity>/<slug>.md Markdown + Disk diff to keep the wiki alive in git or Obsidian. Lint surfaces duplicates / orphans / stale entries with inline fix actions (merge / delete / link); the Activity sub-tab logs ingest / lint / retrieve / merge events with severity. CLI-agnostic — Claude, Gemini, and Codex all see identical context with no adapter changes.

Graph view of the per-project wiki — entries clustered by tag (Concept · Decision · Feature · Pattern), typed edges visualize how ideas relate, and selective injection feeds only what's relevant into each prompt

Planner

A lightweight task planner separate from TODOs — capture ideas, attach images, tag with colors, sort by any column. Convert any planner item into a TODO or a schedule in one click. Markdown export/import (status sections + GFM checkboxes + HTML-comment metadata) lets you move plans across machines or share via GitHub / Obsidian / any plain Markdown viewer. Drop a .md file onto the planner card to import.

Inline editing, color-coded tags, image attachments, and one-click conversion to TODOs or schedules

Parallel Worktree Execution (Tasks)

Each TODO automatically gets its own git worktree. Claude / Gemini / Codex CLIs execute simultaneously in parallel. Dependency chains let you automatically trigger follow-up tasks and branch merges once prerequisites complete. Per-project worktree toggle plus per-TODO tri-state override (inherit / force-worktree / force-main) give you fine-grained control — main-branch tasks are automatically serialized to avoid conflicts. Drag-and-drop reordering and an iOS-style stack mode keep long task lists manageable.

Interactive Sessions

Long-lived interactive CLI sessions as first-class entities — bring up a Claude / Gemini / Codex session in a floating draggable window. VS Code-style window grouping and docking: drag a tab onto another window for a 5-zone diamond (top/bottom/left/right/center) to either split into resizable panes or merge as tabs, plus Aero-style edge snapping, sticky window-to-window snapping, and a minimize-to-dock-tray flow — keeps multi-session screens tidy. xterm.js rendering shows ANSI colors, cursor control, and TUI box-drawing identically to a native terminal. PTY spawns at the exact viewport dimensions, with per-session font size (A−/A+ buttons or Ctrl/Cmd ±) for readability. Per-session wiki injection plus a Send/Skip pre-flight banner lets you review the auto-generated initial prompt before it hits the model. Inline edit button updates non-running sessions in place. iOS Safari mobile Hangul IME is composed via a client-side dubeolsik composer. Window geometry, group tree, and tab arrangement persist and survive tab navigation; works on desktop and mobile (fullscreen on small screens).

Claude, Gemini, and Codex sessions docked side-by-side via VS Code-style window grouping — each running in its own worktree branch

Multi-Agent Discussion

AI agents with different roles — architect, developer, reviewer — debate in rounds before implementation. The resulting design is far more robust than a single AI working in isolation. Agents flagged as Implementers (can_implement) can commit code during their regular turns, while a final implementation round stitches everything together. Auto-implement triggers the code-writing round automatically on consensus. Or hit Send to Planner on a finished discussion to have the transcript distilled into curated planner items via a one-shot LLM extraction — review and edit before persisting.

Multiple AI agents with different roles debating in the Discussion view

Scheduled Execution

Schedule tasks for off-peak hours to avoid rate limits. Supports recurring cron schedules, one-time scheduled runs, and auto-recovery scheduling on rate-limit events — if the CLI hits a token quota, CLITrigger schedules a retry for the exact reset time.

Cron-based recurring and one-time scheduled task execution

Built-in Git Client

A full Git client lives inside the web UI with a Fork/SourceTree-style layout — a workspace menu switches between File Status (staged/unstaged file lists, working-tree diff viewer, commit message + push toggle, Cmd/Ctrl+Enter to commit) and History (commit graph, action toolbar, worktree list, VS Code-style branch context menu with checkout / merge / rebase / fetch / pull / push / rename / delete, and a commit detail panel with file-level diff viewer). Every split is user-resizable and persisted to localStorage. Non-ASCII filenames (Korean, CJK, emoji) render correctly in diff and status output.

Commit graph, branch actions, file diffs — all in the browser

Analytics

Per-project cost and execution stats powered by Recharts — stacked bar chart by CLI tool, donut chart for status distribution, line chart for cost/token trends. Denormalized cost fields in the DB keep aggregation fast even on long histories.

Cost and token usage broken down by CLI, status, and over time

Morning Review Queue

A single cross-project triage screen for the "delegate overnight, review next morning" loop. Aggregates every recent TODO across all your projects into a card stack with project label, last-assistant summary, token totals, diff stats, and a server-classified risk badge (low / medium / high based on status and diff size). Keyboard-only operation: j/k to navigate, Enter for the embedded log viewer, Space / → to expand changed files and diffs inline, m to merge, d to discard, Esc to close — N todos become O(N) keypresses. Time-window selector (12h / 24h / 7d), filter chips (All / Risky / Quick wins / Failed), and a sticky token ribbon with CLI breakdown. Inline diffs survive worktree cleanup by falling back through branch ref → master/main.

Live Logs (Chat & Raw)

WebSocket-based real-time log streaming with two view modes — Chat mode renders assistant messages as markdown with collapsible tool-use rows; Raw mode is a flat terminal view. Multi-round continue reuses the same worktree via the CLI's native --continue flag.

Multi-CLI & Sandbox Mode

Select Claude / Gemini / Codex per project, per TODO, or per discussion agent. Strict sandbox mode restricts CLI file access to the worktree directory using each CLI's native sandboxing (Claude settings.json, Codex --full-auto, Gemini prompt-level restriction).

Remote Access

Access and control from anywhere via Cloudflare Tunnel. Browser notifications alert you when tasks or discussions complete, so you can walk away and come back. Route a named tunnel through your own domain — set Tunnel Name + Custom Hostname in the sidebar ⚙ → Tunnel settings modal, and the displayed URL becomes https://app.your-domain.com, sidestepping the browser "dangerous site" warnings that hit *.trycloudflare.com / *.cfargotunnel.com by inheriting your domain's reputation.

Favorites Launcher

Register frequently-used external tools (executables, shell commands, URLs/folders) in a global Favorites section in the sidebar. Fire-and-forget one-click execution from anywhere in CLITrigger — reduces context-switching to the OS shell for environment setup, IDE launches, or external service access.

Tech Stack

Quick Start

Option A — Desktop App (recommended for end users)

Download the installer for your platform from the latest GitHub release:

• Windows — CLITrigger-Setup-<version>.exe (NSIS installer) or the portable .exe
• macOS — CLITrigger-<version>.dmg (Apple Silicon & Intel)
• Linux — CLITrigger-<version>.AppImage

The desktop app bundles Node.js and the native modules (better-sqlite3, node-pty, cloudflared), so no separate runtime install is needed. On first launch a setup screen appears in the embedded browser — pick a password there and you're in. External sharing (Cloudflare tunnel) stays paused until setup completes, so the first user is guaranteed to be you.

Option B — npm (recommended for developers)

# Install
npm i -g clitrigger
clitrigger

# Upgrade to the latest version
npm i -g clitrigger@latest
# Check current version: clitrigger --version

On first run the server starts immediately. Open http://localhost:3000 → set a password on the welcome screen → register a project → write TODOs → click Start. Change the password later via Settings → Account in the web UI.

CLITrigger also prints a one-line Update available: <new> -> npm i -g clitrigger@latest hint at startup whenever a newer version is on npm — no auto-update, you decide when to upgrade.

# Change settings
clitrigger config port 8080    # Change port
clitrigger config tunnel on    # Enable Cloudflare tunnel for external sharing

Prerequisites: Node.js 20+, Git, at least one AI CLI (Claude / Gemini / Codex)

Supported Platforms: Windows · macOS · Linux — all core code is cross-platform compatible. On macOS, you may need xcode-select --install for native module compilation.

Run from Source (for development)

# 1. Clone & install
git clone https://github.com/HyperAITeam/CLITrigger.git
cd CLITrigger
npm install
cd src/client && npm install && cd ../..

# 2. Configure environment
cp .env.example .env
# AUTH_PASSWORD is optional — leave it blank and the dev server will show the
# setup screen on first browser load. Set it only if you want to skip setup.

# 3. Run
npm run dev

npm run dev        # Development mode
npm run build      # Build
npm run start      # Production server
npm test           # Run tests

Remote Access (Cloudflare Tunnel)

# Install cloudflared
winget install cloudflare.cloudflared    # Windows
brew install cloudflared                  # macOS

# Set TUNNEL_ENABLED=true in .env, then:
npm run start:tunnel
# → Outputs https://xxxx.trycloudflare.com in the console

Route a named tunnel through your own domain (optional)

To avoid the "dangerous site" browser warnings on *.trycloudflare.com / *.cfargotunnel.com, point a named tunnel at your own domain. Either use the sidebar ⚙ → Tunnel settings modal (Tunnel Name + Custom Hostname), or the CLI:

clitrigger config tunnel hostname app.your-domain.com
cloudflared tunnel route dns <tunnel-name> app.your-domain.com   # one-time

The displayed URL becomes https://app.your-domain.com and reputation tracks your domain.

Documentation

Star & Join Us

If CLITrigger saves you time, please give us a star — it genuinely helps the project reach more developers.

Want to help shape what comes next? We're actively looking for contributors:

• File an issue — bug reports, feature requests, and rough ideas all welcome at Issues
• Open a PR — start with good first issue labels, or pick anything that itches you
• Share what you built — drop your worktree workflows, custom plugins, or productivity tips in Discussions

Every star, issue, and PR moves this faster. Thank you 🙏

Contributors

Thanks to everyone who has contributed to CLITrigger!

Star History

License

MIT — Free to use, modify, and distribute.