Skip to content
Thegram Docs

Connect Local Coding Agents to Thegram for Mac · r13

Archived revision r13, recorded 2026-10-14T09:44:44.633Z by portal-product-quickstarts. Current page: Connect Coding Agents to Thegram with an API Key.

Connect local coding agents

Section titled “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

Section titled “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

Section titled “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-release201-final/evidence/release-201/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.

One type, one dashboard

Section titled “One type, one dashboard”

Core 2.0.1 resolves one dashboard per declared document type. The client renders its single ResolvedView/1 result; it does not choose another ViewSpec or compute its own recommendation.

Document type Dashboard
schedule@1 Journal
project@1 Project Tracker
knowledge@1 Knowledge

Without a template declaration, Core recommends a dashboard and the dashboard is read-only. If no recommendation is eligible, it falls back to Project Tracker, still read-only. An unknown id/version or malformed declaration has no dashboard: show the document and Core diagnostics without automatically choosing another type.

A folder opens one home screen. There are no per-document screen tabs, sidebar screen lists, ViewSpec switchers or search/filter/sort/group query toolbar. Document and dashboard are representations of the same file, not separate copies.

Templates still choose a type when creating a document, validate governed writes, supply AI authoring rules and define typed actions. A read-only recommended dashboard does not forbid ordinary document editing through the normal authorized write path.

For declaration and writing rules, see View templates.

Select a client and install

Section titled “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:

Terminal window
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:

Terminal window
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:

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

OMP:

Terminal window
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

Section titled “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

Section titled “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

Section titled “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
r13 · sha256:c39c7c1ba3d34ecb6739a466cac5927f04098f47b00cdfcd1be730eda25994dc
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: 13.gram