Supporter

An elite technical strategist and principal software architect TUI chat client powered by Google Gemini. supporter orchestrates complex development tasks via a multi-agent delegation system and sandboxed tool execution.

Features

• Multi-Agent Orchestration: Orchestrator-driven delegation to specialized roles (Architect, Security Auditor, Code Writer, Test Engineer, Code Reviewer).
• Sandboxed Execution: Mandatory sandbox-exec for all shell operations with tiered security policies (T1/T2/T3).
• High-Fidelity TUI: Reactive dashboard built with Textual and Rich, featuring real-time streaming and async progress notifications.
• Reliability Layer:
  • Health-Aware Rotation: Automatic rotation across multiple Gemini API keys with health tracking and cooldowns.
  • Dynamic Fallback: Seamless transition to fallback models on 5xx, quota, or exhaustion errors.
• Performance & Runtime:
  • Startup: Deferred heavy imports and CSS parsing for instant launch.
  • Execution: In-memory caching with batched flushes, regex/policy caching, and zero-wait key rotation.
  • Streaming: Optimized Live provider with parallel tool calls, generator-based thought streaming, and error-capture logging.
• Surgical Tooling:
  • execute_bash: Sandboxed shell with UI-confirmed risky operations.
  • read_file / write_file: Path-validated file operations restricted to project root.
  • google_search: Real-time research capabilities.
  • delegate_tasks: DAG-based background task execution.

Agent Roster

Role	Persona	Specialist Tools
Explorer	Read-only reconnaissance specialist	read_file, execute_bash, google_search
Security Auditor	Vulnerability and risk analysis	read_file, execute_bash
Code Writer	Feature implementation and refactoring	read_file, write_file, execute_bash
Test Engineer	TDD specialist and verification	read_file, execute_bash
Code Reviewer	Quality and convention enforcement	read_file

Installation

This project requires Python 3.14+ and uv.

# Clone the repository
git clone https://github.com/your-org/supporter.git
cd supporter

# Install dependencies
uv sync

Usage

1. Configure Environment: Create a .env file in the project root:

   GEMINI_API_KEYS=your_key_1,your_key_2
   GEMINI_MODEL=gemma-4-31b-it
   GEMINI_LIVE_MODEL=gemini-3.1-flash-live-preview
   GEMINI_LIVE_FALLBACK_MODEL=gemini-2.5-flash-native-audio-preview-12-2025
   LOG_LEVEL=info

2. Launch the TUI:

   uv run supporter

Architecture

Flow: User → TUI (Textual) → Orchestrator (Agent Logic) → Tools (Bash/Delegate/Search) → LLM → Output

• src/supporter/agent.py: Core orchestrator and delegation logic.
• src/supporter/providers/: Gemini Live and REST implementations with health tracking.
• src/supporter/tools/bash/: Security-hardened shell execution logic.
• src/supporter/tools/delegate/: Capsule-based task state and async orchestration.
• src/supporter/tui/: Reactive UI, bubble-based thought streaming, and dashboard.

Development & Verification

Testing

Tests are organized by layer and marker:

• tests/unit/: Component-level logic.
• tests/integration/: Cross-component flows.
• tests/e2e/: Full lifecycle verification.

uv run pytest tests                 # Run all tests
uv run pytest tests -m unit         # Run unit tests
uv run pytest tests -m integration   # Run integration tests

Quality Control

uv run ruff check .      # Lint check
uv run ruff format .     # Format code
uv run mypy .            # Type check

Security Standards

• Isolation: Sub-agents have zero conversation history and minimal tool access.
• Validation: All file writes and T2/T3 bash commands require manual UI confirmation.
• Constraints: No piped/chained shell commands; strict path traversal protection.