# Manual Slop

## *Note by the Human behind this*

I see the potential of AI as both an invaluable learning, percise techinical writing and code generation tool when handled with care and deep curation. This repo is both a proof of concept of this assertion and a tool to achieve this because every single paid or vested "AI Agenic developer" seems to not be interested in these principles.

The License for this will most likely be MIT or zlib. Nearly the entire codebase was heavily curated AI generated code. From vendors that have pirated nearly everyone's work. Most I can do is just be open to kofi and let whatever rep from this evolve.

## Why did you do this in Python

*TLDR: I apologize it was out of sheer practicality with time allocation and resources available. I really don't like python.*

Before I winged this project on a whim and frustration, I had tried AI with various langauges, unfortuantely python did remarkably well.

* Attic-Greek-TTS - ~3 kloc TTS tool for a dead language, with spectrograph anaylsis for verification.
* forth_bootslop - Used scripts to gather and curate large amounts information and data from sources into formats it could digest.

Prior to making this tool I had very dissapointing performance with more favaorable langauges: C11, Odin, or Jai (Which I don't have direct access to).

I don't enjoy web browser sandboxed runtimes so I didn't use javascript. I haven't attempted AI with lua much but that was the alternative, and I knew python had the next best support for AI toolchain bindings along with an imgui package. So based purely on these factors alone I resolved to attempt this in Python.

## Summary

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

A high-density 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.

**Design Philosophy**: Full manual control over vendor API metrics, agent capabilities, and context memory usage. High information density, tactile interactions, and explicit confirmation for destructive actions.

**Tech Stack**: Python 3.11+, ImGui Bundle (Dear ImGui + imgui-node-editor + imgui_markdown + ImGuiColorTextEdit), FastAPI, Uvicorn, tree-sitter (Python, C, C++), chromadb (RAG), pywin32 (Windows window frame), psutil (telemetry), pydantic, dolt (Beads)
**Providers**: Gemini API, Anthropic API, DeepSeek, Gemini CLI (headless), MiniMax
**Platform**: Windows (PowerShell) — single developer, local use

![img](./gallery/python_2026-06-10_19-59-16.png)

---

## Key Features

### Multi-Provider Integration
- **Gemini SDK**: Server-side context caching with TTL management, automatic cache rebuilding at 90% TTL
- **Anthropic**: Ephemeral prompt caching with 4-breakpoint system, automatic history truncation at 180K tokens
- **DeepSeek**: Dedicated SDK for code-optimized reasoning
- **Gemini CLI**: Headless adapter with full functional parity, synchronous HITL bridge
- **MiniMax**: Alternative provider support

### 4-Tier MMA Orchestration
Hierarchical task decomposition with specialized models and strict token firewalling:
- **Tier 1 (Orchestrator)**: Product alignment, epic → tracks
- **Tier 2 (Tech Lead)**: Track → tickets (DAG), persistent context
- **Tier 3 (Worker)**: Stateless TDD implementation, context amnesia
- **Tier 4 (QA)**: Stateless error analysis, no fixes

### Strict Human-in-the-Loop (HITL)
- **Execution Clutch**: All destructive actions suspend on `threading.Condition` pending GUI approval
- **Three Dialog Types**: ConfirmDialog (scripts), MMAApprovalDialog (steps), MMASpawnApprovalDialog (workers)
- **Editable Payloads**: Review, modify, or reject any AI-generated content before execution

### 45 MCP Tools with Sandboxing
Three-layer security model: Allowlist Construction → Path Validation → Resolution Gate
- **File I/O**: read, list, search, slice, edit, tree
- **AST-Based (Python)**: skeleton, outline, definition, signature, class summary, docstring, var declaration, hierarchy, imports, syntax check, find usages
- **AST-Based (C/C++)**: tree-sitter powered skeleton, outline, definition, signature, and surgical update tools for C and C++
- **File Editing**: surgical string match (`edit_file`) preserving indentation and line endings
- **Analysis**: summary, git diff, find usages, imports, syntax check, hierarchy, derive code path
- **Network**: web search, URL fetch (dependency-free, stdlib only)
- **Runtime**: UI performance metrics
- **Beads**: bd_create, bd_list, bd_ready, bd_update for Dolt-backed issue tracking

See [docs/guide_tools.md](./docs/guide_tools.md) for the full inventory.

### Parallel Tool Execution
Multiple independent tool calls within a single AI turn execute concurrently via `asyncio.gather`, significantly reducing latency.

### AST-Based Context Management
- **Skeleton View**: Signatures + docstrings, bodies replaced with `...`
- **Curated View**: Preserves `@core_logic` decorated functions and `[HOT]` comment blocks
- **Targeted View**: Extracts only specified symbols and their dependencies
- **Heuristic Summaries**: Token-efficient structural descriptions without AI calls

---

## 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)).

### Test Coverage

The project has **273 test files** with 98.9% pass rate (272/273 in the latest batched run; the 1 failure is a pre-existing flake in `test_rag_phase4_stress` that passes in isolation). Most failures are caught and fixed via the 4-tier MMA test-harden track system. See [docs/guide_testing.md](./docs/guide_testing.md) for the full testing contract.

---

## Documentation

| Guide | Scope |
|---|---|
| [Readme](./docs/Readme.md) | Documentation index, GUI panel reference, configuration files, environment variables |
| [Architecture](./docs/guide_architecture.md) | Threading model, event system, AI client multi-provider architecture (Gemini, Anthropic, DeepSeek, Gemini CLI, MiniMax), HITL mechanism, comms logging, RAG integration, Tier 4 patch flow |
| [Tools & IPC](./docs/guide_tools.md) | MCP Bridge 3-layer security, 45-tool inventory, Hook API endpoints, ApiHookClient reference, shell runner, Beads tools |
| [MMA Orchestration](./docs/guide_mma.md) | 4-tier hierarchy, Ticket/Track/WorkerContext data structures, DAG engine, ConductorEngine, worker lifecycle, persona application, abort propagation |
| [Simulations](./docs/guide_simulations.md) | `live_gui` fixture, Puppeteer pattern, mock provider, visual verification, test areas by subsystem, headless service |
| [Context Curation](./docs/guide_context_curation.md) | AST masking, fuzzy anchor slices, structural file editor, view presets, history snapshotting |
| [Shaders & Window](./docs/guide_shaders_and_window.md) | Hybrid shader injection, custom window frame, NERV theme effects |
| [Themes](./docs/guide_themes.md) | TOML-based theming, `[colors]` table, 4-syntax-palette upstream limit, `load_themes_from_disk` / `apply_syntax_palette` API, color-callable convention |
| [Meta-Boundary](./docs/guide_meta_boundary.md) | Application vs Meta-Tooling domains, inter-domain bridges, cross-tool abstractions |

---

## Subsystem Index

| Subsystem | Guide | Primary Module(s) |
|---|---|---|
| Multi-provider LLM client | [Architecture](./docs/guide_architecture.md#ai-client-multi-provider-architecture) | `src/ai_client.py` |
| 4-Tier MMA orchestration | [MMA](./docs/guide_mma.md) | `src/multi_agent_conductor.py`, `src/dag_engine.py` |
| DAG engine & ticket lifecycle | [MMA](./docs/guide_mma.md#dag-engine-dag_enginepy) | `src/dag_engine.py` |
| MCP tools & Hook API | [Tools & IPC](./docs/guide_tools.md) | `src/mcp_client.py`, `src/api_hooks.py` |
| Execution Clutch (HITL) | [Architecture](./docs/guide_architecture.md#the-execution-clutch-human-in-the-loop) | `src/app_controller.py` |
| Context composition & aggregation | [Context Curation](./docs/guide_context_curation.md) | `src/aggregate.py`, `src/file_cache.py` |
| AST inspection & slicing | [Context Curation](./docs/guide_context_curation.md#granular-ast-control) | `src/file_cache.py`, `src/fuzzy_anchor.py` |
| Personas (unified profiles) | *See [guide_mma.md](./docs/guide_mma.md#persona-application); dedicated guide pending* | `src/personas.py` |
| Tool bias engine | *See [guide_tools.md](./docs/guide_tools.md); dedicated guide pending* | `src/tool_bias.py` |
| RAG (Retrieval-Augmented Generation) | *See [guide_architecture.md](./docs/guide_architecture.md#rag-integration); dedicated guide pending* | `src/rag_engine.py` |
| Beads mode (Dolt issue tracking) | *See [guide_tools.md](./docs/guide_tools.md#beads-tools); dedicated guide pending* | `src/beads_client.py` |
| Hot reload (state-preserving) | *Dedicated guide pending* | `src/hot_reloader.py` |
| Discussion metrics & compression | [Architecture](./docs/guide_architecture.md#discussion-compression) | `src/ai_client.py` |
| Test infrastructure & simulations | [Simulations](./docs/guide_simulations.md) | `tests/conftest.py`, `simulation/` |
| Headless service (FastAPI) | [Simulations](./docs/guide_simulations.md#headless-service-tests) | `src/api_hooks.py` |
| NERV theme & visual effects | [Shaders & Window](./docs/guide_shaders_and_window.md#4-nerv-theme-effects) | `src/theme_nerv.py`, `src/theme_nerv_fx.py` |
| TOML theme system (palette + syntax) | [Themes](./docs/guide_themes.md) | `src/theme_2.py`, `src/theme_models.py` |
| Custom window frame | [Shaders & Window](./docs/guide_shaders_and_window.md#2-custom-window-frame-strategy) | `src/gui_2.py` |
| Workspace profiles (docking layouts) | *Dedicated guide pending* | `src/workspace_manager.py` |
| History (undo/redo) | [Context Curation](./docs/guide_context_curation.md#context-snapshotting-per-take) | `src/history.py` |
| External MCP integration | [Tools & IPC](./docs/guide_tools.md#external-mcp-integration) | `src/mcp_client.py` |
| Telemetry & performance monitoring | [Architecture](./docs/guide_architecture.md#telemetry--auditing) | `src/performance_monitor.py` |
| Session logging | [Tools & IPC](./docs/guide_tools.md#session-logging) | `src/session_logger.py` |
| MMA dashboard & node editor | [MMA](./docs/guide_mma.md) | `src/gui_2.py:_render_mma_dashboard` |
| Cross-tool abstractions (conductor) | [Meta-Boundary](./docs/guide_meta_boundary.md#the-cross-tool-abstractions) | `conductor/` |

Subsystems marked "dedicated guide pending" are slated for dedicated `docs/guide_*.md` files in upcoming docs work. For now, their details live inline in the guides listed under [Documentation](#documentation) above.

---

## 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"

[minimax]
api_key = "YOUR_KEY"
```

Each provider's key is loaded by the corresponding `_ensure_<provider>_client()` in `src/ai_client.py`. The `credentials.toml` is **blacklisted** by the MCP allowlist — AI tools cannot read it under any circumstance.

### Running

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

### Running Tests

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

> **Note:** See the [Structural Testing Contract](./docs/guide_simulations.md#structural-testing-contract) for rules regarding mock patching, `live_gui` standard usage, and artifact isolation (logs are generated in `tests/logs/` and `tests/artifacts/`).

---

## MMA 4-Tier Architecture

The Multi-Model Agent system uses hierarchical task decomposition with specialized models at each tier:

| Tier | Role | Model | Responsibility |
|------|------|-------|----------------|
| **Tier 1** | Orchestrator | `gemini-3.1-pro-preview` | Product alignment, epic → tracks, track initialization |
| **Tier 2** | Tech Lead | `gemini-3-flash-preview` | Track → tickets (DAG), architectural oversight, persistent context |
| **Tier 3** | Worker | `gemini-2.5-flash-lite` / `deepseek-v3` | Stateless TDD implementation per ticket, context amnesia |
| **Tier 4** | QA | `gemini-2.5-flash-lite` / `deepseek-v3` | Stateless error analysis, diagnostics only (no fixes) |

**Key Principles:**
- **Context Amnesia**: Tier 3/4 workers start with `ai_client.reset_session()` — no history bleed
- **Token Firewalling**: Each tier receives only the context it needs
- **Model Escalation**: Failed tickets automatically retry with more capable models
- **WorkerPool**: Bounded concurrency (default: 4 workers) with semaphore gating

---

## Module by Domain

### src/ — Core implementation (53 modules)

| File | Role |
|---|---|
| `src/gui_2.py` | Primary ImGui interface — App class, frame-sync, HITL dialogs, event system |
| `src/app_controller.py` | Headless controller; bridges GUI and async AI workers |
| `src/ai_client.py` | Multi-provider LLM abstraction (Gemini, Anthropic, DeepSeek, MiniMax) |
| `src/mcp_client.py` | 45 MCP tools + `run_powershell` (canonical 46 in `models.AGENT_TOOL_NAMES`); 3-layer filesystem security and tool dispatch |
| `src/api_hooks.py` | HookServer — REST API on `127.0.0.1:8999` for external automation |
| `src/api_hook_client.py` | Python client for the Hook API (used by tests and external tooling) |
| `src/multi_agent_conductor.py` | ConductorEngine — Tier 2 orchestration loop with DAG execution |
| `src/dag_engine.py` | TrackDAG (dependency graph) + ExecutionEngine (tick-based state machine) |
| `src/models.py` | Ticket, Track, WorkerContext, Metadata, Persona, WorkspaceProfile, etc. |
| `src/events.py` | EventEmitter, AsyncEventQueue, UserRequestEvent |
| `src/project_manager.py` | TOML config persistence, discussion management, track state |
| `src/session_logger.py` | JSON-L + markdown audit trails (comms, tools, CLI, hooks) |
| `src/rag_engine.py` | RAG subsystem (ChromaDB + embedding providers) |
| `src/beads_client.py` | Beads/Dolt-backed issue tracking client |
| `src/hot_reloader.py` | State-preserving module reloader |
| `src/personas.py` | Unified agent profile manager |
| `src/presets.py` | System prompt preset manager |
| `src/context_presets.py` | Context composition preset manager |
| `src/tool_presets.py` | Tool preset manager |
| `src/tool_bias.py` | Tool bias engine (semantic nudging + dynamic strategy) |
| `src/command_palette.py` | Command palette + fuzzy matcher + registry |
| `src/commands.py` | 33 registered commands (toggle, theme, layout, AI, project, tools) |
| `src/workspace_manager.py` | Workspace profile save/load with scope inheritance |
| `src/theme_2.py` | Theme system (palette/font/etc.) |
| `src/theme_nerv.py` | NERV Tactical Console theme |
| `src/theme_nerv_fx.py` | NERV FX (scanlines, flicker, alert) |
| `src/shell_runner.py` | PowerShell execution with 60s timeout, env config, qa_callback + patch_callback for Tier 4 QA |
| `src/file_cache.py` | ASTParser (tree-sitter) — skeleton, curated, targeted views |
| `src/fuzzy_anchor.py` | Fuzzy anchor slice algorithm |
| `src/history.py` | Undo/redo HistoryManager with UISnapshot |
| `src/imgui_scopes.py` | ImGui context managers (imscope) for the UI delegation pattern |
| `src/performance_monitor.py` | FPS, frame time, CPU, input lag tracking |
| `src/log_registry.py` | Session metadata persistence |
| `src/log_pruner.py` | Automated log cleanup based on age and whitelist |
| `src/paths.py` | Centralized path resolution with environment variable overrides |
| `src/cost_tracker.py` | Token cost estimation for API calls |
| `src/gemini_cli_adapter.py` | CLI subprocess adapter with session management |
| `src/mma_prompts.py` | Tier-specific system prompts for MMA orchestration |
| `src/summarize.py` | Heuristic file summaries (imports, classes, functions) |
| `src/outline_tool.py` | Hierarchical code outline via stdlib `ast` |
| `src/summary_cache.py` | SHA256-keyed summary LRU cache |
| `src/markdown_helper.py` | Markdown rendering helpers |
| `src/patch_modal.py` | Patch approval modal |
| `src/diff_viewer.py` | Diff rendering |
| `src/external_editor.py` | External editor integration (VSCode, etc.) |
| `src/orchestrator_pm.py` | Orchestrator project manager |
| `src/conductor_tech_lead.py` | Tier 2 ticket generation from track briefs |
| `src/synthesis_formatter.py` | Multi-take synthesis |
| `src/thinking_parser.py` | AI thinking-trace extraction |

Simulation modules in `simulation/`:
| File | Role |
|---|--- |
| `simulation/sim_base.py` |       BaseSimulation class with setup/teardown lifecycle |
| `simulation/workflow_sim.py` |       WorkflowSimulator — high-level GUI automation |
| `simulation/user_agent.py` |        UserSimAgent — simulated user behavior (reading time, thinking delays) |

---

## Setup
The MCP Bridge implements a three-layer security model in `mcp_client.py`:

Every tool accessing the filesystem passes through `_resolve_and_check(path)` before any I/O.

### Layer 1: Allowlist Construction (`configure`)
Called by `ai_client` before each send cycle:
1. Resets `_allowed_paths` and `_base_dirs` to empty sets
2. Sets `_primary_base_dir` from `extra_base_dirs[0]`
3. Iterates `file_items`, resolving paths, adding to allowlist
4. Blacklist check: `history.toml`, `*_history.toml`, `config.toml`, `credentials.toml` are NEVER allowed

### Layer 2: Path Validation (`_is_allowed`)
Checks run in order:
1. **Blacklist**: `history.toml`, `*_history.toml` → hard deny
2. **Explicit allowlist**: Path in `_allowed_paths` → allow
3. **CWD fallback**: If no base dirs, allow `cwd()` subpaths
4. **Base containment**: Must be subpath of `_base_dirs`
5. **Default deny**: All other paths rejected

### Layer 3: Resolution Gate (`_resolve_and_check`)
1. Convert raw path string to `Path`
2. If not absolute, prepend `_primary_base_dir`
3. Resolve to absolute (follows symlinks)
4. Call `_is_allowed()`
5. Return `(resolved_path, "")` on success or `(None, error_message)` on failure

All paths are resolved (following symlinks) before comparison, preventing symlink-based traversal attacks.

### Security Model

The MCP Bridge implements a three-layer security model in `mcp_client.py`. Every tool accessing the filesystem passes through `_resolve_and_check(path)` before any I/O.

### Layer 1: Allowlist Construction (`configure`)
Called by `ai_client` before each send cycle:
1. Resets `_allowed_paths` and `_base_dirs` to empty sets.
2. Sets `_primary_base_dir` from `extra_base_dirs[0]` (resolved) or falls back to cwd().
3. Iterates `file_items`, resolving each path to an absolute path, adding to `_allowed_paths`; its parent directory is added to `_base_dirs`.
4. Any entries in `extra_base_dirs` that are valid directories are also added to `_base_dirs`.

### Layer 2: Path Validation (`_is_allowed`)
Checks run in this exact order:
1. **Blacklist**: `history.toml`, `*_history.toml`, `config`, `credentials` → hard deny
2. **Explicit allowlist**: Path in `_allowed_paths` → allow
7. **CWD fallback**: If no base dirs, any under `cwd()` is allowed (fail-safe for projects without explicit base dirs)
8. **Base containment**: Must be a subpath of at least one entry in `_base_dirs` (via `relative_to()`)
9. **Default deny**: All other paths rejected
All paths are resolved (following symlinks) before comparison, preventing symlink-based traversal attacks.

### Layer 3: Resolution Gate (`_resolve_and_check`)
Every tool call passes through this:
1. Convert raw path string to `Path`.
2. If not absolute, prepend `_primary_base_dir`.
3. Resolve to absolute.
4. Call `_is_allowed()`.
5. Return `(resolved_path, "")` on success, `(None, error_message)` on failure
All paths are resolved (following symlinks) before comparison, preventing symlink-based traversal attacks.

---

## Conductor SystemThe project uses a spec-driven track system in `conductor/` for structured development:

```
conductor/
├── workflow.md           # Task lifecycle, TDD protocol, phase verification
├── tech-stack.md         # Technology constraints and patterns
├── product.md            # Product vision and guidelines
├── product-guidelines.md # Code standards, UX principles
└── tracks/
    └── <track_name>_<YYYYMMDD>/
        ├── spec.md       # Track specification
        ├── plan.md       # Implementation plan with checkbox tasks
        ├── metadata.json # Track metadata
        └── state.toml    # Structured state with task list
```

**Key Concepts:**
- **Tracks**: Self-contained implementation units with spec, plan, and state
- **TDD Protocol**: Red (failing tests) → Green (pass) → Refactor
- **Phase Checkpoints**: Verification gates with git notes for audit trails
- **MMA Delegation**: Tracks are executed via the 4-tier agent hierarchy

See `conductor/workflow.md` for the full development workflow.

---

## 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
```

---

## Quick Reference

### Hook API Endpoints (port 8999)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/status` | GET | Health check |
| `/api/project` | GET/POST | Project config |
| `/api/session` | GET/POST | Discussion entries |
| `/api/gui` | POST | GUI task queue |
| `/api/gui/mma_status` | GET | Full MMA state |
| `/api/gui/value/<tag>` | GET | Read GUI field |
| `/api/ask` | POST | Blocking HITL dialog |

### MCP Tool Categories

| Category | Tools |
|----------|-------|
| **File I/O** | `read_file`, `list_directory`, `search_files`, `get_tree`, `get_file_slice`, `set_file_slice`, `edit_file` |
| **AST (Python)** | `py_get_skeleton`, `py_get_code_outline`, `py_get_definition`, `py_update_definition`, `py_get_signature`, `py_set_signature`, `py_get_class_summary`, `py_get_var_declaration`, `py_set_var_declaration`, `py_get_docstring` |
| **Analysis** | `get_file_summary`, `get_git_diff`, `py_find_usages`, `py_get_imports`, `py_check_syntax`, `py_get_hierarchy` |
| **Network** | `web_search`, `fetch_url` |
| **Runtime** | `get_ui_performance` |

---
