# Cortland 🍎

**Your agent brings the brain. Cortland brings the hands — and the human gate.**

Give an AI real access to your Mac — Mail, Calendar, Reminders, Notes, files —
without giving it the keys. Every consequential action previews first, waits for
your approval through a channel the model can't touch, gets logged, and can be
undone.

Cortland has no model of its own, no cloud, and no web access. That is the
point. Whatever agent you already use — Claude, Codex, Cursor, or a local Gemma
that never leaves the machine — gets a governed way to touch your real data and
to reach you.

---

## A worked example

An agent watched a handful of retailer pages for days, waiting for a limited-run
controller to come back in stock. When it finally did — unattended, at an hour I
was nowhere near my desk — my phone buzzed with an iMessage. I bought one.

**Cortland never touched a website.** It has no web-fetch tool and never has.
The watching was done by a coding agent with internet access. Cortland was the
part that reached me: on my own Mac, through Messages, with the recipient fixed
in local config so nothing the agent generated could point that message at
anyone else.

That division is the pitch in one story. Your agent has the reasoning and the
internet. Cortland has your Mac, your Apple apps, and your attention — and every
outward action still stops to ask.

### The part worth telling

The first version cheated, and I only found out by reading my own audit log.

No governed "tell the human" tool existed. The iMessage bridge could *answer*
me, but nothing could start a conversation — so the monitor imported Cortland's
send module directly and called it. It worked, and it was genuinely Cortland
doing the sending: same owner handle from config, same AppleScript escaping,
same hourly rate cap. But it went *around* the framework instead of through it,
so days of running left **zero audit rows**.

That is this project failing its own test. A guarantee with no legitimate path
through it is a guarantee people route around — and the person who routed around
it was the one who wrote the guarantee.

The fix is [`notify_owner`](packages/imessage): write-safe, because a message to
you is not an outward action, it *is* the review loop. It has no recipient
argument at all — the handle comes from local config, so no model output and no
injected content can redirect it. Its hourly cap is counted from the audit log
rather than from memory, so a cron job that starts fresh every run still can't
exceed it. A notification now leaves a row behind. This one is real, copied out
of the audit DB after sending a test message to my own phone:

```
notify_owner | Messages | write-safe | undo=none | dry_run=0 | ok
principal: cli:notify   tool_version: 0.2.0
args: {"text":{"redacted":true,"length":84,"sha256":"3e389e33…"},
       "source":"cortland-test"}
```

The body is stored as a length and a hash — the row proves a message was sent
without keeping what it said. `source` stays readable because it is a label,
constrained to a slug, and not content anyone can compose.

---

## What it looks like in use

**Text it like a contact** — the bridge, answered by a 4 GB model on an 8 GB
MacBook Air. Nothing left the Mac:

```
You:       Add a reminder to call the vet tomorrow at 2pm
Cortland: Received — working on it…
Cortland: Added "Call vet" for tomorrow, Aug 3 at 2:00 PM.
```

The texting interface needs a **second Apple ID**, signed into Messages on the
Mac only — a mouthpiece, not a worker. It owns no mail, no calendar, no data.
You text it from your phone like any contact; the Mac still does the work as
*you*. Your system iCloud stays yours. Claude Code, Cursor, Codex, and other
MCP clients skip this step: they talk to the same tools over stdio.

**Ask about your week** — reads are free, no approval needed:

```
You:       Anything from the school this week?
Cortland: Three emails from Lincoln Elementary. Two are the weekly
            newsletter; one from Ms. Alvarez on Tuesday asks for a
            permission slip by Friday.
```

**Ask it to change something** — writes stop and ask, every time:

<p align="center">
  <img src="docs/images/imessage-approval.svg" alt="An iMessage thread: the user asks to delete a reminder; Cortland acknowledges, then replies with an approval request naming the reminder, its list, and its due date, asking the user to reply &quot;yes a3f9c1&quot;; the user replies with the code; Cortland confirms the deletion with the same details." width="430">
</p>

The code in that prompt is generated by the framework and never enters the
model's context — so even a fully prompt-injected model can't forge your
approval. Ignore the message and the action expires, refused.

**Ask what it can do** — answered from the tools actually installed, so it
can't overclaim:

```
You:       what can you do?
Cortland: Here's what I can do with your Mac:
            • Calendar: list, look up, create, delete
            • Mail: search, read, follow threads, draft, send (asks first), flag, file
            • Notes: search, read, create, add to
            • Reminders: list, search, create, tick off, delete

            Anything that deletes or changes things asks you first — I text
            you a code and wait for "yes <code>". Reads just happen.
```

**In Claude Code or Claude Desktop**, the same tools are just there:

> **You:** send a reply to Ms. Alvarez saying the slip is coming Thursday
> **Claude:** *[searches mail, reads the thread]* I can send this from your
> Personal account to alex@example.com. Approve in the usual channel.

`mail_send` is write-gated. Live mode plus per-action human approval. A stolen
token can only *ask*.

---

## Requirements

macOS only. Nothing here runs on Windows or Linux — the tools talk to Apple
apps via Automation.

| | Minimum | Comfortable |
|---|---|---|
| **OS** | macOS 13 Ventura | macOS 15+ |
| **Mac** | Any Mac that runs Ventura (Intel can drive Cursor/Claude) | Apple Silicon (M1 or newer) |
| **Node** | 20 LTS (`node -v`) | 22 |
| **Toolchain** | Xcode Command Line Tools (`xcode-select -p`) | same — `better-sqlite3` compiles native code |
| **Client** | One MCP app: Cursor, Claude Code, Claude Desktop, Codex, or LM Studio | plus Ollama if you want to **text** it |
| **RAM** | 8 GB (cloud/Cursor model, or Gemma 4 E2B) | 16 GB+ for larger local models |
| **Disk** | ~500 MB for this repo’s build | **+6 GB** if you pull `gemma4:e2b-it-qat` |
| **Apple apps** | The apps you want touched, signed in as you | Mail + Reminders is the usual first pair |

**iMessage bridge only:** macOS 13+ (modern `chat.db`), Full Disk Access for
the process that runs Node, Automation → Messages, and a **second Apple ID**
signed into Messages.app — not into System Settings. See
[SETUP.md §5.1](SETUP.md#51-create-the-assistants-apple-id).

**Osaurus as a client:** Apple Silicon, macOS 15.5+.

Not required: a developer account, iCloud for Path A, or any API key.

---

## Quick start

**Fastest path to “it searched my mail”** — Cursor (or Claude Code) as the
brain, no second Apple ID, no Ollama:

```bash
xcode-select --install          # if `xcode-select -p` fails
git clone https://github.com/cortland-suite/cortland.git
cd cortland
npm install && npm run build    # first install compiles sqlite — a minute
```

Then Cursor Settings → MCP, add servers pointing `node` at
`packages/mail/dist/server.js` (and reminders/notes/calendar if you want
them). Absolute paths. JSON is in
**[docs/08_local_models.md](docs/08_local_models.md#cursor)**.

Ask: *search my mail for anything from school this week.* macOS will prompt
**Automation** (Cursor → Mail). Allow it.

Writes stay previews until you set `"live": true` in
`~/Library/Application Support/cortland/config.json`. Even then, send/delete
asks you per action.

**Texting it from your phone** is a longer path (second Apple ID + Ollama).
[SETUP.md](SETUP.md) is the ordered list; [docs/08](docs/08_local_models.md)
is the illustrated one.

---

## Why it exists

Most MCP servers for personal data are thin wrappers around AppleScript:
`delete_email`, `send_message`, executed the instant a model calls them. That's
a hard thing to trust with an inbox, and the alternatives don't help — cloud
assistants (Poke, Arlo, Lindy) can't touch Apple-native data at all, because
Apple gives them no API, and self-hosted agents like OpenClaw run ungoverned
(a CVSS 8.8 in January 2026, with permission gates still on the roadmap).

Cortland inverts the default. A tool call *previews* what it would do unless
you've opted into live mode, and even then every consequential action waits for
you. The framework enforcing that is a small library with a test suite proving
each guarantee can't be bypassed — and every tool in the suite is built on it.

---

## The guarantees

| | |
|---|---|
| **Dry-run by default** | Gated tools preview instead of executing. Every config error resolves *toward* dry-run. |
| **The human gate is out-of-band** | Approval arrives via a native dialog, a file you move, your client's own UI, or a text you reply to — never through model text. |
| **Everything is audited** | Success, failure, dry-run, denial, refusal: one local SQLite row each. "What did my tools actually do?" always has an answer. |
| **Undo is enforced at registration** | A tool claiming native undo must produce a recipe *before* the write, or the framework refuses it. |
| **Content is data, not instructions** | Everything read from mail, notes, or messages returns inside a nonce-delimited fence. |
| **Safety by absence** | No ungated send. No attendee invitations. No reading conversations other than your own. |
| **Local-first** | No accounts, no credentials, no cloud. Your model, your machine, your disk. |

---

## Install

From the repo:

```bash
git clone https://github.com/cortland-suite/cortland.git
cd cortland
npm install
npm run build
npx cortland setup
```

The wizard asks before every step and records what it did. Full walkthrough —
including the iMessage bridge, permissions, and model choice — in
**[SETUP.md](SETUP.md)**. Connecting Cursor, Codex, LM Studio, Osaurus, or
Ollama: **[docs/08_local_models.md](docs/08_local_models.md)**.

---

## Packages

| Package | What it does |
|---|---|
| [`@cortland/governed`](packages/governed) | The framework: dry-run defaults, approval gates, audit, provenance, undo, injection fencing. Build your own governed tools on it. |
| [`@cortland/mail`](packages/mail) | Apple Mail: read, search (two tiers), threads, drafts, send (write-gated). |
| [`@cortland/reminders`](packages/reminders) | Reminders: lists, search, create, complete, delete — with native undo. |
| [`@cortland/notes`](packages/notes) | Notes: folders, search, read, create, append. |
| [`@cortland/calendar`](packages/calendar) | Calendar: window queries, create, delete. Cannot send invitations, by design. |
| [`@cortland/context`](packages/context) | Local context layer: mail/calendar *metadata* (pointers, never bodies), briefings, person lookups, a corrections flywheel. |
| [`@cortland/imessage`](packages/imessage) | Text your own AI. Second Apple ID in Messages (mouthpiece only); owner-only by construction, approvals by reply, plus `notify_owner` so an unattended agent can reach you first. |
| [`@cortland/folders`](packages/folders) | Folder-as-API: drop a file in iCloud from any device, a declared local pipeline runs. |
| [`@cortland/remote`](packages/remote) | Reach the suite from your other devices over your own private network. |
| [`@cortland/setup`](packages/setup) | The onboarding wizard. |

---

## Bring your own model

Cortland is the tools. You pick the brain.

<p align="center">
  <img src="docs/images/two-paths.svg" alt="Path A: an MCP client hosts the model and Cortland is a plugin. Path B: you text an iMessage bridge; Ollama is the brain; the Mac still acts as you." width="860">
</p>

**Path A.** Cursor, Claude Code, Claude Desktop, Codex, LM Studio, or Osaurus
hosts the model. Cortland is an MCP plugin. No second Apple ID.

**Path B.** You text it. A second Apple ID signs into Messages on the Mac
(mouthpiece only). Ollama runs Gemma 4 on disk. Approvals are `yes <code>`
in the same thread.

Field-tested on an 8 GB M2: `gemma4:e2b-it-qat` (4.3 GB) makes clean tool
calls and refuses honestly. The governed contract matters *more* with a
small model, not less.

**Walkthroughs, including LM Studio and Osaurus from a clean install:**
**[docs/08_local_models.md](docs/08_local_models.md)**. Clean-Mac order,
permissions, and the iMessage second-ID steps: **[SETUP.md](SETUP.md)**.

---

## Privacy model

- **Pointers, not copies.** The context layer stores metadata referencing
  messages by ID; bodies are never stored. Delete a message in Mail and the
  pointer dangles and gets pruned.
- **Model use is opt-in and declared.** Works fully deterministically with no
  model. Configure one and its network egress is declared in config and
  recorded in the audit log on every run.
- **Nothing phones home.** The only optional outbound call is a push ping you
  configure yourself, and its body is a fixed string carrying no information.

---

## Docs

- **[SETUP.md](SETUP.md)** — clean Mac to working assistant, with the gotchas.
- **[docs/08_local_models.md](docs/08_local_models.md)** — connect Cursor, Codex,
  LM Studio, Osaurus, or Ollama; illustrated, from zero.
- **[SECURITY.md](SECURITY.md)** — reporting, and what's in scope.
- **`docs/`** — one design doc per component: the framework contract (01),
  Mail (02), folder-as-API (03), the context layer (04), remote access (05),
  the iMessage bridge (06), the threat model / review guide (07), and local
  models (08).
- **`NOTES.md`** — the engineering log: decisions with dates, open questions,
  and every field finding, including the ones that were embarrassing.

## License

MIT. See [LICENSE](LICENSE).