Metadata-Version: 2.3
Name: gemini-subagent
Version: 0.1.5
Summary: Parallel sub-agent orchestration CLI for Gemini
License: MIT
Keywords: gemini,agent,cli,orchestration,parallel
Author: NLanN
Author-email: alan@openclaw.dev
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: filelock (>=3.13.1,<4.0.0)
Requires-Dist: httpx (>=0.27.2,<0.28.0)
Requires-Dist: mcp (>=1.26.0,<2.0.0)
Requires-Dist: rich (>=13.0.0,<14.0.0)
Requires-Dist: typer (>=0.12.0)
Project-URL: Documentation, https://github.com/NLanN/gemini-subagents/tree/main/docs
Project-URL: Repository, https://github.com/NLanN/gemini-subagents
Description-Content-Type: text/markdown

# 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

```bash
pip install gemini-subagent
```

*Requirements: Python 3.10+, Gemini CLI, Tmux.*

## 🛠️ Usage

### 1. Delegate (The Fork)

Dispatch a task organized by lanes or personas:

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

### 2. Monitor (The Board)

Track execution progress across the swarm:

```bash
subgemi session board
```

### 3. Analyze (The Metrics)

Track your ROI and token efficiency:

```bash
subgemi metrics board
```

### 4. Cleanup (The Reaper)

Purge orphaned monitors and dangling processes:

```bash
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](https://github.com/NLanN).

