corresync

# Corresync

<!-- markdownlint-disable MD013 MD033 -->
<p align="center">
  <a href="https://corresync.org/">
    <img src="site/corresync-mark.svg" width="144" height="144" alt="Corresync: two correspondence flows around one local core">
  </a>
</p>

<p align="center">
  <strong>Mail, calendars, and tasks. One local MCP server and CLI.</strong><br>
  Provider-neutral, local-first tooling for AI agents, scripts, and you.
</p>

<p align="center">
  <a href="https://github.com/nkiyohara/corresync/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/nkiyohara/corresync/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/nkiyohara/corresync/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/nkiyohara/corresync?display_name=tag&sort=semver"></a>
  <a href="go.mod"><img alt="Go 1.26" src="https://img.shields.io/badge/Go-1.26-00ADD8?logo=go&logoColor=white"></a>
  <a href="LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/github/license/nkiyohara/corresync"></a>
  <a href="docs/install.md"><img alt="macOS, Linux, and Windows" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-334155"></a>
  <a href="docs/mcp.md"><img alt="Model Context Protocol over stdio" src="https://img.shields.io/badge/MCP-stdio-6F5BD3"></a>
  <a href="docs/README.md"><img alt="Current documentation" src="https://img.shields.io/badge/docs-current-3F7AD6"></a>
  <a href="docs/architecture.md"><img alt="Local-first architecture" src="https://img.shields.io/badge/architecture-local--first-E0574A"></a>
</p>

<p align="center">
  <a href="https://corresync.org/">Website</a> ·
  <a href="https://corresync.org/getting-started.html">Getting started</a> ·
  <a href="https://corresync.org/providers.html">Providers</a> ·
  <a href="https://corresync.org/features.html">Features</a> ·
  <a href="https://corresync.org/safety.html">Safety</a> ·
  <a href="https://corresync.org/privacy.html">Privacy</a> ·
  <a href="https://corresync.org/terms.html">Terms</a> ·
  <a href="docs/README.md">Technical docs</a>
</p>
<!-- markdownlint-enable MD013 MD033 -->

`corr` brings isolated mail, calendar, and task accounts into one terminal—and
one local
[Model Context Protocol](https://modelcontextprotocol.io/) server.
Gmail, Google Calendar, and Google Tasks are available through a Desktop OAuth
client in a Google Cloud project you control. Corresync-managed Google OAuth
remains dormant. The canonical task tools also include explicit Microsoft To
Do, Todoist, TickTick, and CalDAV VTODO routes; remaining task-provider adapters
stay unavailable until their contracts are implemented.

- Search mail and build one agenda across accounts without collapsing their
  identity or provider provenance.
- Use one stable, provenance-preserving task model as provider adapters become
  available.
- Save private account-local mail searches and relative calendar windows, then
  run them live without creating a shadow mailbox or calendar cache.
- Use the same typed operations from a human-friendly CLI, stable JSON, or an
  AI agent.
- Keep sign-in in a visible browser, an explicit public-client OAuth flow, or
  an approved local credential store.
- Review consequential effects before they happen. Unknown remote outcomes
  stop for reconciliation instead of being retried automatically.

## What it feels like

```console
$ corr mail search --all-accounts \
    --query 'subject:"Quarterly plan"' --limit 3
● work · microsoft-owa   Ana Ruiz   Plan review
· personal · jmap       Finance    Plan receipt

$ corr agenda list --all-accounts \
    --start 2026-07-29T00:00:00Z \
    --end 2026-07-30T00:00:00Z
```

Connect an agent to the same local core:

```console
corr integrations detect
corr integrations plan codex claude-code
corr integrations setup codex claude-code
# Phase A also includes github-copilot, gemini-cli, qwen-code, qoder, kimi-code
```

Then ask naturally:

```text
Check my inboxes, calendars, and task lists and summarize what needs attention today.
```

One failed provider becomes an explicit partial failure. Successful results
remain available, and writes still require one exact account.

## Choose the route that fits

Mail, calendar, and task routes are selected independently. For example, an
account can pair IMAP/SMTP mail with a CalDAV calendar; its task route remains a
separate explicit choice.

<!-- markdownlint-disable MD013 -->
| Route | Mail | Calendar | Tasks | Authentication |
| --- | --- | --- | --- | --- |
| Outlook Web | Typed reads and writes | Selectable calendars; provider-supported Teams link | — | Dedicated visible browser profile |
| Google (your OAuth client) | Gmail API reads and writes; no permanent delete | Selectable calendars; Google Meet when advertised | Google Tasks through a separate task-only grant | Your Desktop OAuth client; client credential and grants in the OS keyring |
| Microsoft Graph | Typed reads and writes | Selectable calendars; typed Teams-link creation | Microsoft To Do | Your authorized public OAuth client; OS-keyring grant |
| Todoist | — | — | Typed Todoist operations | Your authorized public OAuth client; OS-keyring grant |
| TickTick | — | — | Typed TickTick operations | Your authorized confidential OAuth client; external secret handle and OS-keyring grant |
| JMAP | Typed mail operations | — | — | OS keyring or approved credential helper |
| IMAP / SMTP | IMAP read/manage and SMTP draft/send | — | — | OS keyring or approved credential helper |
| CalDAV | — | Typed calendar operations and conditional scheduling | VTODO lists, search, sync, and reviewed writes | OS keyring or approved credential helper |
<!-- markdownlint-enable MD013 -->

Discovery gathers DNS, well-known, and provider metadata without credentials.
It never authenticates or adds an account. Microsoft Graph and user-owned
Google authorization remain explicit choices and are never automatic
fallbacks. Google discovery can offer guided Desktop-client setup, but no
Google sign-in starts until a later explicit `corr auth login`. See the
[annotated Google setup guide](docs/google-oauth-setup.md).

iCloud has a first-class guided preset over the same provider-neutral
IMAP/SMTP and CalDAV adapters. `corr setup` recognizes documented iCloud Mail
address families or the complete verified Apple SRV endpoint set, reviews both
routes as one account, and uses one external credential handle by default.
After the account is added, an explicit handoff can open Apple's app-password
page and the OS-owned credential prompt; the `corr` process never reads the
app-specific password.

Every available v0.9 route above has synthetic provider-contract and
application coverage. The user-owned Google API route is available but
live-unobserved. Other provider and platform implementations remain
**live-unobserved** until an authorized, content-free observation is bound to
the exact commit. See [compatibility evidence](docs/compatibility.md) before
connecting a sensitive account.

## From install to a first read

Prefer a guided page? Follow
[getting started on the website](https://corresync.org/getting-started.html).

### 1. Install

The official standalone installers are the shortest path on every platform.
They select the latest stable release, verify its archive and candidate binary,
install for the current user without elevation, and leave account setup untouched.

#### macOS and Linux

```console
curl -LsSf https://corresync.org/install.sh | sh
corr --version
```

#### Windows PowerShell

```powershell
powershell -NoProfile -Command "irm https://corresync.org/install.ps1 | iex"
corr --version
```

Review [`install.sh`](https://corresync.org/install.sh) or
[`install.ps1`](https://corresync.org/install.ps1) before running it if you
prefer. Package managers remain fully supported alternatives:

```console
# Homebrew · macOS or Linux
brew install nkiyohara/corresync/corresync

# WinGet · Windows
winget install --id nkiyohara.Corresync --exact

# Scoop · Windows
scoop bucket add corresync https://github.com/nkiyohara/scoop-corresync
scoop install corresync/corresync
```

Direct archives, native Linux packages, version pinning, checksums, and
Sigstore provenance are in the [installation guide](docs/install.md). The
[guided website](https://corresync.org/getting-started.html#step-install) keeps
the same copy-paste choices visible for people who do not use GitHub regularly.

Claude Desktop users can also install the platform-universal `.mcpb` from the
[latest release](https://github.com/nkiyohara/corresync/releases/latest).
The bundle runs the same verified `corr mcp serve` binary locally over stdio;
it does not deploy Corresync or relay mailbox data. Install the CLI first for
the explicit account setup and sign-in steps below, then open or drag the
`.mcpb` into Claude Desktop.

### Stay current

Interactive commands make a quiet, cached release check at startup. If an
update exists, Corresync shows the exact command for your installation:
`corr update` for the standalone build, or the matching Homebrew, Scoop, or
WinGet command. Package-managed files are never changed by Corresync.

Stable releases are selected by default. Standalone users who want signed
release candidates can choose the preview channel interactively:

```console
corr settings
```

The equivalent copy-paste commands for scripts are:

```console
corr config set updates.channel preview
corr update
```

Switch back with `corr config set updates.channel stable`; Corresync never
downgrades the running binary. Preview releases do not enter package-manager
catalogs.

Standalone users can opt in to verified automatic installation:

```console
corr config set updates.auto_install true
```

It never runs during MCP tool calls, configuration changes, daemon work, JSON
output, pipes, or other non-interactive paths. The current command continues
normally and the new binary is active on the next `corr` start.

### 2. Add and sign