MadCop

A local-first AI agent desktop workstation.

MadCop is a cross-platform desktop application that brings the power of modern LLMs into a private, agentic workflow. It runs as a single Electron binary on macOS, Windows, and Linux, talks to any OpenAI-compatible API endpoint, and keeps your conversations, files, and knowledge base entirely on your machine. No cloud lock-in, no per-seat fees, no data leaving the device.

This document explains the why behind the major design decisions — written for product managers and reviewers who want to understand how the system is put together, not just a list of features.

Preview

What problem is MadCop solving?

The dominant LLM desktop clients (ChatGPT, Claude.ai, Gemini) are excellent chat surfaces but they assume a specific shape of interaction: one human, one model, one conversation at a time, with vendor-managed tools and memory. That works for "answer this question" but it does not work for "I need to (a) search the web, (b) read a local file, (c) summarise the result, (d) save a Markdown report to disk" — which is a normal afternoon for a product manager, analyst, or engineer.

MadCop is built around three observations:

1. The work is multi-step. A single useful task almost always needs several LLM calls with intermediate state. A chat that cannot sequence, branch, persist, or call external tools caps you at "Q&A on a webpage".
2. The data is local. A working file directory, a Notion export, a git history, screenshots, contracts — the substance of real work sits on the user's disk. A client that can only attach a single file per message (or pays per-token for cloud RAG) punishes the people who already have the answer.
3. The model is a choice, not a vendor. A senior engineer might need different models for different tasks — one for refactoring code, another for Chinese-language analysis. A privacy-sensitive user wants a self-hosted endpoint. A startup wants to A/B-test cost. A single-vendor client forces that decision at sign-up and never lets you revisit it.

So the design goal is: a thin local shell that lets the user pick their own model, hand it their own files, and let the system orchestrate the rest. Everything else is in service of that.

How is the system structured?

┌─────────────────────────────────────────────────────────┐
│                    Electron Shell                       │
│  ┌────────────────────┐   ┌────────────────────────┐  │
│  │  Vue 3 + Pinia +   │   │   Python Backend       │  │
│  │  Tailwind v4 UI    │   │   (FastAPI + Uvicorn)  │  │
│  │  (Renderer Process)│←→│                         │  │
│  └────────────────────┘   │  ┌──────────────────┐  │  │
│                            │  │  LLM Client       │  │  │
│  ┌────────────────────┐   │  │  (OpenAI Compat)  │  │  │
│  │  Workspace Picker  │   │  └──────────────────┘  │  │
│  │  Sidebar / Tabs    │   │  ┌──────────────────┐  │  │
│  │  Chat / Composer   │   │  │  Tool Registry    │  │  │
│  └────────────────────┘   │  │  + MCP Bridge      │  │  │
│                            │  └──────────────────┘  │  │
│                            │  ┌──────────────────┐  │  │
│                            │  │  Workflow Engine  │  │  │
│                            │  │  + Agent Modes    │  │  │
│                            │  └──────────────────┘  │  │
│                            │  ┌──────────────────┐  │  │
│                            │  │  Memory Pipeline  │  │  │
│                            │  │  (5-tier)         │  │  │
│                            │  └──────────────────┘  │  │
│                            └────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

The architecture is intentionally two processes talking over HTTP — not one big monolith — for three reasons:

1. The Python backend can be deployed headless. The same madcop.server module runs without Electron (over plain HTTP/WebSocket) for CI, scripting, or embedding in other tools.
2. The Vue renderer is portable. Tauri, Web, or a custom shell can reuse the frontend as-is because it never assumes anything about the backend's runtime.
3. Process isolation protects the user. A misbehaving tool call cannot freeze the UI; the renderer survives a hung request and can cancel it.

How does model routing work?

Routing is the single most important design question in any LLM client. MadCop routes on three axes simultaneously:

Axis 1: Per-request model selection

The user configures one or more model providers in the Settings panel. Each provider is a name + base URL + API key + model id (any OpenAI-compatible endpoint). The frontend exposes the active provider as a useSettingsStore.currentModel ref; the backend receives a model field on every POST /api/chat and forwards it to the OpenAI-compatible client.

This means there is no "default model" hard-coded in the backend. If you don't configure one, you get a clear error on the first request. The model lives in user data, not in the product.

Axis 2: Per-session tool registry

Different models from different vendors have wildly different tool-use quality. The backend's tool dispatcher handles this by tuning the system prompt per model family. The backend's tool dispatcher (madcop/tools/registry.py) registers the same toolset regardless of model, but the system prompt is tuned to nudge the model toward emitting function calls. Specifically, every chat request includes an explicit instruction:

"When the user asks you to do anything that requires real-time information, you MUST call the web_search tool. Do not make up answers. Call the tool directly — do not output the tool's parameter description."

This works around the most common failure mode of self-hosted Chinese-tuned models (outputting the JSON schema as text instead of as a structured tool_calls array).

Axis 3: Intent classification → execution mode

A single chat turn can be either "answer this" (one LLM call) or "search the web, read a file, write a report" (many LLM calls with tool side effects). Rather than exposing a dozen graph presets, MadCop collapses this into one unified four-way mode selector that simultaneously picks the workflow and the reasoning effort:

This replaces the earlier EffortSelector (a standalone low/medium/high picker) and a defunct "R Act 推理" button — the two were conflated and users could not tell them apart. The selector lives in the composer bar; the old effort control is demoted to a node-config panel in the topology editor for advanced users.

Routing (auto). When the user leaves the selector on auto, the backend's task router (madcop/agent_network/task_router.py) classifies the input with pure keyword analysis, checking in priority order: deep patterns (重构 / 架构 / 代码审查 / 前端.*后端) → quick patterns (什么是 / 语法 / 怎么写) → standard action verbs (修复 / 添加 / 实现 / 测试), with a short-text fast path (<15 chars, no action verb → quick). The /api/agent/route endpoint returns the decision plus a human-readable reason ("匹配 2 个复杂任务模式"), so the UI can show why a mode was chosen.

Execution. The three non-auto modes are real engines, not prompts:

• quick → one client.chat() call, streamed as text.
• standard → madcop/agent_network/react_engine.py runs a bounded ReAct loop (default 10 steps) that dispatches tool calls through the shared ToolRegistry and streams each Thought / Action / Observation as an SSE event.
• deep → madcop/agent_network/engine.py builds a multi-agent DAG and walks it with graphlib topological sort + parallel waves; each node is an agent (planner → coder → reviewer) whose output feeds the next wave.

All three are mounted inside /api/chat behind an agent_mode field, and each engine's output is mapped onto the existing text / tool / tool_result / reasoning / done event vocabulary — so the frontend's SSE parser and the existing ToolCallBlock / ToolResultBlock / ThinkingBlock render the steps with no special-casing.

How are tools registered and dispatched?

The tool system is the surface where "agent" stops being marketing and becomes real. MadCop's design is a single registry that everything reads from, with three extension points:

1. Built-in tools — registered in madcop/tools/__init__.py::default_registry(). These include:

   • web_search (DuckDuckGo, no API key needed)
   • web_fetch (httpx + BeautifulSoup-style HTML→text)
   • read_file / write_file / edit_file (path-confined to allowlisted dirs)
   • weather (wttr.in, no key)
   • clarify (returns a structured question back to the user)

2. MCP servers — any external Model Context Protocol server can be registered at sta