Connect Local Coding Agents to Thegram for Mac · r10

Archived revision r10, recorded 2026-10-14T02:42:46.837Z 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	Connection / permission	Storage
Local Mac (owner-source supported)	MCP; Document, Dashboard, Graph UI; gram_recall modes: exact, keyword, semantic, hybrid, auto; embeddinggemma-2 semantic retrieval is conditional on model/index readiness. Dynamic; check gram_capabilities semantic status and index counts before semantic retrieval.	Thegram for Mac running; Agent Access (read or write) granted by the person	Local Mac folders plus connected Google Drive and Thegram Cloud vault mounts listed by gram_projects; each mount reports its read/write access.
Cloud (user-reported 2026-10-13)	MCP (15 tools); Document, Dashboard; search: exact, keyword; semantic search: unavailable	Thegram account; OAuth sign-in; running Mac required: no	Thegram Cloud vaults or Google Drive separately connected at vault.thegram.one

Thegram for Mac 0.9.8 (build 33) was reported in use on 2026-10-13; this dated app observation is distinct from the current Mac release, which is sourced from thegram-desktop-release/evidence/release-0100/verification.json. Cloud runtime facts are dated user-reported observations, not an independently captured runtime test. Provenance: User review supplied 2026-10-13; reported runtime observations, not an independently captured test.

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: r10 · sha256:a193a41f0e273e5d1ffd40078f7c9be96e93114caa70a131da228b1d3267e849
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: 10.gram