# GEMINI.md

This file covers Gemini-CLI-specific operational notes for the Manual Slop project. The primary toolchain is Gemini CLI; for general agent orientation, see `AGENTS.md`.

## Project Overview

**Manual Slop** is a local GUI orchestrator for LLM-driven coding sessions. It bridges high-latency AI reasoning with a low-latency ImGui render loop via a thread-safe async pipeline; every AI-generated payload passes through a human-auditable gate before execution.

**Main Technologies:**
*   **Language:** Python 3.11+
*   **Package Management:** `uv`
*   **GUI Framework:** ImGui Bundle (`imgui-bundle`)
*   **AI SDKs:** `google-genai` (Gemini), `anthropic` (Claude), `openai` (DeepSeek + MiniMax via OpenAI-compatible endpoints), `GeminiCliAdapter` (headless gemini CLI subprocess)
*   **Configuration:** TOML (`tomli-w`)

**Providers Supported (as of 2026-06-02):**
- **Gemini SDK** — Primary; uses server-side CachedContent
- **Gemini CLI** — Headless adapter with full functional parity
- **Anthropic** — Ephemeral prompt caching (4-breakpoint system)
- **DeepSeek** — Code-optimized reasoning
- **MiniMax** — OpenAI-compatible alternative

**Entry Point:** `sloppy.py` (was `gui_legacy.py` before the rename; `gui_2.py` is now the active ImGui application module).

**Architecture (key modules):**
*   **`src/gui_2.py`:** Primary ImGui application; App class, frame-sync, HITL dialogs, event system. ~260K lines.
*   **`src/ai_client.py`:** Multi-provider LLM abstraction (Gemini, Anthropic, DeepSeek, Gemini CLI, MiniMax). Module-level singleton with state.
*   **`src/mcp_client.py`:** 45 MCP tools (file I/O, AST inspection, C/C++ tree-sitter, analysis, network, runtime, Beads). Three-layer security model.
*   **`src/multi_agent_conductor.py`:** ConductorEngine + WorkerPool. 4-Tier MMA orchestration with DAG execution.
*   **`src/dag_engine.py`:** TrackDAG (cycle detection, topological sort) + ExecutionEngine (tick-based state machine).
*   **`src/aggregate.py`:** Context aggregation pipeline.
*   **`src/app_controller.py`:** Main controller; bridges GUI and async AI workers.
*   **`src/api_hooks.py`:** HTTP API on `:8999` for external automation and IPC.
*   **`src/rag_engine.py`:** RAG subsystem (ChromaDB + embedding providers).
*   **`src/personas.py`:** Unified agent profile management.
*   **`src/workspace_manager.py`:** Workspace profile save/load.
*   **`src/hot_reloader.py`:** State-preserving module reloading.

Full module list: `src/*.py`. See `docs/guide_architecture.md` for the threading model and event system.

# Building and Running

*   **Setup:** The application uses `uv` for dependency management. Ensure `uv` is installed.
*   **Credentials:** You must create a `credentials.toml` file in the root directory to store your API keys:
    ```toml
    [gemini]
    api_key = "****"
    [anthropic]
    api_key = "****"
    [deepseek]
    api_key = "****"
    [minimax]
    api_key = "****"
    ```
    The `credentials.toml` is **blacklisted** by the MCP allowlist — AI tools cannot read it.
*   **Run the Application:**
    ```powershell
    uv run sloppy.py                        # Normal mode
    uv run sloppy.py --enable-test-hooks    # With Hook API on :8999
    ```

# Gemini-CLI-Specific Conventions

*   **Conductor Extension:** Gemini CLI uses the conductor extension, which reads `./conductor/` for task tracking, workflow, and product context. Tracks live in `conductor/tracks/<name>_<YYYYMMDD>/` with `spec.md`, `plan.md`, and `metadata.json`.
*   **Skill Activation:** Use `activate_skill mma-orchestrator` to load the orchestrator skill, then activate the tier-specific skill (e.g., `activate_skill mma-tier1-orchestrator`).
*   **The Conductor Convention:** Read `conductor/workflow.md` for the TDD protocol. Treat `conductor/tracks.md` as the task registry. Track implementation follows per-file atomic commits with git notes.
*   **Tool Execution:** AI-generated PowerShell scripts and tool calls pass through the Execution Clutch (HITL). Scripts are saved to `scripts/generated/<ts>_<seq>.ps1`.
*   **Context Refresh:** After every tool call that modifies the file system, the application automatically refreshes file contents in the context using `mtime` checks.
*   **Fuzzy Anchor Resilience:** Line-based operations (`get_file_slice`, `set_file_slice`, `py_update_definition`, fuzzy anchor slices) use FuzzyAnchor to survive file modifications. They can be batched in a single turn without line drift.
*   **Layout Persistence:** Window layouts are saved to `manualslop_layout.ini` (was `dpg_layout.ini`).
*   **Logging:** All API communications are logged to `logs/sessions/<id>/comms.log`. Tool calls to `toolcalls.log`. Generated scripts to `scripts/generated/`.
*   **Code Style:**
    *   Use exactly 1-space indentation for Python (NO EXCEPTIONS). See `conductor/product-guidelines.md`.
    *   Use the manual-slop MCP tools (`manual-slop_edit_file`, `manual-slop_py_update_definition`) for surgical edits — native edit tools destroy indentation.
    *   Internal methods and variables are prefixed with an underscore (e.g., `_flush_to_project`, `_do_generate`).

# Human-Facing Documentation

For understanding, using, and maintaining the tool, see `docs/Readme.md` and the 14 deep-dive guides it indexes. See `conductor/product.md` for the product vision.