Metadata-Version: 2.4
Name: mindsync-ai
Version: 1.8.0
Summary: Local-first MCP orchestration, shared memory, and automatic task routing for coding agents
Author: Aditya Arya, MindSync Contributors
License-Expression: MIT
Project-URL: Homepage, https://adityarya24.github.io/mindsync-ai/
Project-URL: Source, https://github.com/adityarya24/mindsync-ai
Project-URL: Documentation, https://github.com/adityarya24/mindsync-ai#readme
Project-URL: Issues, https://github.com/adityarya24/mindsync-ai/issues
Project-URL: Changelog, https://github.com/adityarya24/mindsync-ai/blob/master/CHANGELOG.md
Keywords: mcp,memory,sync,multi-agent,agents,llm,event-bus,dispatch,mindsync-ai
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.27.0
Requires-Dist: pydantic>=2.0
Requires-Dist: sqlite-vec<0.2,>=0.1.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: ruff<0.16,>=0.4; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="docs/mindsync-mark.svg" alt="MindSync AI" width="88" height="88" />
</p>

<h1 align="center">MindSync AI</h1>

<p align="center">
  <a href="https://github.com/adityarya24/mindsync-ai/actions/workflows/ci.yml"><img src="https://github.com/adityarya24/mindsync-ai/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://pypi.org/project/mindsync-ai/"><img src="https://img.shields.io/pypi/v/mindsync-ai.svg" alt="PyPI version" /></a>
  <a href="https://pypi.org/project/mindsync-ai/"><img src="https://img.shields.io/pypi/pyversions/mindsync-ai.svg" alt="Python versions" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
</p>

<p align="center"><strong><a href="https://adityarya24.github.io/mindsync-ai/">adityarya24.github.io/mindsync-ai</a></strong></p>

Run a fleet of coding agents without them tripping over each other. MindSync is
**local-first MCP orchestration**: the CLI already talking to you becomes the
orchestrator, and everything else runs through it — no separate app, no account,
no hosted control plane.

- **Routes by capability** and tells you which agent it picked, and why.
- **Blocks file collisions** by showing active file focus before work starts.
- **Remembers across sessions** — decisions, blockers, and facts replay into the next run.
- **Hands off before limits land** — a job cools an exhausted provider and moves to the next agent; the Codex seat warns before it runs out.

```text
You → human-facing CLI (orchestrator) → MindSync → Codex / Claude / Gemini / AGY / Grok / Cursor / OpenCode / Aider
```

Workers get bounded tasks. They cannot recursively delegate through MindSync.
Remote sync is optional and runs through your own SSH host — your agents, your
machine, your data.

## Quick start

```bash
pip install mindsync-ai
mindsync setup --mode auto
mindsync doctor
mindsync agents
```

Requires Python 3.10+. Restart the configured CLI sessions after setup.

`setup` registers known MCP hosts (Codex, Claude, Gemini, Grok, Cursor, OpenCode)
and recognised PATH agent CLIs. MCP is installed only when MindSync has a real
recipe — it will not guess `mcp add` flags. Unknown binaries are suggested, not
registered, and never executed. Use `mindsync register` for an unusual name.

```bash
mindsync setup --dry-run          # preview
mindsync setup --cli grok         # one known host, no PATH scan
mindsync setup --no-discover      # hosts only
mindsync setup --no-hooks         # skip Codex standalone hooks
```

Install from source: `python -m pip install -e ".[dev]"`

## Supported clients

A CLI may be an **MCP host**, a **worker**, or both.

| CLI | MCP host | Worker | Notes |
| --- | --- | --- | --- |
| OpenAI Codex | Native | Yes | Also gets standalone memory hooks |
| Anthropic Claude | Native | Yes | Architecture, review, large context |
| Google Gemini CLI | Native | Yes | Gemini/Antigravity family |
| Antigravity (`agy`) | Via Gemini | Yes | Preferred worker in that family |
| Grok CLI | Native | Yes | Research, review, security |
| Cursor Agent | JSON | Yes | `~/.cursor/mcp.json` |
| OpenCode | JSON | Yes | `~/.config/opencode/opencode.jsonc` |
| Aider | — | Yes | Focused editing |

Gemini CLI and `agy` are one family. When either is the human-facing orchestrator,
both are excluded from automatic worker selection.

## Orchestration

Policy lives in `~/.mindsync/orchestration.json`. Modes: `auto`, `suggest`, `off`.

```bash
mindsync config orchestration.mode auto
mindsync-dispatch run auto "implement and test the fix" --capability coding
mindsync-dispatch status
```

Provider quota handoff is opt-in and requires an isolated worktree:

```bash
mindsync-dispatch run auto "implement and test the fix" --write --worktree --on-limit handoff
mindsync-dispatch limits                 # inspect provider/account cooldowns
mindsync-dispatch limits clear           # clear cooldowns after operator verification
```

Pre-emptive usage readers are pluggable per provider. The Codex adapter can
read primary and weekly OAuth usage windows from the local `~/.codex/auth.json`
source when a reader is configured. Pre-emptive polling and threshold handoff are
opt-in: they require both `usage.enabled: true` in `agents.json` and
`--on-limit handoff` on an isolated worktree job. Global usage settings default
to disabled:

```json
{
  "usage": {
    "enabled": false,
    "defaultThresholdPercent": 90,
    "orchestratorReservePercent": 80,
    "pollingIntervalSeconds": 60
  }
}
```

`defaultThresholdPercent` is the dispatched-worker handoff threshold.
`orchestratorReservePercent` is a separate opt-in Codex standalone Stop
warning line; when omitted it follows `defaultThresholdPercent` so existing
configs keep working. Neither field is a live usage estimate.

When enabled, dispatch polls at `pollingIntervalSeconds` during a running
attempt, skips cooling or over-threshold provider accounts before spawn, and may
transfer only when a privacy-safe MindSync checkpoint already exists for that
attempt (plus the worktree diff and original task). There is no generic CLI
control channel: dispatch does not ask arbitrary agents to write `HANDOFF.md`.
Without a checkpoint, threshold hits are recorded as `preemptiveBlocked` and
the attempt keeps running so reactive quota handoff remains the floor. Job
status shows usage evaluation, skips, blocks, and handoffs; only percentages,
window labels, reset times, scope, and reasons are persisted — never raw usage,
auth, or source payloads.

Per-adapter overrides use `usageReader` and optional `usageThresholdPercent`.
The bundled Codex preset declares `usageReader: "codex-oauth"`.
Near the Codex standalone usage threshold, Stop warns the operator, points at
the ranked dispatch successor, and does **not** launch another CLI. Other
adapters have no pre-emptive reader; `mindsync doctor` shows `usage_mode` and
whether reactive cooldown uses a parsed stderr timestamp or `quotaCooldownSeconds`.

Only configured provider-specific exhaustion messages rotate. Timeouts, auth
errors, generic rate limits, failing tests, and ordinary agent failures stop the
job. A successor receives the same worktree, the original task, and the latest
structured MindSync checkpoint; because routing may select another provider,
enable handoff only when that cross-provider context transfer is acceptable.

Completed jobs keep their branch by default. To push a successful isolated
job and open a pull request for review, enable it for that repository:

```bash
mindsync config onComplete pr --project .
```

MindSync never merges the pull request. It also declines to publish when a
requested check failed or did not report, private prompt framing cannot be
separated safely, commit hooks refuse the work, or changed paths look like
secrets. Use `MINDSYNC_ON_COMPLETE=pr` for a one-run override.

Custom worker:

```bash
mindsync register --name my-worker --bin my-cli --capability coding
```

Heavy tags (`security`, `large-context`, `multimodal`) need `--confirm`.
Roster and jobs: `~/.mindsync/dispatch/` (`AGENT_DISPATCH_HOME` overrides).

## Memory

Dispatch memory defaults to `auto` in git checkouts (opaque git identity, never
a path or repo name). Failures warn; they do not fail the job.

```bash
mindsync memory stats
mindsync memory list --project my-repo
mindsync memory recall --project my-repo --query "database decision"
```

Nothing is pruned without `--yes`. See MCP tools on the server (`get_sync_context`,
`delegate_task`, `job(action='wait')`, …) once a host is configured. Orchestrator
MCP exposes 16 tools; worker subprocesses started with `MINDSYNC_WORKER=1` expose
12 and omit orchestration-only dispatch tools (`delegate_task`, `route_task`,
`get_orchestration_policy`, `list`). Job/event/session/consolidation helpers are
subject bundles with no old-name aliases.

Optional `completionSinkCmd` in the orchestration policy is an argv list
(no shell) that receives one JSON object on stdin after `job.completed` /
`job.failed` is persisted: `event_id`, job id/status, bounded summary, optional
privacy-screened task, optional PR URL. The allowlisted projection is written to
an outbox before send; failed delivery stays pending and is retried on the next
drain (later job events or process restart). Each drain stops after the first
sink failure and is bounded by a short wall-clock budget and attempt cap.
Duplicate `event_id`s are not resent.
Sink failure never changes job status. Leave it empty to keep current behavior.

## Optional remote sync

```bash
export MINDSYNC_SSH_HOST=my-server
export MINDSYNC_REMOTE_ROOT=/opt/mindsync
```

Worker loop and VPS scripts: [`examples/remote/`](examples/remote/).
Environment variables: [`.env.example`](.env.example).

## Safety

- The human-facing CLI owns authorization and the final answer.
- Setup never executes a binary it cannot name.
- Existing MCP registrations are preserved unless `--force`.
- Local state uses crash-safe locks and atomic writes. On Windows, tune queue
  lock deadlines and OS-lock contention backoff via
  `MINDSYNC_QUEUE_LOCK_TIMEOUT`, `MINDSYNC_LOCK_CONTENTION_BACKOFF_BASE`, and
  `MINDSYNC_LOCK_CONTENTION_BACKOFF_MAX` (see [`.env.example`](.env.example)).

Runs with the current user's privileges. See [`SECURITY.md`](SECURITY.md).

## Development

```bash
python -m venv .venv && . .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"
python -m ruff check .
python -m pytest -q
```

Use the venv. `sqlite-vec` is a package dependency; a bare system Python will
fail the Tier 2 tests.

## License

[MIT](LICENSE)
