Metadata-Version: 2.4
Name: mindsync-ai
Version: 1.6.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

# MindSync AI

[![CI](https://github.com/adityarya24/mindsync-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/adityarya24/mindsync-ai/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/mindsync-ai.svg)](https://pypi.org/project/mindsync-ai/)
[![Python versions](https://img.shields.io/pypi/pyversions/mindsync-ai.svg)](https://pypi.org/project/mindsync-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**[adityarya24.github.io/mindsync-ai](https://adityarya24.github.io/mindsync-ai/)**

Local-first MCP orchestration for coding agents. The CLI already talking to you
stays in charge: MindSync routes work by capability, blocks file collisions,
and keeps session memory across runs. No MindSync account. Remote sync is optional.

```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.

## 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
```

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_wait`, …) once a host is configured.

## 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.

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)
