Skip to main content
Glama
README.md
<div align="center">

<h1>Tandem MCP</h1>

<img src="assets/logo.svg" alt="Tandem MCP logo: a tandem bicycle, two riders on one frame" width="360">

<p><strong>Your cloud AI plans. Your local AI executes. Tandem verifies.</strong></p>

<p>
  <a href="https://github.com/ALENOC/tandem-mcp/releases"><img src="https://img.shields.io/github/v/release/ALENOC/tandem-mcp" alt="GitHub Release"></a>
  <a href="https://github.com/ALENOC/tandem-mcp/actions/workflows/tests.yml"><img src="https://github.com/ALENOC/tandem-mcp/actions/workflows/tests.yml/badge.svg" alt="CI"></a>
  <a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
</p>

<p><strong>Delegate locally. Verify deterministically. Keep control.</strong></p>

</div>

Tandem MCP is an MCP server that pairs a cloud AI orchestrator (Claude Code, Codex, Gemini) with a local OpenAI-compatible LLM (LM Studio, Ollama, llama.cpp, vLLM). The cloud model keeps architectural decisions and final review; the local model reads large files and executes bounded edits while Tandem enforces contracts, runs checks, verifies quotes, and enables rollback.

---

## Architecture: How Tandem Works

<p align="center">
  <img src="assets/architecture.svg" width="720" alt="Tandem MCP Architecture: Cloud AI Orchestrator -> Tandem MCP Server -> Local AI Executor">
</p>

1. **Plan:** The cloud orchestrator decides what to read or delegate and sets explicit contract limits.
2. **Execute:** Tandem sends a bounded task to the local model inside a confined workspace.
3. **Verify:** Tandem runs syntax checks, acceptance tests, and lexical quote/number verification.
4. **Review:** The orchestrator inspects `job_evidence` or `job_diff` and accepts (`job_feedback`) or restores (`job_rollback`).

The local model does not receive unrestricted control over the machine. Actual isolation strength depends on configuration and platform (Bubblewrap on Linux vs command-text checks in compatibility mode).

Learn more -> [Architecture](docs/ARCHITECTURE.md) ([English PDF](docs/tandem-mcp-architecture.pdf) · [Italian PDF](docs/tandem-mcp-architettura.pdf))

---

## Why Tandem MCP?

- **Save cloud context:** The local model reads large files, logs, and docs, returning only verified answers and quotes.
- **Controlled delegation:** Tasks are bounded by contracts, writable globs, command allow lists, and read-only test guards.
- **Deterministic verification:** Baseline checks, syntax validation, lexical quote checks, and acceptance tests verify results without trusting the local model's word.
- **Local model flexibility:** Works with **LM Studio**, **Ollama**, **llama.cpp**, **vLLM**, and other OpenAI-compatible endpoints, with role-based model routing.
- **Review and rollback:** Inspect diffs and cited lines before accepting, and restore recoverable changes without overwriting later user edits.
- **Usage insights:** Track calls, local tokens, retry counts, and estimated cloud input savings in `ledger_report`.

---

## Benchmarks: Tandem MCP v3.6.1

### Gemini 4 Hydrogen + Qwen 27B (LM Studio)

Reproduced on `v3.6.1` (`010cbb6`), `qwen3.8-27b@iq3_s` (`65536` ctx, `23.6 tok/s`), `bubblewrap` sandbox, cache disabled, `1 cloud tok = 3.6 chars` (**Estimated**).

#### Reading & Extraction

| Workload | Cloud Saved (Est.) | Local Tokens | Time / Verified |
| --- | --- | ---: | --- |
| Full-file QA (`README.md`) | ~2,127 tok (90.4%) | 3,602 | 36.2 s · 1/3 quotes (`contested`) |
| Targeted grep QA (`agent.py`) | ~27,572 tok (99.5%) | 837 | 22.2 s · 2/2 quotes (`quote_only`) |
| Multi-file survey (`8 files`) | ~69,202 tok (99.4%) | 107,172 | 864.0 s · 11/11 quotes (`checked`) |
| Git history (`30 commits`) | ~3,554 tok (96.8%) | 53,712 | 420.6 s · completed |
| Structured extraction (`pyproject.toml`) | ~187 tok (85.6%) | 633 | 11.9 s · schema valid (0 loose) |

#### Delegated Fixes

| Workload | Cloud Saved (Est.) | Local Tokens | Time / Verified |
| --- | --- | ---: | --- |
| Micro bugfix (6 lines) | ~171 tok (58.7%) | 6,498 | 27.7 s · `VERIFIED` (0 repairs) |
| Multi-file bugfix (`config_loader.py`) | ~1,561 tok (92.2%) | 8,278 | 37.1 s · `VERIFIED` (0 repairs) |

#### Code Generation

| Orbital simulation, direct (`Gemini 4 Hydrogen`) | Orbital simulation, with Tandem (`Gemini 4 Hydrogen` + `qwen3.8-27b@iq3_s`) |
| :---: | :---: |
| <img src="benchmarks/gemini_3_6_1/animation_direct.gif" alt="Orbital simulation written directly by Gemini 4 Hydrogen" width="360" height="230" /> | <img src="benchmarks/gemini_3_6_1/animation_tandem.gif" alt="Orbital simulation written by qwen3.8-27b@iq3_s under a Tandem v3.6.1 contract" width="360" height="230" /> |
| **3D neon portal, direct (`Gemini 4 Hydrogen`)** | **3D neon portal, with Tandem (`Gemini 4 Hydrogen` + `qwen3.8-27b@iq3_s`)** |
| <img src="benchmarks/gemini_3_6_1/portal_direct.gif" alt="3D neon portal written directly by Gemini 4 Hydrogen" width="360" height="230" /> | <img src="benchmarks/gemini_3_6_1/portal_tandem.gif" alt="3D neon portal written by qwen3.8-27b@iq3_s under 4 Tandem v3.6.1 contracts" width="360" height="230" /> |

| Workload | Cloud Output Saved (Est.) | Local Tokens | Time / Verified |
| --- | --- | ---: | --- |
| Orbital animation (1 file) | ~1,748 tok (42.7%)* | 63,324 | 984.2 s · `VERIFIED` (46/46 met) |
| 3D neon portal (4 modules) | ~2,491 tok (51.0%)* | 237,029 | 2,464.4 s · `VERIFIED` (69/69 met) |

*\*Excludes ~5,529 and ~9,708 est. cloud input tokens to inspect receipts and `job_evidence`.*

- **[View Orbital Animation Comparison](https://alenoc.github.io/tandem-mcp/benchmarks/gemini_3_6_1/animation_comparison.html)** · **[View 3D Portal Comparison](https://alenoc.github.io/tandem-mcp/benchmarks/gemini_3_6_1/scene3d_comparison.html)**
- **Reports & raw data:** [Gemini v3.6.1 Report](benchmarks/gemini_3_6_1/RESULTS.md) · [Raw JSON](benchmarks/gemini_3_6_1/results.json) · [Generation JSON](benchmarks/gemini_3_6_1/generation.json) · [Reproducible Script](benchmarks/gemini_3_6_1/run_benchmark.py)
- **Historical Benchmark (Tandem 3.1.0 / Fable 5.2):** [Fable Report](benchmarks/RESULTS.md) · [Orbital Demo](https://alenoc.github.io/tandem-mcp/benchmarks/animation_comparison.html) · [3D Portal Demo](https://alenoc.github.io/tandem-mcp/benchmarks/scene3d_comparison.html)

---

## Quick Start

**Prerequisites:** Python 3.11+, a local OpenAI-compatible server (e.g. **LM Studio**), and `bubblewrap` on Linux for OS-level sandboxing.

**1. Install**

```sh
git clone https://github.com/ALENOC/tandem-mcp
cd tandem-mcp
python3 -m venv .venv
.venv/bin/pip install .
```

**2. Start a local LLM server (LM Studio example)**

Open **LM Studio**, load a model, and start the local server on its default OpenAI-compatible endpoint:

```text
http://127.0.0.1:1234/v1
```

(The endpoint can differ depending on your LM Studio or Ollama/vLLM configuration; Tandem auto-detects common local ports or reads `TANDEM_BASE_URL`.)

**3. Register with your MCP client**

```sh
.venv/bin/python scripts/install.py
```

Restart your MCP client (Claude Code, Codex, or Antigravity), then run your first check:

```text
Run executor_status
```

See [Getting Started](docs/GETTING_STARTED.md) for manual stdio JSON configs, installer flags, and multi-client setup.

---

## Typical Prompts

**Analyze large logs** (`digest_file`)
```text
Use tandem-mcp to inspect server.log and list every error with line numbers.
```

**Understand a codebase** (`digest_many`)
```text
Ask tandem-mcp what each Python module in src/ is responsible for.
```

**Fix a bug safely** (`delegate` -> `job_diff` -> `job_feedback` / `job_rollback`)
```text
Delegate fixing the failing test in tests/test_auth.py to tandem-mcp, then show me job_diff.
```

**Check token usage** (`ledger_report`)
```text
Show me ledger_report for the last 7 days.
```

> **Want your AI agent to use Tandem automatically?** Add standing rules to `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md` (see [Getting Started](docs/GETTING_STARTED.md#5-optional-agent-instructions-claudemd-agentsmd-geminimd)).

---

## Features Overview

- **Read & Analyze:** `ask`, `digest_file`, `digest_many`, `extract_from_file`
- **Delegate & Execute:** `delegate`, `delegate_many`, `digest_command`
- **Inspect & Control:** `job_status`, `job_diff`, `job_evidence`, `job_feedback`, `job_rollback`, `job_continue`, `job_stop`
- **Models & Monitoring:** `executor_status`, `executor_probe`, `ledger_report`
- **Project Knowledge:** `lesson_add`, `lessons`

See the [Complete MCP Tool Reference](docs/TOOLS.md).

---

## Security by Design

- **OS sandbox (`bubblewrap`):** On Linux, `TANDEM_SANDBOX` defaults to `secure` (fail-closed if `bubblewrap` is unavailable). Commands run with allowlisted system dirs, an empty tmpfs over host `$HOME`, `/tmp`, and `/run`, read-only `SKIP_DIRS`, stripped secret env vars, and network/PID/IPC namespace isolation.
- **Compatibility mode warning:** On systems without `bubblewrap` (macOS, Windows, or `TANDEM_SANDBOX=compatible`/`auto`), commands run **without OS filesystem isolation**, relying on command-text checks (`allow_run`/`DENY`), outbound symlink refusal, and workspace `stamp()` verification.
- **Contracts & file protection:** Strict contracts require concrete goals, `write_globs`, and `verify_commands`. Protected test files are restored automatically if modified.
- **Snapshots, rollback & redaction:** Edits are journaled and pre-run files are snapshotted up to configurable caps (`TANDEM_REQUIRE_FULL_BACKUP=1` enforces full backup coverage; incomplete rollbacks report `partial_rollback`). Tool outputs redact detected secrets by default.

See [Security Model](docs/SECURITY_MODEL.md) for full details and [SECURITY.md](SECURITY.md) to report vulnerabilities.

---

## Performance & Benchmarks

Tandem trades local execution time for reduced cloud context on **reading** and **test-driven fixes**. Generating brand-new code from a contract preserves quality when design is written into constraints, but adds contract-authoring and review overhead so total cloud savings are smaller or negative compared to one cloud turn.

- **Latest full suite (`3.6.1`, Nov 2026):** Measured with `Gemini 4 Hydrogen` + `qwen3.8-27b@iq3_s` on i9-9900K / RX 6800 XT (58.7%-99.5% estimated cloud input savings on reading/bugfixes; 46/46 and 69/69 constraints on full demo generation).
- **Live validation (`3.5.1`, Nov 2026):** Measured on LM Studio (`qwen3.8-27b@iq3_s`, `10.7 tok/s` probed): `digest_file` `14.84 s`, `delegate` bugfix `23.78 s` (`5,124` local tokens, `VERIFIED`, `0` repairs) vs direct LM Studio completion `8.46 s` (`305` local tokens, unverified).
- **Historical suite (`3.1.0`, Nov 2026):** Measured with `Fable 5.2` + `qwen3.8-27b@iq3_s` on i9-9900K / RX 6800 XT (58.7%-99.3% estimated cloud input savings on reading/bugfixes; 19-31 min on full demo generation).

See [Benchmarks](docs/BENCHMARKS.md) for full tables, hardware specs, and methodology.

---

## Comparison With Alternatives

Rather than merely connecting a cloud agent to a local LLM, Tandem introduces bounded delegation, deterministic checks, lexical evidence tracking, and controlled review with journaled rollback.

See the [full comparison](docs/COMPARISON.md) (compiled Nov 2026 from public READMEs).

---

## Documentation

- [Getting Started](docs/GETTING_STARTED.md)
- [Architecture](docs/ARCHITECTURE.md) ([English PDF](docs/tandem-mcp-architecture.pdf) · [Italian PDF](docs/tandem-mcp-architettura.pdf))
- [MCP Tools Reference](docs/TOOLS.md)
- [Security Model](docs/SECURITY_MODEL.md)
- [Configuration](docs/CONFIGURATION.md)
- [Benchmarks](docs/BENCHMARKS.md)
- [Comparison With Alternatives](docs/COMPARISON.md)
- [Changelog](CHANGELOG.md)

---

## License & Attribution

[MIT License](LICENSE) · Copyright (c) 2026 **Alessandro Nocentini** ([@ALENOC](https://github.com/ALENOC)) · [Security Policy](SECURITY.md)

TDQS

A3.5/5.0

Scored across 19 tools

Disambiguation4/5

The core delegation lifecycle (delegate, delegate_many, job_status/continue/stop/diff/rollback/evidence/feedback) is cleanly separated by verb, and executor_status vs executor_probe are distinguishable. The main blur is in the read/digest cluster: ask, digest_file, digest_many and extract_from_file all route content to the executor, so an agent must parse descriptions to know whether it wants a prose answer, a per-file survey, or schema-bound structured data. lessons vs lesson_add vs job_feedback's lesson parameter also sit close together but stay workable.

Naming Consistency4/5

Everything is snake_case and grouped by prefix (job_*, digest_*, executor_*), which makes scanning predictable. Minor deviations: bare 'delegate', 'ask' and 'lessons' break the verb_noun pattern, and lesson_add/lessons are an asymmetric create/list pair. Nothing rises to a real inconsistency problem.

Tool Count4/5

19 tools is on the heavy side, but the surface is broad (delegation, job lifecycle, file digests, lessons, executor introspection, ledger) and nearly every tool maps to a distinct operation rather than a convenience wrapper. The weight comes from describing a contract protocol rather than from redundancy, though trimming the digest cluster would be defensible.

Completeness4/5

The delegation lifecycle is unusually complete: dispatch, batch, poll, continue, stop, diff, rollback, evidence, verdict, plus persistent lessons and usage reporting. The noticeable gap is enumeration: job_status and the job_* tools all require a job_id, but there is no job_list/jobs tool to discover ids after a server restart or in a later session, forcing the agent to remember them.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues