Connect Local Coding Agents to Thegram for Mac

@gram 2
doc d_127b30e9a5c64e2aa472db36e7214a3d
t Connect Local Coding Agents to Thegram for Mac
::rich
# Connect local coding agents

The Thegram Mac app hosts a local MCP server. Claude Code, Codex, OpenCode and OMP connect on the same Mac while the app is open. This route is distinct from Thegram Cloud: local-only folders do not appear in a cloud connection.

## Prerequisites

- Apple silicon: uname -m prints arm64.
- macOS 26 or later.
- Node.js 22 or later on PATH.
- Thegram installed from https://thegram.one/download/mac/ and running.
- The person at the Mac chooses Agent Access in Thegram → Settings… → Agent Connections. Read is sufficient for inspection; Read and Write allows changes. Never change this setting on the person's behalf.

The local app connection is the Unix socket at ~/Library/Application Support/Thegram/mcp.sock. The app must remain open.

## Select a client and install

The command blocks below are generated from the canonical [local install guide](https://thegram.one/install/agents.md). That guide remains the sole command source; do not substitute cloud endpoint configuration.

Claude Code:

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

Codex:

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

OpenCode:

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

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

OMP:

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

For Codex, the next run asks the person whether to trust plugin hooks; the person chooses Trust all and continue. Alternatively, the person can use Thegram → Settings → Agent Connections → Agent Apps → Install next to the host. Terminal opens and the app reports Connected after installation.

## Verify without writing

1. Keep Thegram open and confirm Connection says Running in Agent Connections. The documented check is: test -S "$HOME/Library/Application Support/Thegram/mcp.sock" && echo running.
2. Start a new agent session in the intended project folder.
3. Use gram_capabilities, then gram_projects, then gram_brief for the exact path returned; use gram_read with outline=true and a returned section heading to inspect only needed content. This sequence is read-only.
4. Expected result: the agent can see the intended project/document, the brief returns a current revision and summary, and gram_read returns the selected section. No write is needed to verify connectivity.

## Troubleshooting

- Socket absent or agent reports unreachable: open Thegram, check Agent Access is not Off, verify Connection is Running, and check that a second Thegram copy is not holding the connection.
- node: command not found or an old version: the person installs Node.js LTS from https://nodejs.org/, opens a new Terminal and repeats the documented setup.
- Plugin reports disconnected: check host plugin installation and start a fresh session. Use the canonical guide's doctor command and its client-specific plugin folder rather than guessing a path.
- Codex asks to trust hooks: this is expected; the person chooses whether to trust them. Do not accept on the person's behalf.
- OpenCode v1 rejects plugin add: follow the v1 configuration route in the canonical guide.

## Source authority

Exact commands, app checks, doctor locations and current host-specific caveats live in https://thegram.one/install/agents.md. The docs landing page links there rather than maintaining a second command list. Source: https://thegram.one/agent-memory/#mac.
::end