# Install Thegram for a coding agent on a Mac

For Claude Code, Codex, OpenCode and OMP. Thegram is a Mac app that keeps project memory in `.gram` files. The `thegram-memory` plugin (public source: https://github.com/clab-one/thegram-mcp) gives you its `gram_*` tools, hands you the project brief when a session starts and reminds you to record outcomes.

You are the agent. Work through the steps in order. Run every check and command yourself. Steps marked **Ask the person** need their hands: say exactly what to click, wait until they confirm, then run the check again. Talk to them in their language. Never skip a failed check; stop and explain it instead.

## 1. Check this Mac

1. `uname -m` must print `arm64` and `sw_vers -productVersion` must be 26 or later. Otherwise stop: Thegram needs Apple silicon and macOS 26.
2. `test -d /Applications/Thegram.app && echo installed`. If nothing prints, **ask the person** to install the app:
   1. Open https://thegram.one/download/mac/ in a browser. `Thegram.dmg` downloads.
   2. Open `Thegram.dmg` from Downloads and drag **Thegram** onto **Applications** in the window that appears.
   3. Open Thegram from Applications. If macOS asks whether to open an app downloaded from the Internet, choose **Open**. The app is signed and notarized by Apple. Signing in is optional.
3. `node --version` must print v22 or later. If node is missing or older, **ask the person** to install the LTS version from https://nodejs.org. If `brew` exists you may offer `brew install node`, but run it only after they agree.

## 2. Turn on agent access

**Ask the person**: in Thegram, open **Thegram → Settings…** (⌘,) → **Agent Connections** and set **Agent Access** to **Read and Write**. **Connection** then shows **Running**. Agents reach Thegram only while the app is open, so it must stay open.

Check: `test -S "$HOME/Library/Application Support/Thegram/mcp.sock" && echo running`.

## 3. Install the plugin

Run the block for the agent you are. If a server named `thegram` was added by hand earlier, the first line removes it so the plugin's server is the only one.

Claude Code:

```sh
claude mcp remove --scope user thegram 2>/dev/null || true
claude plugin marketplace add clab-one/thegram-mcp || claude plugin marketplace update thegram-memory
claude plugin install thegram-memory@thegram-memory
```

Codex:

```sh
codex mcp remove thegram 2>/dev/null || true
codex features enable hooks
codex plugin marketplace add clab-one/thegram-mcp || codex plugin marketplace upgrade
codex plugin add thegram-memory@thegram-memory
```

Tell the person that the next Codex run asks whether to trust the plugin's hooks, and that they should choose **Trust all and continue**.

OpenCode:

```sh
opencode plugin add github:clab-one/thegram-mcp
```

OpenCode v1 has no `plugin add`; add `"github:clab-one/thegram-mcp"` to the `plugin` array in `~/.config/opencode/opencode.json` instead.

OMP:

```sh
omp plugin marketplace add clab-one/thegram-mcp || true
omp plugin install thegram-memory@thegram-memory
omp plugin upgrade thegram-memory || true
```

The person can run the same install from the app instead: **Settings → Agent Connections → Agent Apps → Install** next to the agent. Terminal opens, and the row shows **Connected** when it is done.

## 4. Check the connection

Find `dist/thegram-memory.mjs` in the newest installed version of the plugin and run `doctor` from the project directory:

| Agent | Plugin folder |
|---|---|
| Claude Code | `~/.claude/plugins/cache/thegram-memory/thegram-memory/<version>/` |
| Codex | `~/.codex/plugins/cache/thegram-memory/thegram-memory/<version>/` |
| OMP | `~/.omp/plugins/cache/plugins/thegram-memory___thegram-memory___<version>/` |
| OpenCode | `~/.cache/opencode/npm/<…>/node_modules/thegram-memory/` |

```sh
node <plugin folder>/dist/thegram-memory.mjs doctor
```

Exit code 0 prints a `socket:` line, `vault: <folder> · access write` and `project: <name> for <directory>`. Exit code 1 means the app is not reachable: Thegram is closed, **Agent Access** is **Off**, or another copy of Thegram holds the connection. Go back to step 2.

## 5. Finish

The plugin loads in a new session. Tell the person, in a few lines:

- Thegram is connected, and with what access (`read` or `write`).
- They should start a new session of this agent; from then on it gets the project brief from Thegram at the start.
- Each git repository gets a folder of the same name in Thegram, which they can open in the app to see decisions, tasks and history.
- A first thing to try: “What does Thegram remember about this project?”

Help: support@thegram.one · Guide for people: https://thegram.one/install/#mac