# Sloppy

![img](./gallery/splash.png)

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

**Tech Stack**: Python 3.11+, Dear PyGui / ImGui, FastAPI, Uvicorn
**Providers**: Gemini API, Anthropic API, DeepSeek, Gemini CLI (headless)
**Platform**: Windows (PowerShell) — single developer, local use

---

## Architecture at a Glance

Four thread domains operate concurrently: the ImGui main loop, an asyncio worker for AI calls, a `HookServer` (HTTP on `:8999`) for external automation, and transient threads for model fetching. Background threads never write GUI state directly — they serialize task dicts into lock-guarded lists that the main thread drains once per frame ([details](./docs/guide_architecture.md#the-task-pipeline-producer-consumer-synchronization)).

The **Execution Clutch** suspends the AI execution thread on a `threading.Condition` when a destructive action (PowerShell script, sub-agent spawn) is requested. The GUI renders a modal where the user can read, edit, or reject the payload. On approval, the condition is signaled and execution resumes ([details](./docs/guide_architecture.md#the-execution-clutch-human-in-the-loop)).

The **MMA (Multi-Model Agent)** system decomposes epics into tracks, tracks into DAG-ordered tickets, and executes each ticket with a stateless Tier 3 worker that starts from `ai_client.reset_session()` — no conversational bleed between tickets ([details](./docs/guide_mma.md)).

---

## Documentation

| Guide | Scope |
|---|---|
| [Architecture](./docs/guide_architecture.md) | Threading model, event system, AI client multi-provider architecture, HITL mechanism, comms logging |
| [Tools & IPC](./docs/guide_tools.md) | MCP Bridge security model, all 26 native tools, Hook API endpoints, ApiHookClient reference, shell runner |
| [MMA Orchestration](./docs/guide_mma.md) | 4-tier hierarchy, Ticket/Track data structures, DAG engine, ConductorEngine execution loop, worker lifecycle |
| [Simulations](./docs/guide_simulations.md) | `live_gui` fixture, Puppeteer pattern, mock provider, visual verification patterns, ASTParser / summarizer |

---

## Module Map

| File | Lines | Role |
|---|---|---|
| `gui_2.py` | ~3080 | Primary ImGui interface — App class, frame-sync, HITL dialogs |
| `ai_client.py` | ~1800 | Multi-provider LLM abstraction (Gemini, Anthropic, DeepSeek, Gemini CLI) |
| `mcp_client.py` | ~870 | 26 MCP tools with filesystem sandboxing and tool dispatch |
| `api_hooks.py` | ~330 | HookServer — REST API for external automation on `:8999` |
| `api_hook_client.py` | ~245 | Python client for the Hook API (used by tests and external tooling) |
| `multi_agent_conductor.py` | ~250 | ConductorEngine — Tier 2 orchestration loop with DAG execution |
| `conductor_tech_lead.py` | ~100 | Tier 2 ticket generation from track briefs |
| `dag_engine.py` | ~100 | TrackDAG (dependency graph) + ExecutionEngine (tick-based state machine) |
| `models.py` | ~100 | Ticket, Track, WorkerContext dataclasses |
| `events.py` | ~89 | EventEmitter, AsyncEventQueue, UserRequestEvent |
| `project_manager.py` | ~300 | TOML config persistence, discussion management, track state |
| `session_logger.py` | ~200 | JSON-L + markdown audit trails (comms, tools, CLI, hooks) |
| `shell_runner.py` | ~100 | PowerShell execution with timeout, env config, QA callback |
| `file_cache.py` | ~150 | ASTParser (tree-sitter) — skeleton and curated views |
| `summarize.py` | ~120 | Heuristic file summaries (imports, classes, functions) |
| `outline_tool.py` | ~80 | Hierarchical code outline via stdlib `ast` |

---

## Setup

### Prerequisites

- Python 3.11+
- [`uv`](https://github.com/astral-sh/uv) for package management

### Installation

```powershell
git clone <repo>
cd manual_slop
uv sync
```

### Credentials

Configure in `credentials.toml`:

```toml
[gemini]
api_key = "YOUR_KEY"

[anthropic]
api_key = "YOUR_KEY"

[deepseek]
api_key = "YOUR_KEY"
```

### Running

```powershell
uv run gui_2.py                        # Normal mode
uv run gui_2.py --enable-test-hooks    # With Hook API on :8999
```

### Running Tests

```powershell
uv run pytest tests/ -v
```

---

## Project Configuration

Projects are stored as `<name>.toml` files. The discussion history is split into a sibling `<name>_history.toml` to keep the main config lean.

```toml
[project]
name = "my_project"
git_dir = "./my_repo"
system_prompt = ""

[files]
base_dir = "./my_repo"
paths = ["src/**/*.py", "README.md"]

[screenshots]
base_dir = "./my_repo"
paths = []

[output]
output_dir = "./md_gen"

[gemini_cli]
binary_path = "gemini"

[agent.tools]
run_powershell = true
read_file = true
# ... 26 tool flags
```