manual_slop/GEMINI.md

Project Overview

Manual Slop is a local GUI application designed as an experimental, "manual" AI coding assistant. It allows users to curate and send context (files, screenshots, and discussion history) to AI APIs (Gemini and Anthropic). The AI can then execute PowerShell scripts within the project directory to modify files, requiring explicit user confirmation before execution.

Main Technologies:

• Language: Python 3.11+
• Package Management: uv
• GUI Framework: Dear PyGui (dearpygui), ImGui Bundle (imgui-bundle)
• AI SDKs: google-genai (Gemini), anthropic
• Configuration: TOML (tomli-w)

Architecture:

• gui.py: The main entry point and Dear PyGui application logic. Handles all panels, layouts, user input, and confirmation dialogs.
• ai_client.py: A unified wrapper for both Gemini and Anthropic APIs. Manages sessions, tool/function-call loops, token estimation, and context history management.
• aggregate.py: Responsible for building the file_items context. It reads project configurations, collects files and screenshots, and builds the context into markdown format to send to the AI.
• mcp_client.py: Implements MCP-like tools (e.g., read_file, list_directory, search_files, web_search) as native functions that the AI can call. Enforces a strict allowlist for file access.
• shell_runner.py: A sandboxed subprocess wrapper that executes PowerShell scripts (powershell -NoProfile -NonInteractive -Command) provided by the AI.
• project_manager.py: Manages per-project TOML configurations (manual_slop.toml), serializes discussion entries, and integrates with git (e.g., fetching current commit).
• session_logger.py: Handles timestamped logging of communication history (JSON-L) and tool calls (saving generated .ps1 files).

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 = "****"
  

• Run the Application:

  uv run .\gui.py
  

Development Conventions

• Configuration Management: The application uses two tiers of configuration:
  • config.toml: Global settings (UI theme, active provider, list of project paths).
  • manual_slop.toml: Per-project settings (files to track, discussion history, specific system prompts).
• Tool Execution: The AI acts primarily by generating PowerShell scripts. These scripts MUST be confirmed by the user via a GUI modal before execution. The AI also has access to read-only MCP-style file exploration tools and web search capabilities.
• Context Refresh: After every tool call that modifies the file system, the application automatically refreshes the file contents in the context using the files' mtime to optimize reads.
• UI State Persistence: Window layouts and docking arrangements are automatically saved to and loaded from dpg_layout.ini.
• Code Style:
  • Use type hints where appropriate.
  • Internal methods and variables are generally prefixed with an underscore (e.g., _flush_to_project, _do_generate).
• Logging: All API communications are logged to logs/comms_<ts>.log. All executed scripts are saved to scripts/generated/.