Mastermind is a local-first repository control plane for AI-assisted software work. An AI reasoning client plans and explains; Mastermind mediates bounded reads, guarded changes, validation, and Git operations inside repositories the owner has authorized.
This is the 2.0.0-beta.1 public pre-release. It includes the current Builder/Quick Mode and resumable Goal Mode behavior. It is not a claim that every roadmap capability is complete.
- Quick Mode handles focused tasks: inspect exact files, answer repository questions, make a scoped edit, run a bounded check, and report evidence.
- Goal Mode handles larger authorized outcomes. It records a roadmap and progress, executes bounded tasks across files, validates work, and can resume the same run after an interruption. A run is complete only when its actual completion conditions are satisfied; a paused or failed run remains recoverable.
Both modes use the same repository policy and execution core.
- Bounded reads of authorized repository files and context.
- Guarded file create, edit, move, and delete operations, subject to path policy and any required confirmation.
- Bounded validation and command execution with persisted results.
- Git-aware changes and explicit commit/push authority. No force-push or automatic push is granted by default.
- Durable Goal Mode roadmap, progress, continuation, and recovery state.
- Human-readable progress and results; routine responses do not require users to interpret internal JSON or logs.
- Five authenticated Custom GPT Action operations: status, repository context, guarded file changes, Git commit, and bounded command/validation.
AI reasoning client
-> five-operation Mastermind API / Custom GPT Actions
-> local Mastermind runtime and policy checks
-> owner-authorized repository
-> bounded file, validation, and Git operations
The AI client supplies reasoning, while the local runtime enforces source identity, path policy, execution limits, confirmations, and evidence. The repository remains under the owner's control.
- Repository operations require an exact authorized source; a chat's implied “current folder” is not authority.
- Reads, outputs, commands, and validation jobs are bounded.
- Secrets, environment files, private keys, Git metadata, generated/vendor paths, and other protected system paths are denied.
- Edits are constrained to approved repository paths. Unrelated existing changes are preserved and are not silently staged.
- Consequential actions can require explicit confirmation and a runtime-issued confirmation token.
- Commits use explicit paths. Pushes require explicit authority; force push is not a normal operation.
- Goal Mode pauses for ambiguity, missing authority, confirmation, or failed validation and does not claim completion without evidence.
Review every proposed diff and keep sensitive repositories out of integrations whose disclosure and retention behavior you have not approved.
- Node.js 20.20.2 or newer in the 20.x line; the MCP workspace package
and root package both declare
>=20.20.2 <21. - pnpm 10.33.0, pinned by the root
packageManagerfield. - Git.
- Docker Engine with Docker Compose for the complete local relay stack.
- An HTTPS endpoint reachable by ChatGPT-hosted Actions if you connect from ChatGPT. Localhost is only reachable by clients on the same machine.
git clone https://github.com/prochattools/mastermind.git
cd mastermind
npm install --global pnpm@10.33.0
pnpm install --frozen-lockfile
pnpm build
pnpm type-check
node packages/cli/dist/bin/workbench.js init
node packages/cli/dist/bin/workbench.js connect /path/to/repositoryThe CLI registers only the repository path you provide. Read the installation guide before starting the complete local stack: it covers the owner Action token, relay configuration, file permissions, and health checks.
Start and verify the owner-local stack:
pnpm local:start
pnpm local:verify
curl -fsS http://127.0.0.1:3054/api/unified-health
curl -fsS http://127.0.0.1:3054/api/openapilocal:start manages the Mastermind services on their documented local
ports. Do not run it over another instance you intend to keep running.
The supported hosted ChatGPT integration in this release is Custom GPT Actions using the five-operation OpenAPI schema. This release does not include the staging Lab's remote Plugin/App OAuth transport.
- Configure an HTTPS domain or tunnel that reaches your own Mastermind runtime.
- Set
PUBLIC_ACTION_ORIGINto that exact HTTPS origin, with no path. - Fetch
https://your-domain.example/api/openapiand import the schema in the Custom GPT Action editor. - Configure bearer authentication with the owner-created Action Token.
- Use Custom GPT instructions, then test status and one bounded read before authorizing any write.
The committed schema uses https://your-mastermind-domain.example as a
placeholder. Do not use that placeholder in a live GPT. Do not assume that
ChatGPT can reach a private localhost address or that every account/workspace
has the same integration features.
Quick Mode: “Inspect src/parser.ts and its focused tests. Explain the
failure, make the smallest in-scope correction, run the relevant test, and
show me the exact diff. Do not commit.”
Goal Mode: “Add the approved export option under src/export/. First
propose a bounded roadmap and protected paths. Implement and validate each
phase, preserve unrelated changes, and keep this same goal resumable if the
conversation is interrupted. Report completion only after all checks pass.”
- High-priority roadmap: automatic repository, worktree, and feature-branch freshness/discovery is not implemented. Recheck the selected source and Git state before relying on cached context.
- Optional Jev acceleration is deferred.
- Remote Plugin/App distribution and OAuth are not part of this public release.
- Dirty-target compare-and-swap/reconciliation is deferred; review current state before applying or publishing changes.
- A reachable HTTPS endpoint and an enabled Custom GPT Actions feature are platform/account requirements, not capabilities this repository can grant.