# MasterMind Lite

Ask Claude, Gemini, and Grok from a ChatGPT conversation through the provider CLIs you already use.

```text
                    Claude
                   /
ChatGPT -> MasterMind Lite -> Gemini
                   \
                    Grok
                     |
                     v
             ChatGPT synthesis
```

ChatGPT remains the coordinator. MasterMind Lite sends one payload to independent advisers in
parallel and returns their answers separately. It does not vote, rank models, run an internal
debate, or act as an autonomous agent.

## Why I built it

Different models often catch different flaws, edge cases, and approaches. Comparing them improved
my planning and reviews, but repeatedly opening three sites, rebuilding context, copying prompts,
and pasting every answer back into ChatGPT became tedious. MasterMind Lite makes that small workflow
one local tool call while leaving the final judgment with ChatGPT and the user.

## What it does

- ChatGPT calls one local MCP consultation tool.
- MasterMind Lite asks selected providers concurrently with the same payload.
- Claude uses Claude Code, Gemini uses Google's Antigravity CLI (`agy`), and Grok uses Grok CLI.
- Full provider results return independently, including partial success when one provider fails.
- Stable thread keys continue the corresponding native provider conversations.
- Model changes safely restart only the affected provider conversation.
- No API keys, prompt bodies, response bodies, or telemetry are stored by MasterMind Lite.

## Two modes

### Exact mode

Say: **“Send this exact prompt to MasterMind.”**

`mastermind_exact` forwards the supplied text unchanged. Provider selection and model overrides are
metadata: they are never appended or prepended to the prompt. MasterMind Lite verifies the outgoing
UTF-8 payload with SHA-256 for every provider.

### Feedback mode

Say: **“Initiate MasterMind and get feedback on this.”**

ChatGPT—not MasterMind Lite—constructs a concise, self-contained briefing from the relevant chat
context. `mastermind_feedback` then sends that briefing unchanged to the independent advisers.

## Friendly defaults

Ordinary consultations use these product presets automatically:

| Adviser | Friendly preset | Current CLI resolution |
|---|---|---|
| Claude | **Opus 5 / Medium** | `--model opus --effort medium` (currently `claude-opus-5`) |
| Gemini | **3.8 Flash / Extended** | `--model gemini-3.8-flash-high --effort high` |
| Grok | **Expert** | `--model grok-4.6 --reasoning-effort high` |

“Extended” and “Expert” are stable MasterMind Lite product names. The preset layer isolates users
from provider-specific identifiers. `mmlite doctor` and `mmlite config show` display both the
friendly preset and current resolved CLI settings.

When a user explicitly asks for another setting, ChatGPT passes a per-call override. Examples:

- “Call MasterMind, but use Claude Opus 5 High.” uses Claude's **Opus 5 / High** preset only.
- “Use Grok Simple this time.” uses Grok's **Simple** preset only.
- A custom override can supply an explicit CLI `model` and/or `effort`.

The additional built-in mappings are Opus 5 / High → `opus` with `high`, and Grok Simple →
`grok-4.6` with `low` reasoning effort.

No model choice is required for normal calls. If an override changes a provider's resolved model or
effort on a persistent thread, MasterMind Lite starts a fresh native session for that provider,
returns `thread_state: "restarted"`, and leaves the other provider sessions untouched. Returning to
the default later may therefore restart that provider again.

## Requirements

- Windows with Python 3.11 or newer (v0.1 is built and live-tested on Windows).
- Claude Code CLI, authenticated with a supported Claude account.
- Google Antigravity CLI (`agy`), authenticated with a supported Google account.
- Grok CLI, authenticated with a supported xAI account.
- ChatGPT/Codex Desktop with local STDIO MCP support for the conversational workflow.

Provider access varies by product, subscription, region, and CLI release. MasterMind Lite does not
guarantee that every consumer plan includes every model.

## Install

```powershell
git clone https://github.com/kukumaka/mastermind-lite.git
cd mastermind-lite
py -3.11 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install .
```

Authenticate the provider CLIs using their supported flows:

```powershell
claude auth login
agy models
grok login
```

`agy models` also verifies that the authenticated Antigravity model catalog is reachable. Then run:

```powershell
mmlite doctor
mmlite config show
```

## Configuration

The first command creates `%USERPROFILE%\.aimastermind-lite\config.json`. The simple schema-v3
defaults look like this:

```json
{
  "schema_version": 3,
  "providers": {
    "claude": {
      "preset": "Opus 5 / Medium",
      "timeout_seconds": 150,
      "max_response_chars": 24000
    },
    "gemini": {
      "preset": "3.8 Flash / Extended",
      "timeout_seconds": 150,
      "max_response_chars": 24000
    },
    "grok": {
      "preset": "Expert",
      "timeout_seconds": 150,
      "max_response_chars": 24000
    }
  }
}
```

Advanced users can replace one preset with explicit settings:

```json
{
  "preset": "Custom",
  "model": "provider-model-id",
  "effort": "high",
  "timeout_seconds": 150,
  "max_response_chars": 24000
}
```

Invalid fields, presets, or effort values fail before any provider call. Configuration is reloaded
for every consultation. External CLI releases can rename models or flags; use `doctor` and the
provider model-list commands after upgrading a CLI.

## Local CLI

```powershell
mmlite consult --thread project-review --prompt "What should I reconsider?"
mmlite consult --thread project-review --prompt-file C:\path\to\prompt.txt
mmlite consult --thread project-review --provider grok --prompt "Retry the question."
mmlite thread --thread project-review
mmlite reset --thread project-review
```

Repeat `--provider` to select more than one adviser. Provider selection supports targeted retries;
MasterMind Lite never automatically repeats an entire consultation.

## Connect to ChatGPT/Codex Desktop

Run the local STDIO server with:

```powershell
mmlite-mcp
```

Or register the installed executable directly using a generic path such as:

```text
<repo>\.venv\Scripts\mmlite-mcp.exe
```

In the desktop MCP server configuration, ensure the outer tool timeout exceeds the provider
timeout. The recommended values are 150 seconds per provider and 180 seconds for the MCP tool:

```toml
[mcp_servers.mastermind_lite]
command = 'C:\path\to\mastermind-lite\.venv\Scripts\mmlite-mcp.exe'
tool_timeout_sec = 180
```

After adding the STDIO server, restart the desktop app and use `/mcp` to confirm these three tools:

- `mastermind_exact`
- `mastermind_feedback`
- `mastermind_reset_thread`

## Reliability and persistent threads

Each provider has an independent timeout. If Claude and Gemini finish while Grok times out, both
completed answers return alongside Grok's structured error. Only the failed provider can be retried
with `providers: ["grok"]`; successful siblings are not silently called again.

Each result includes `thread_state` (`new`, `continued`, or `restarted`), a locally reliable
`successful_turn_count`, requested preset/model/effort, provider-reported settings when available,
duration, prompt hash, and truncation metadata. Counts remain `null` when old state cannot support a
reliable value.

Provider histories can drift because each CLI compacts and interprets context differently. Use a
fresh thread or a self-contained feedback briefing when a clean comparison matters. Resetting a
MasterMind thread forgets local mappings; it does not delete histories owned by provider CLIs.

Responses are limited to 24,000 characters per provider by default. A longer answer retains its
beginning and end and returns `truncated: true` with original and returned character counts.

## Privacy, security, and limitations

Prompts are sent to every selected provider. Authentication remains managed by the provider CLIs,
and users remain responsible for those providers' data terms and subscription quotas.

- Runtime state is local under `%USERPROFILE%\.aimastermind-lite`; prompt and response bodies are
  not persisted.
- Known provider API-key environment variables are removed from child processes.
- Claude receives an empty tool set and strict empty MCP configuration.
- Antigravity exposes no complete no-tools switch; its isolation is weaker even though it runs
  headlessly with sandbox selection and disabled slash commands.
- Grok's CLI-level tools and permissions are denied, but its installed documentation does not claim
  Windows OS sandbox enforcement.
- External CLI changes can require adapter updates.
- Multiple opinions can expose missed assumptions; they do not guarantee a better answer.
- MasterMind Lite is intentionally not an autonomous agent framework or browser automation system.

Please report security issues using the process in [SECURITY.md](SECURITY.md).

## Development

```powershell
python -m pip install -e ".[dev]" build
pytest -q
python -m build
```

The test suite installs an automatic guard that rejects attempts to launch `claude`, `agy`, or
`grok`, so automated tests do not intentionally consume provider quota. The GitHub Actions workflow
runs only this offline suite and package build.

See [POST_V0_1.md](POST_V0_1.md) for deliberately deferred ideas and [CONTRIBUTING.md](CONTRIBUTING.md)
for the small contribution guide.

## License

MIT. See [LICENSE](LICENSE).