SUBGEMI: Gemini Sub-Agent Orchestration

The industrial-grade parallel engine for Gemini.

subgemi is a standalone CLI tool designed for high-agency, autonomous task execution. It allows you to delegate complex, tedious, or parallel tasks to Gemini sub-agents while you maintain focus on project architecture.

🚀 Key Features

• Atomic Parallelism: Dispatch dozens of background tasks simultaneously.
• Isolated Sandboxing: Every agent runs in its own isolated git worktree with read-only metadata protection.
• Distributed State: High-performance, lock-free architecture using atomic JSON artifacts.
• Live Dashboard: Real-time tree visualization (DAG) of all active and historical sessions.
• Usage Metrics: Built-in token burn tracking and spend estimation (USD) via subgemi metrics.
• Active Health Checks: Built-in "Dead Man's Switch" detects and reaps zombie processes automatically.

📦 Installation

pip install gemini-subagent

Requirements: Python 3.10+, Gemini CLI, Tmux.

🛠️ Usage

1. Delegate (The Fork)

Dispatch a task organized by lanes or personas:

subgemi task delegate "Audit all endpoints in src/api/" --lane security --persona security_lead

2. Monitor (The Board)

Track execution progress across the swarm:

subgemi session board

3. Analyze (The Metrics)

Track your ROI and token efficiency:

subgemi metrics board

4. Cleanup (The Reaper)

Purge orphaned monitors and dangling processes:

subgemi session prune --hard

🏗️ Architecture

subgemi follows the One-Shot Context principle. When a task is delegated, the engine:

1. Creates an isolated Git Worktree.
2. Bundles project Rules, Roles, and Workflows.
3. Packs the repository context into a high-density Repomix bundle.
4. Spawns a Tmux monitor for background visibility.
5. Executes the task via an FSM (Finite State Machine) to ensure robust lifecycle tracking.

Built by NLanN.