{ "markdown": "# Corresync\n\n\n

\n \n \"Corresync:\n \n

\n\n

\n Mail, calendars, and tasks. One local MCP server and CLI.
\n Provider-neutral, local-first tooling for AI agents, scripts, and you.\n

\n\n

\n \"CI\n \"Latest\n \"Go\n \"Apache-2.0\n \"macOS,\n \"Model\n \"Current\n \"Local-first\n

\n\n

\n Website ·\n Getting started ·\n Providers ·\n Features ·\n Safety ·\n Privacy ·\n Terms ·\n Technical docs\n

\n\n\n`corr` brings isolated mail, calendar, and task accounts into one terminal—and\none local\n[Model Context Protocol](https://modelcontextprotocol.io/) server.\nGmail, Google Calendar, and Google Tasks are available through a Desktop OAuth\nclient in a Google Cloud project you control. Corresync-managed Google OAuth\nremains dormant. The canonical task tools also include explicit Microsoft To\nDo, Todoist, TickTick, and CalDAV VTODO routes; remaining task-provider adapters\nstay unavailable until their contracts are implemented.\n\n- Search mail and build one agenda across accounts without collapsing their\n identity or provider provenance.\n- Use one stable, provenance-preserving task model as provider adapters become\n available.\n- Save private account-local mail searches and relative calendar windows, then\n run them live without creating a shadow mailbox or calendar cache.\n- Use the same typed operations from a human-friendly CLI, stable JSON, or an\n AI agent.\n- Keep sign-in in a visible browser, an explicit public-client OAuth flow, or\n an approved local credential store.\n- Review consequential effects before they happen. Unknown remote outcomes\n stop for reconciliation instead of being retried automatically.\n\n## What it feels like\n\n```console\n$ corr mail search --all-accounts \\\n --query 'subject:\"Quarterly plan\"' --limit 3\n● work · microsoft-owa Ana Ruiz Plan review\n· personal · jmap Finance Plan receipt\n\n$ corr agenda list --all-accounts \\\n --start 2026-07-29T00:00:00Z \\\n --end 2026-07-30T00:00:00Z\n```\n\nConnect an agent to the same local core:\n\n```console\ncorr integrations detect\ncorr integrations plan codex claude-code\ncorr integrations setup codex claude-code\n# Phase A also includes github-copilot, gemini-cli, qwen-code, qoder, kimi-code\n```\n\nThen ask naturally:\n\n```text\nCheck my inboxes, calendars, and task lists and summarize what needs attention today.\n```\n\nOne failed provider becomes an explicit partial failure. Successful results\nremain available, and writes still require one exact account.\n\n## Choose the route that fits\n\nMail, calendar, and task routes are selected independently. For example, an\naccount can pair IMAP/SMTP mail with a CalDAV calendar; its task route remains a\nseparate explicit choice.\n\n\n| Route | Mail | Calendar | Tasks | Authentication |\n| --- | --- | --- | --- | --- |\n| Outlook Web | Typed reads and writes | Selectable calendars; provider-supported Teams link | — | Dedicated visible browser profile |\n| 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 |\n| Microsoft Graph | Typed reads and writes | Selectable calendars; typed Teams-link creation | Microsoft To Do | Your authorized public OAuth client; OS-keyring grant |\n| Todoist | — | — | Typed Todoist operations | Your authorized public OAuth client; OS-keyring grant |\n| TickTick | — | — | Typed TickTick operations | Your authorized confidential OAuth client; external secret handle and OS-keyring grant |\n| JMAP | Typed mail operations | — | — | OS keyring or approved credential helper |\n| IMAP / SMTP | IMAP read/manage and SMTP draft/send | — | — | OS keyring or approved credential helper |\n| CalDAV | — | Typed calendar operations and conditional scheduling | VTODO lists, search, sync, and reviewed writes | OS keyring or approved credential helper |\n\n\nDiscovery gathers DNS, well-known, and provider metadata without credentials.\nIt never authenticates or adds an account. Microsoft Graph and user-owned\nGoogle authorization remain explicit choices and are never automatic\nfallbacks. Google discovery can offer guided Desktop-client setup, but no\nGoogle sign-in starts until a later explicit `corr auth login`. See the\n[annotated Google setup guide](docs/google-oauth-setup.md).\n\niCloud has a first-class guided preset over the same provider-neutral\nIMAP/SMTP and CalDAV adapters. `corr setup` recognizes documented iCloud Mail\naddress families or the complete verified Apple SRV endpoint set, reviews both\nroutes as one account, and uses one external credential handle by default.\nAfter the account is added, an explicit handoff can open Apple's app-password\npage and the OS-owned credential prompt; the `corr` process never reads the\napp-specific password.\n\nEvery available v0.9 route above has synthetic provider-contract and\napplication coverage. The user-owned Google API route is available but\nlive-unobserved. Other provider and platform implementations remain\n**live-unobserved** until an authorized, content-free observation is bound to\nthe exact commit. See [compatibility evidence](docs/compatibility.md) before\nconnecting a sensitive account.\n\n## From install to a first read\n\nPrefer a guided page? Follow\n[getting started on the website](https://corresync.org/getting-started.html).\n\n### 1. Install\n\nThe official standalone installers are the shortest path on every platform.\nThey select the latest stable release, verify its archive and candidate binary,\ninstall for the current user without elevation, and leave account setup untouched.\n\n#### macOS and Linux\n\n```console\ncurl -LsSf https://corresync.org/install.sh | sh\ncorr --version\n```\n\n#### Windows PowerShell\n\n```powershell\npowershell -NoProfile -Command \"irm https://corresync.org/install.ps1 | iex\"\ncorr --version\n```\n\nReview [`install.sh`](https://corresync.org/install.sh) or\n[`install.ps1`](https://corresync.org/install.ps1) before running it if you\nprefer. Package managers remain fully supported alternatives:\n\n```console\n# Homebrew · macOS or Linux\nbrew install nkiyohara/corresync/corresync\n\n# WinGet · Windows\nwinget install --id nkiyohara.Corresync --exact\n\n# Scoop · Windows\nscoop bucket add corresync https://github.com/nkiyohara/scoop-corresync\nscoop install corresync/corresync\n```\n\nDirect archives, native Linux packages, version pinning, checksums, and\nSigstore provenance are in the [installation guide](docs/install.md). The\n[guided website](https://corresync.org/getting-started.html#step-install) keeps\nthe same copy-paste choices visible for people who do not use GitHub regularly.\n\nClaude Desktop users can also install the platform-universal `.mcpb` from the\n[latest release](https://github.com/nkiyohara/corresync/releases/latest).\nThe bundle runs the same verified `corr mcp serve` binary locally over stdio;\nit does not deploy Corresync or relay mailbox data. Install the CLI first for\nthe explicit account setup and sign-in steps below, then open or drag the\n`.mcpb` into Claude Desktop.\n\n### Stay current\n\nInteractive commands make a quiet, cached release check at startup. If an\nupdate exists, Corresync shows the exact command for your installation:\n`corr update` for the standalone build, or the matching Homebrew, Scoop, or\nWinGet command. Package-managed files are never changed by Corresync.\n\nStable releases are selected by default. Standalone users who want signed\nrelease candidates can choose the preview channel interactively:\n\n```console\ncorr settings\n```\n\nThe equivalent copy-paste commands for scripts are:\n\n```console\ncorr config set updates.channel preview\ncorr update\n```\n\nSwitch back with `corr config set updates.channel stable`; Corresync never\ndowngrades the running binary. Preview releases do not enter package-manager\ncatalogs.\n\nStandalone users can opt in to verified automatic installation:\n\n```console\ncorr config set updates.auto_install true\n```\n\nIt never runs during MCP tool calls, configuration changes, daemon work, JSON\noutput, pipes, or other non-interactive paths. The current command continues\nnormally and the new binary is active on the next `corr` start.\n\n### 2. Add and sign in to your account\n\n```console\ncorr setup\n```\n\nThe guided setup derives a resumable preflight from current local state,\noptionally installs shell completion at a displayed user-local path, and then\nperforms credential-free account discovery. It previews the selected\nmail/calendar/task routes and adds an account only after confirmation.\nAuthentication or external-credential access remains a separate choice. The\nsame run can add more accounts, select several detected agent hosts, preview\ntheir independent local integration plans, apply only one confirmed plan, and\nverify each result. Re-running `corr setup` skips healthy work and offers the\nmissing or repairable steps.\n\nAfter choosing a connection route, the wizard presents a service checklist.\nFor a Microsoft account, Outlook Mail and Calendar are preselected and can be\nchanged independently; Microsoft To Do is an optional, explicit Graph\nauthorization. Teams messaging is shown as coming soon while the v0.9 release\ngate is closed and cannot be selected, persisted, or opened. Discovery is only\nroute evidence: it never proves that any checked service is enabled for the\naccount, and it never triggers a Graph fallback.\n\nRun `corr settings` to open the same account wizard; sign in to, rename,\nselect, or remove accounts; and manage updates, safety, and browser sign-in\nfrom an arrow-key form. Its Setup guide entry resumes the complete coordinator\ninstead of maintaining another implementation. The\ntop-level Accounts category contains Add account and the configured account\nlist; selecting an account opens only actions for that account. Removal\npreviews the local data it deletes and asks for confirmation; removing the\ndefault first asks which remaining account should replace it. Each choice also\ndisplays the equivalent command, so the interactive flow teaches the direct\nCLI.\nSet `CORRESYNC_ACCESSIBLE=true` for line-oriented screen-reader prompts; type\n`:cancel` to leave an input step safely. The direct rename form remains:\n\n```console\ncorr account rename personal work\n```\n\nScripts and advanced users retain the deterministic form:\n\n```console\ncorr setup you@example.com --alias personal\ncorr auth login --account personal\ncorr doctor --account personal\n```\n\nThe direct `setup ADDRESS` form creates the same provider-neutral, secret-free\nlocal configuration, performs credential-free discovery, and adds only an\nautomatically selectable first-party route. It never opens a sign-in page.\nAuthentication is a separate, account-specific action.\n\nIf no route can be selected safely—or if you want an API or standards route—\ninspect the evidence and choose the exact provider settings:\n\n```console\ncorr account discover reader@example.invalid\ncorr account add reader@example.invalid --help\n```\n\nFor Gmail, Google Calendar, and Google Tasks, create a Desktop OAuth client in\na Google Cloud project you control. Guided setup validates the downloaded\nclient JSON and places its generated credential in the OS keyring; account\naddition still does not authenticate. Follow the\n[Google OAuth setup guide](docs/google-oauth-setup.md) for current Cloud\nConsole screens, audience choices, exact APIs, scopes, import, and login.\n\nBefore installing, the optional\n[provider compatibility checker](https://corresync.org/providers.html#check)\ncan classify public evidence for an address. The browser sends only the domain\nafter the `@` in a request body; it never sends the local part, persists the\naddress, or starts sign-in. The public service uses only a fixed DNS resolver\nand returns no raw DNS record. Skip it whenever you prefer and run `corr account\ndiscover ADDRESS` locally.\n\nAccount addition does not authenticate. OAuth routes require a client\nregistration you are authorized to use. Google additionally requires a\nseparate external handle for its generated Desktop client credential.\nStandards routes use a keyring entry\nor explicitly approved helper reference. Passwords and tokens never enter\n`config.toml`. See [account and provider configuration](docs/configuration.md).\nThe Outlook Web route opens a dedicated visible profile during the later\n`auth login`; that window remains the browser-owned session until account\nlogout or daemon shutdown. SSO, MFA, Conditional Access, and organization\nnotices remain inside the provider-owned flow.\n\n### 3. Connect an agent\n\n```console\ncorr mcp setup codex\n```\n\nUse `corr mcp --help` for Claude Code, GitHub Copilot CLI, Gemini CLI, Qwen\nCode, Qoder, Kimi Code CLI, and generic stdio clients. Corresync exposes 45\nnarrow tools and two read-only monitor resources; there is no HTTP, SSE,\nremote MCP endpoint, or hosted relay.\n\n## Nothing sends on the first attempt\n\nConsequential writes use a server-enforced `preview -> commit` protocol. The\nfirst command shows the normalized account, provider, target, recipients,\ncontent digest, and version preconditions without performing the effect.\n\n```console\nprintf 'Synthetic body.\\n' | \\\n corr mail send \\\n --account work \\\n --to reader@example.invalid \\\n --subject 'Review example' \\\n --body-file -\n```\n\nAfter reviewing every field, repeat the exact command with approval:\n\n```console\nprintf 'Synthetic body.\\n' | \\\n corr mail send \\\n --account work \\\n --to reader@example.invalid \\\n --subject 'Review example' \\\n --body-file - \\\n --approve\n```\n\nApproval is short-lived, single-use, and bound to the caller, account,\nprovider, target, payload, and effect. Changing any reviewed field invalidates\nit. MCP keeps preview and commit as separate typed tools.\n\n[See the complete safety model](https://corresync.org/safety.html).\nCorresync's public [Privacy Policy](https://corresync.org/privacy.html)\nexplains Google data access, local storage, disclosure, retention, and removal;\nthe [Terms of Use](https://corresync.org/terms.html) preserve\nthe software rights granted by Apache-2.0.\n\n## More than one inbox\n\n- **Cross-account views:** bounded mail search and agenda projections retain\n original account, provider, calendar, time-zone, and partial-failure\n provenance.\n- **Read-only import staging:** inspect an explicitly approved local archive,\n Maildir tree, or supported export without uploading or mutating the source.\n- **Opt-in monitoring:** move deliberately from `off` to local notification,\n durable queueing, and finally one approved no-shell runner. Remote egress is\n a separate consent.\n- **Privacy-preserving feedback:** generate an allowlisted report locally,\n review it, then explicitly copy, save, or open a prefilled GitHub page. A\n separate default-off setting can submit an even smaller allowlist-only public\n issue through your authenticated `gh` client after an interactive failure.\n\nMailbox, calendar, import, and event-queue values are private, untrusted\nexternal data. Their content is never authority to run a command or start an\nagent.\n\n## Honest edges\n\n- Gmail, Google Calendar, and Google Tasks require a user-owned Google Desktop\n OAuth client. Corresync-managed Google OAuth stays disabled; the user-owned\n route is synthetic-contract covered and live-unobserved.\n- Microsoft Graph requires your own authorized public-client registration.\n Corresync ships no token relay.\n- Windows desktop notification setup is unavailable because Corresync does\n not install an AppUserModelID; queue and approved runner modes remain\n available.\n- Provider meeting links are requested only when the selected calendar route\n reports native support.\n- Cross-compilation and synthetic fixtures do not prove native browser,\n keyring, IPC, provider, package-manager, Gatekeeper, or SmartScreen behavior.\n- Teams chat, channels, calls, recordings, and meeting lifecycle management;\n tenant-wide access; unattended login; TLS interception; arbitrary provider\n actions; automatic telemetry; and raw crash upload are outside scope.\n\nThe exact action matrix and typed provider degradations are in\n[features.md](docs/features.md).\n\n## One local safety boundary\n\n```text\nAI agents ───────── MCP over stdio ─┐\n ├── typed use cases + effect policy\nHumans and scripts ──────── corr ───┘ │\n │ authenticated local IPC\n session owner\n ├── browser-owned sessions\n ├── explicit OAuth + keyring\n └── standards adapters\n```\n\nThe session owner exposes no TCP listener. On Unix, clients authenticate and\npin the environment-independent private runtime directory, singleton lock,\nsocket, and peer UID before the local bearer can be sent. On Windows, clients\nverify the protected named pipe, owner, DACL, server process, and SID first.\n\nRead the [architecture](docs/architecture.md),\n[authentication model](docs/authentication.md), and\n[threat model](docs/threat-model.md) for the complete boundaries.\n\n## Documentation\n\n| I want to… | Start here |\n| --- | --- |\n| Install and verify a release | [Installation](docs/install.md) |\n| Add accounts and choose routes | [Configuration](docs/configuration.md) |\n| Understand browser, OAuth, and standards sign-in | [Authentication](docs/authentication.md) |\n| Learn CLI commands | [CLI guide](docs/cli.md) |\n| Connect an AI client | [MCP guide](docs/mcp.md) |\n| Compare provider actions and degradations | [Feature matrix](docs/features.md) |\n| Consume stable machine output | [JSON contract](docs/json.md) |\n| Integrate versioned public/local contracts | [Versioning policy](docs/adr/0020-public-and-local-versioning.md) |\n| Verify compatibility claims | [Evidence matrix](docs/compatibility.md) |\n| Review privacy and Google data handling | [Privacy Policy](https://corresync.org/privacy.html) |\n| Review use and open-source license terms | [Terms of Use](https://corresync.org/terms.html) |\n| Connect Google with your own Desktop client | [Google OAuth setup](docs/google-oauth-setup.md) |\n| Review the dormant managed-client plan | [Google verification runbook](docs/google-oauth-verification.md) |\n| Review every guide | [Documentation map](docs/README.md) |\n\nUsers upgrading from versions before v0.7 can follow the\n[historical migration guide](docs/migration-v0.7.md). `corr` is the primary\ncommand. The product, package, repository, configuration roots, plugin, and MCP\nserver remain named Corresync.\n\n## Contributing and security\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md). Default\ntests and CI use only synthetic fixtures:\n\n```console\nmise exec -- task verify\n```\n\nPlease report vulnerabilities through\n[GitHub private vulnerability reporting](SECURITY.md), never a public issue.\n", "bytes": 20718, "sha": "cd9a11e98f2cc099c752214830eddf223252886feed9ae3651e3172ea752f16b", "repo_slug": "nkiyohara/corresync", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_nkiyohara_corresync_50ff9fbf/readme" }