---
title: Connect a coding agent
description: Install the canonical plugin for Claude Code, Codex, OpenCode or OMP, connect a scoped API key privately and resolve your existing project.
url: https://docs.thegram.one/guides/local-setup/
lang: en
tier: current
status:
  component: Coding agent plugin (thegram-memory)
  deployment: Cloud MCP https://vault.thegram.one/mcp
  applies_to_version: Latest
  status: GA
  last_verified: "2026-10-25"
  owner: thegram-one/thegram-mcp
  public_evidence:
    - https://thegram.one/install/agents.md
    - https://github.com/thegram-one/thegram-mcp
  rationale: Commands are generated from the canonical public installation guide. Project discovery follows the current public repository-tag contract; this page does not run an installer or grant access.
historical_source: https://docs.thegram.one/sources/local-setup.gram
editorial_sources:
  - https://thegram.one/install/agents.md
  - https://github.com/thegram-one/thegram-mcp
---

# Connect a coding agent

## Choose your coding agent {#h0-5}

### Claude Code

```sh
claude mcp remove --scope user thegram >/dev/null 2>&1 || true
claude plugin marketplace add thegram-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 thegram-one/thegram-mcp || codex plugin marketplace upgrade
codex plugin add thegram-memory@thegram-memory
```

### OpenCode

```sh
opencode plugin add github:thegram-one/thegram-mcp
```

### OMP

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

Source: https://thegram.one/install/agents.md

<div class="gram-doc-anchor" id="e0-d_127b30e9a5c64e2aa472db36e7214a3d"></div>

## Before you connect {#h0-1}

Use the latest coding plugin with Node.js 22+. It connects directly to Cloud MCP; no Mac app, DMG, Agent Access switch or local socket is needed.

### Prerequisites {#h0-3}

Use your own Thegram account, the intended Cloud vault and an existing project document. Install only the selected host’s block above. Remove an old manually registered `thegram` server only as the canonical guide directs; preserve unrelated plugins and servers.

### 2. Issue a key and connect privately {#h0-15}

1. Open [Thegram](https://vault.thegram.one/) and **Settings → Agents → API keys**.
2. Name the key, choose only the required vaults and permissions, and review its expiry. Drive requires a separate connection and grant.
3. Copy the one-time secret. Never paste it into a chat, repository, command argument or shell history.
4. Ask your agent to locate the installed plugin. In your own terminal, replace `<installed-plugin>` with that path and run:

```sh
node <installed-plugin>/dist/thegram-memory.mjs connect
node <installed-plugin>/dist/thegram-memory.mjs doctor
```

Enter the key at the hidden prompt. The connection is saved privately (POSIX directory `0700`, credential file `0600`) and bound to its endpoint. `connect` does not choose or save a document destination.

**Expected:** `doctor` reports the Cloud endpoint and the exact existing repository project document. A nonzero exit is a connection, permission or association problem, not a reason to fall back to a different vault or desktop app.

### 3. Resolve your existing project {#h0-19}

Start a new agent session after installation. The adapter searches currently authorized Vault documents for an existing project record with the exact `repo:<host>/<repository-path>` tag. Worktrees sharing an origin use the same identity. Fixed paths, selected-vault defaults and `projects.json` do not choose a destination.

If your **existing document** lacks this association, review its exact path and authorize this one-time change before running:

```sh
node <installed-plugin>/dist/thegram-memory.mjs bind --document @mounts/<vault-id>/<document>.gram [--project <id>]
```

`bind` requires write access to that existing document. Use `--project` when the document contains multiple project records. For an explicitly known non-Git identity, the published CLI also accepts `--repository <host>/<repository-path>`; do not invent one. Restart the host session after binding.

Missing or duplicate associations stop memory use; they do not create a replacement. If no project exists, agree on its purpose and destination before separately creating one. Do not create it as a connection test.

### 4. Verify without writing {#h0-22}

```text
What does Thegram remember about this project? Read the existing project overview and cite its source. Do not create or change any records. Report a missing or ambiguous repository association instead of choosing another document.
```

**Expected:** the intended existing project is read, or the assistant names the exact unresolved association. Read-only keys must never initialize or modify a project.

### Troubleshooting {#h0-25}

| What you see | Next safe action |
| --- | --- |
| `E_AUTH` or HTTP 401 | Check that your key is configured, unexpired and unrevoked; reconnect privately if you issue a replacement. |
| `E_PROJECT_IDENTITY`, missing project or multiple matches | Confirm the repository origin and the exact existing project association. Never guess a path or change the destination. |
| `E_FORBIDDEN` or `AGENT_SCOPE_DENIED` | Review key scopes, membership and organization policy. A new plugin cannot widen them. |
| `E_CONNECT` or `key_service_unavailable` | Check the configured Cloud endpoint. Do not use a desktop socket as a fallback. |
| OMP upgrade fails | Use the full marketplace ID in the generated block above. A bare `thegram-memory` name is not the upgrade target. |

### Keep access under your control {#h0-27}

CLI `disconnect` removes this machine’s saved credential; revoking the key in Thegram stops future server access. Never share a key to resolve another person’s error.

For an authorized first save, review the content and exact destination first, save only that material, then read it back directly. Search may lag indexing. Continue with [permissions](/guides/permissions/) and [everyday workflows](/guides/workflows/).