80 lines
5.2 KiB
Markdown
80 lines
5.2 KiB
Markdown
# 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.
|