Turn an AI conversation into a real software-engineering workflow.
A local-first agent runtime that gives existing AI assistants a controlled connection to your development environment.
GitHub · Documentation · Architecture · Security
Modern AI assistants are excellent at reasoning, writing code, and debugging. The missing piece is direct, controlled access to the real development environment.
Normally, the workflow looks like this:
AI writes code
↓
You copy it
↓
You edit files
↓
You run commands
↓
You copy errors back
↓
AI reasons again
Mediator removes that manual handoff.
┌─────────────────────┐
│ AI / AI CLIENT │
│ ChatGPT · Claude · │
│ Cursor · Gemini... │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ MEDIATOR │
│ Agent Runtime │
│ State · Security │
│ Context · Tools │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ LOCAL COMPUTER │
│ Files · Terminal │
│ Git · Tests · Apps │
└─────────────────────┘
The core idea is simple:
AI thinks → Mediator orchestrates → Computer executes.
The AI remains the reasoning layer. Mediator becomes the controlled execution layer between intelligence and the local machine.
Mediator is not another AI model.
It is infrastructure for connecting existing AI intelligence to real software-engineering execution.
That means an AI can move through an engineering loop such as:
Understand
↓
Inspect
↓
Plan
↓
Edit
↓
Execute
↓
Test
↓
Observe failure
↓
Reason
↓
Fix
↓
Retest
↓
Verify
↓
Complete
Instead of repeatedly asking the developer to move information between the AI and terminal, Mediator provides the execution bridge.
Mediator is designed around the Model Context Protocol, supporting local MCP connectivity through stdio and Streamable HTTP.
This makes it possible to connect the runtime to AI development environments and clients that understand MCP.
Mediator can orient itself inside an unfamiliar repository instead of blindly reading files.
- Ranked repository mapping
- Symbol discovery
- File and directory inspection
- Git history and status
- Structured project context
The runtime exposes controlled tools for the operations an engineering agent actually needs:
- Filesystem operations
- Terminal commands
- Git operations
- Test execution
- Process management
- Repository inspection
- Symbol discovery
- Workspace checkpoints
Tests are not treated as an opaque wall of terminal output.
Mediator can detect supported test frameworks and return structured failure information such as:
Test
File
Line
Message
Relevant output
That gives the AI useful debugging context instead of forcing it to interpret an entire raw terminal log.
Local execution is powerful, so Mediator treats the execution boundary as a first-class security surface.
The runtime includes mechanisms for:
- Workspace-bounded operations
- Permission-aware tool execution
- Controlled command execution
- Process isolation
- Prompt-injection defense scanning
- Audit-oriented execution state
- Shadow Git checkpoints
The goal is not to give an AI unrestricted shell access and hope for the best.
The goal is to create a controlled execution boundary.
Long-running processes, command output, process trees, and execution state are handled as runtime concerns rather than one-off shell calls.
On Windows, Mediator uses process-management primitives such as Job Objects to improve process-tree cleanup and isolation.
At a high level:
USER
│
▼
┌───────────────────┐
│ AI INTERFACE │
│ ChatGPT / Claude │
│ Cursor / MCP ... │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ BROWSER / CLIENT │
│ BRIDGE │
└─────────┬─────────┘
│
▼
╔════════════════════════════════╗
║ MEDIATOR ║
║ ║
║ Transport ║
║ ↓ ║
║ Protocol ║
║ ↓ ║
║ Security Broker ║
║ ↓ ║
║ Agent / Session Runtime ║
║ ↓ ║
║ Context + Planning ║
║ ↓ ║
║ Tool Registry + Executor ║
╚══════════════╤═════════════════╝
│
┌──────────────┼──────────────┐
▼ ▼ ▼
Filesystem Terminal Git
│ │ │
└──────────────┼──────────────┘
▼
Tests / Apps
│
▼
Tool Result
│
▼
AI
For the detailed architecture, see docs/04_SYSTEM_ARCHITECTURE.md.
The project is intentionally built around a simple separation of responsibilities:
| Layer | Responsibility |
|---|---|
| AI | Intelligence, reasoning, planning, coding, debugging |
| Mediator | Orchestration, state, security, context, execution |
| Tools | Filesystem, terminal, Git, tests, processes |
| Project Context | Repository structure, symbols, history |
| Client / Extension | Bridge between the AI interface and Mediator |
| User | Direction, approval, and control |
This separation is one of the core architectural principles of the project.
- Python 3.13+
ripgrepavailable onPATH(for fast code search and symbols)- Node.js 18+ (for developing or building the React dashboard)
- Git
- A supported MCP-capable AI client (Claude Desktop, Cursor, etc.) or the Mediator Chrome extension
git clone https://github.com/codeseeboy/Mediator-code.git
cd Mediator-codeYou can use either uv (recommended) or standard pip:
Using uv:
# Sync environment with dependencies
uv syncUsing pip / virtual environment:
python -m venv .venv
# On Windows: .venv\Scripts\activate
# On macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"The React frontend ships inside the Python package in mediator/ui/dist:
cd ui
npm install
npm run build
cd ..Verify your installation by running the automated tests:
uv run pytest
# or: pytestRun the Mediator runtime server bound to loopback:
uv run mediator --workspace .
# or: python -m mediator --workspace .The control center dashboard will be live at:
👉 http://127.0.0.1:8765/
For Claude Desktop, Cursor, Cline, or other MCP stdio clients:
uv run mediator-mcp
# or: mediator-mcpSee
docs/16_MCP_INTEGRATION.mdanddocs/17_MCP_QUICKSTARTS.mdfor ready-to-use client configuration snippets.
- Open Chrome and navigate to
chrome://extensions. - Enable Developer mode in the top-right corner.
- Click Load unpacked and select the
extension/directory. - Open the extension popup, ensure it connects to
ws://127.0.0.1:8765/ws, and start collaborating!
Mediator/
│
├── mediator/ # Core local agent runtime (Python)
│ ├── agent/ # Agent runtime, session registry, loops & directives
│ ├── context/ # Repository map, PageRank scoring, primer & activity
│ ├── events/ # Event bus and state transitions
│ ├── mcp/ # MCP Streamable HTTP, stdio & WebMCP bridge
│ ├── protocol/ # Typed message definitions and envelopes
│ ├── security/ # Security broker, permissions & execution policies
│ ├── tools/ # Tool implementations (terminal, filesystem, git, tests, processes)
│ └── ui/dist/ # Built static assets for the React control center
│
├── ui/ # Control center frontend source (React 18 + TypeScript + Vite)
│
├── extension/ # Chrome browser extension (Manifest V3)
│ ├── background/ # Service worker & background bridge
│ ├── content/ # Web content parsers & provider bridges
│ ├── protocol/ # Browser-side message handling
│ └── ui/ # Extension popup interface
│
├── tests/ # 685+ automated unit and integration tests
│
├── docs/ # Comprehensive architecture, security, and design specs
│ ├── 00_COMPLETE_DOCUMENTATION.md
│ ├── 04_SYSTEM_ARCHITECTURE.md
│ ├── 08_SECURITY_SPECIFICATION.md
│ └── Importants/ # Extension specs & blueprints
│
├── scripts/ # E2E test harnesses and automation scripts
│
├── pyproject.toml # Python package build definition (PEP 621 / hatchling)
├── uv.lock # Deterministic dependency lockfile
└── README.md # Project documentation entry point
The repository contains a detailed engineering documentation set covering the product from concept through implementation.
docs/00_COMPLETE_DOCUMENTATION.md— complete project referencedocs/01_PRODUCT_DEFINITION.md— product vision and scopedocs/02_PRD.md— product requirementsdocs/03_SRS.md— software requirementsdocs/04_SYSTEM_ARCHITECTURE.md— system architecturedocs/05_AGENT_PROTOCOL.md— agent protocoldocs/06_TOOL_SPECIFICATION.md— tool contractsdocs/08_SECURITY_SPECIFICATION.md— security modeldocs/10_UX_SPECIFICATION.md— UX architecturedocs/15_MEDIATOR_V2_ROADMAP.md— current V2 roadmapdocs/16_MCP_INTEGRATION.md— MCP integrationdocs/17_MCP_QUICKSTARTS.md— MCP setup guidesdocs/18_M5_IDE_RUNTIME.md— IDE/runtime direction
Mediator is being built around a few non-negotiable principles:
Local-first
The execution runtime lives close to the developer's machine and projects.
AI-agnostic
The runtime should not depend on a single model provider for its intelligence layer.
Controlled execution
Tools should have explicit boundaries instead of unrestricted access.
Observable execution
The user and AI should be able to understand what is happening and why.
Stateful engineering loops
The runtime should preserve enough execution context to support real multi-step work.
Verification over assumption
A successful file write is not the same thing as a working feature. Builds, tests, health checks and process state matter.
Modular evolution
Transport, protocol, security, tools, context and UI should evolve independently where possible.
Mediator is not trying to replace every AI coding tool with another model or another chat interface.
It is an execution and coordination layer.
The core proposition is:
Use the AI you already trust. Give it a controlled way to work with the computer you already use.
That distinction is central to the project.
Mediator is an actively evolving engineering project.
The repository already contains the core runtime architecture, MCP integration, tool system, context layer, security components, browser integration, UI work and an extensive automated test suite. Some integrations and higher-level agent capabilities are still evolving.
For the most accurate implementation status, see docs/15_MEDIATOR_V2_ROADMAP.md.
Mediator is being developed as an open-source project and contributions are welcome.
Before making substantial changes, start with:
docs/01_PRODUCT_DEFINITION.mddocs/04_SYSTEM_ARCHITECTURE.mddocs/05_AGENT_PROTOCOL.mddocs/06_TOOL_SPECIFICATION.mddocs/13_DECISIONS.mddocs/15_MEDIATOR_V2_ROADMAP.md
The project is large enough that understanding the architecture before changing a subsystem will save time.
Mediator executes operations against real development environments. Treat security as part of the product, not an optional feature.
If you discover a security issue, please avoid publishing sensitive exploit details in a public issue until the issue has been responsibly assessed.
See docs/08_SECURITY_SPECIFICATION.md for the project's security model.
Mediator is released under a Source-Available Non-Commercial & Anti-Plagiarism License.
- You are welcome to inspect, build, and use this software locally for personal, educational, and evaluation purposes.
- Re-branding, re-publishing, commercial exploitation, or claiming ownership of this architecture or implementation is strictly prohibited.
See LICENSE for the full legal terms.
Mediator
AI intelligence. Local execution. One engineering loop.