Connect Local Coding Agents to Thegram for Mac · r8

Archived revision r8, recorded 2026-10-13T01:47:53.490Z by portal-product-quickstarts. Current page: Connect Coding Agents to Thegram with an API Key.

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.

Local and Cloud: features, permissions and storage

Route	Features observed	Connection / permission	Storage
Local Mac	MCP; Graph UI	Thegram for Mac running; Agent Access enabled by the person	Folders stored on the Mac; local-only folders are not exposed to Cloud.
Cloud	MCP (15 tools); Document, Dashboard; search: exact, keyword; semantic search: unavailable	Thegram account; OAuth sign-in; running Mac required: no	Thegram Cloud vault; Google Drive only when separately connected and authorized.

Runtime observations dated 2026-10-13: User review supplied 2026-10-13; reported product observations, not an independently captured test. The Mac version/build are date-bounded observations, not a current-release pointer. Keep current public Mac release values derived from owner release evidence. If a later owner release differs, refresh this observation only with a new runtime review; never silently relabel the old observation.

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:

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:

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:

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

OMP:

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.

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:

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:

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

Source and renderer evidence

Canonical source SHA-256: 66c7a825c24ce4cc25fac497fd4bf326e95e0771ae237ebf3b330dc7a713df11
Selected revision: r8 · sha256:f2d023acec27af44b333ad3b5354451a3aa70e49c5b2c13b8b86f366d9ea121f
Local renderer: configured local Thegram renderer · API thegram-web-render/1
Core source: git+https://github.com/clab-one/thegram-format.git?rev=b16489e1d0d77d38f82d2f61776524737aa31557#b16489e1d0d77d38f82d2f61776524737aa31557

Canonical source: 8.gram