@gram 2
doc d_127b30e9a5c64e2aa472db36e7214a3d
t Connect Local Coding Agents to Thegram for Mac
d Meet current Mac and Node prerequisites, let the person enable Agent Access, then install a host plugin and verify read-only.
tag guides
tag local
view document
::rich
# Connect local coding agents

The Thegram Mac app hosts a local MCP server. Claude Code, Codex, OpenCode and OMP connect on this Mac while the app is open. Local-only folders are not available to a Cloud connection.

## Prerequisites

- Apple silicon (arm64); macOS 26 or later; Node.js 22+ on PATH.
- Thegram installed and running. The app must remain open; its local MCP socket is ~/Library/Application Support/Thegram/mcp.sock.
- The person chooses Agent Access in Thegram → Settings… → Agent Connections. Read is sufficient for inspection. Never change this setting on the person’s behalf.

## Select a client and install

These exact command blocks come from the canonical local install source. Run only the block for the chosen host; the person handles install commands and host trust prompts.

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@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
```

OMP:

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

## Verify without writing

Use gram_projects to choose the project folder, then gram_brief with the returned project name to list its exact document paths. Read a path from that list without optional arguments to receive its outline; pass a returned heading as section only for the next read.

```js
gram_capabilities({})
gram_projects({})
gram_brief({ "folder": "<project folder or mount key returned by gram_projects>" })
gram_read({ "path": "<exact document path in gram_brief docs>" })
gram_read({ "path": "<same document path>", "section": "<heading returned by gram_read outline>" })
```

Expected: the intended project and existing document appear with current revision/hash; the direct read supplies the outline and the section read returns its content. No write is needed to verify connectivity.

## Troubleshooting

- Socket absent or unreachable: open Thegram, ask the person to review Agent Access, confirm Connection is Running, and check no second app copy holds the socket.
- Node missing or old: the person installs the current Node.js prerequisite from https://nodejs.org and opens a fresh Terminal.
- Plugin disconnected: follow the canonical guide’s host-specific doctor check and start a new session.
- Codex trust prompt or any account/permission prompt: the person decides; do not accept or change it on their behalf.

## Optional first save and search

Keep installation and the checks above read-only. Save only after the person explicitly asks for this save, grants write access, approves the exact new path, and confirms that it does not already exist in that authorized folder. Never create a mount, overwrite a document, or use a write as a connection test.

Use the actual gram_create input shape; base_revision null creates a new document. Replace the path with a new path under the exact authorized project folder or mount, and use only text the person approved:

```js
gram_create({
  "path": "<authorized-folder>/setup-notes.gram",
  "title": "Setup notes",
  "base_revision": null,
  "content": "# Setup notes"
})
```

Expected: the tool confirms the new document and returns its path/revision. Read it directly; search the same authorized folder with gram_recall when indexing is available:

```js
gram_read({ "path": "<exact path returned by gram_create>" })
gram_recall({
  "query": "setup notes",
  "folder": "<same authorized folder or mount key>",
  "top_k": 5
})
```

Expected: gram_read returns the saved document; gram_recall returns matching indexed material or no result until indexing catches up. Both retrieval calls are read-only.

Exact host commands and caveats: https://thegram.one/install/agents.md
::end

@gram-history 6
@rev 0 2026-10-12T13:01:57.716Z agent agent=omp-coding-agent 4654e187b285eaeff23cf820535c6e99622998b460a385814ef9f80b070047ea
@rev 1 2026-10-12T13:05:13.995Z agent agent=omp-coding-agent req=product-local-setup-command-sync-20261012 dig=a7af55e2385ecada ddb47d5506ece17377086151ea0d2afad3e46562d1b0bf55d9edc9b61e58c02e
@@ 20 1 1
Use the exact current command block in [the canonical local install guide](https://thegram.one/install/agents.md); it is the command source used by both the landing install page and product quickstarts. Do not substitute cloud endpoint configuration.
@@ 22 1 4
- Claude Code: choose its block in the guide; it installs the thegram-memory plugin and marketplace.
- Codex: choose its block; hooks are enabled and the plugin is installed. On the next run, Codex asks whether to trust the plugin hooks; the person must choose Trust all and continue.
- OpenCode: use the documented plugin add flow for current versions. OpenCode v1 uses the plugin array in ~/.config/opencode/opencode.json instead.
- OMP: choose its marketplace/install block.
@@ 24 32 1
The person can instead use Thegram → Settings → Agent Connections → Agent Apps → Install next to the chosen host. The app opens Terminal and reports Connected after installation.
@rev 2 2026-10-12T13:08:03.655Z agent agent=omp-coding-agent req=product-local-setup-command-sync-v2-20261012 dig=3f9fedf48043656f fb851b5b53210b2a9654db52f22b3641efb3be8777fee8354889bcad5011898e
@@ 25 1 1
claude mcp remove --scope user thegram 2>/dev/null || true
@@ 28 1 0
@@ 34 2 1
codex mcp remove thegram 2>/dev/null || true
@rev 3 2026-10-12T13:13:25.932Z agent agent=omp-coding-agent req=product-local-setup-codex-runtime-sync-20261012 dig=e27c7591482462af d24926f04747bbdfbdb91553a126845794a528af9b9485228d48fc613ade881a
@@ 35 1 1
codex plugin remove thegram-local@thegram-local >/dev/null 2>&1 || true
@rev 4 2026-10-12T13:38:02.496Z portal-product-quickstarts agent=developer-doc-generator req=portal-product-local-setup-f88898f27151d8bd105605ab dig=b24bfe6051dcb656 kind=SourceImported 86da7e0b60286b443ab77eea2ebd983d3d6f22e55637832d0b2df25b9174929f
@@ 3 5 1
::rich
@@ 10 1 1
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.
@@ 14 3 5
- 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.
@@ 18 0 2
The local app connection is the Unix socket at ~/Library/Application Support/Thegram/mcp.sock. The app must remain open.

@@ 20 1 1
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.
@@ 28 1 1
claude plugin update thegram-memory || true
@@ 47 0 2
OpenCode v1 has no plugin add command; add github:clab-one/thegram-mcp to the plugin array in ~/.config/opencode/opencode.json.

@@ 55 0 2
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.

@@ 57 3 4
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.
@@ 63 4 5
- 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.
@@ 68 1 3
## 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.
@rev 5 2026-10-12T13:47:34.160Z portal-product-quickstarts agent=developer-doc-generator req=portal-product-local-setup-f3ad0e9bc1fee9e15261bff9 dig=bb9eb5bed7f8039a kind=SourceImported b24003731b2533a737b6f7468c0b1d1987475928a41a8b995b2a1ef17d557430
@@ 7 1 1
::body
@rev 6 2026-10-12T14:10:29.156Z portal-product-quickstarts agent=developer-doc-generator req=portal-product-local-setup-526450811690221dca4a3b66 dig=ef74b67ae3a63b08 kind=SourceImported d132f425b72aa56b02a3fe68981ba47952c2392c9737c37cb7c17ec21af1a1bb
@@ 57 1 3
1. Keep Thegram open and confirm Connection says Running in Agent Connections.
2. Call gram_capabilities, gram_projects and gram_brief for the exact returned path; call gram_read without section to get its outline, then gram_read with a returned heading as section. This is read-only.
3. Expected: the intended project is visible and the brief/read return current revision and content. No write is needed to verify connectivity.
@@ 59 10 0
@@ 75 28 0