manual_slop/GEMINI.md

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:

  [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:

  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.