Connect Local Coding Agents to Thegram for Mac

@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