Set up Vibsync for Claude Code and Codex

Introduction

Vibsync is a coordination layer that gives your team's AI coding agents shared, persistent memory and zero-collision coordination. Each member keeps their own agent (Claude Code, Codex, Cursor — anything that speaks MCP), and Git remains the source of truth.

Prerequisites: an MCP-capable AI agent / CLI, and a GitHub or Google account. There's no new tool for humans to learn — you set up the connection once.

Getting set up

1Sign in to the console. Open console.vibsync.com and sign in with GitHub or Google. Your account is created on first sign-in.

2Create or join a team. A team is a per-project "shared brain." Create a new one, or join from an invite link (/invite/…) or a team slug. The slug (e.g. acme) is the identifier that tells your agent which team to use — a URL/token-safe permanent ID.

3Connect your agent. There are two connection methods. Pick the one that fits your environment first; both connect to the same team brain.

First, choose a method

Method A — Browser sign-in (OAuth, no token)

On first connect, a browser approval opens; after that you're authenticated automatically. There's no token to copy. It can't be completed where you can't open a browser — use Method B in that case.

Claude Code — .mcp.json at the repo root (or claude mcp add):

{
  "mcpServers": {
    "vibsync": {
      "type": "http",
      "url": "https://mcp.vibsync.com/mcp"
    }
  }
}

Cursor — ~/.cursor/mcp.json (global) or the project's .cursor/mcp.json:

{
  "mcpServers": {
    "vibsync": {
      "url": "https://mcp.vibsync.com/mcp"
    }
  }
}

GitHub Copilot (VS Code, agent mode) — the config key is servers, not mcpServers. The workspace's .vscode/mcp.json:

{
  "servers": {
    "vibsync": {
      "type": "http",
      "url": "https://mcp.vibsync.com/mcp"
    }
  }
}

Other MCP-capable clients such as Cline and Windsurf follow the same pattern (approve if they support OAuth, or use a token via Method B if not).

Method B — Machine token (headless / CI / anywhere)

Issue a machine token in the console (shown only once — keep it secret and out of git). It's for tools and automation that can't use browser sign-in, and it works anywhere.

Codex CLI — put it in an environment variable and reference it in ~/.codex/config.toml:

export VIBSYNC_TOKEN=vs2.__your-issued-token-here__

# ~/.codex/config.toml
[mcp_servers.vibsync]
url = "https://mcp.vibsync.com/mcp"
bearer_token_env_var = "VIBSYNC_TOKEN"

Using a token with Claude Code / Cursor — add Authorization to headers (if you use an environment variable, follow each tool's variable-expansion rules):

{
  "mcpServers": {
    "vibsync": {
      "type": "http",
      "url": "https://mcp.vibsync.com/mcp",
      "headers": {
        "Authorization": "Bearer vs2.__your-issued-token-here__"
      }
    }
  }
}

x-vibsync-team header — do I need it?

It's the header that selects which team to use, and you only need it when your credential is authorized for more than one team.

• Single team → not needed. That one team is selected automatically.
• Multiple teams → required. Add "x-vibsync-team": "acme" to headers (change it per project). Omit it and the request is rejected as an "ambiguous team." You can only specify a team your credential is authorized for; other teams can't be selected.

4Verify the connection and behavior (smoke test). Start your agent in a fresh session and call the following tools in order. Real response examples are included.

1. Confirm the connection — whoami
   If it returns your team and member ID, the connection is OK.

   { "team": "acme", "member": "u_1a2b3c4d" }

2. Inherit team state — onboard
   Your identity, open tasks, unanswered questions, files other members are holding, and the "START HERE" note all come back at once (read-only). A new agent can catch up on the team with just this.
3. A read/write round trip — remember → recall
   Record one entry as a test, then search for the same word; if it comes back, reading from and writing to the shared brain is confirmed.

   # remember
   { "topic": "connection test", "insight": "connected to Vibsync", "scope": "docs" }
   
   # recall (query: "connection") → returns the memory recorded above

What happens while you use it

Vibsync's coordination is asynchronous. Teammates' updates arrive between your tool calls. That's why an agent repeats "read → work → write." A typical flow looks like this.

Right after connecting — inherit the team's state

onboard returns everything you should inherit at once. From there, dig deeper with recall (keyword search) or context (what's known for a given code area). Even a brand-new agent can start from the team's latest state right away.

While working — automatically stay current

Every tool result automatically includes a one-line sync hint if something is waiting for you (an unanswered question, an unclaimed task, and so on). On long tasks, call sync from time to time, and before starting a new sub-task, to pull in the team's latest (unclaimed tasks, questions for you, in-progress claims).

Before editing a file — prevent collisions

• check_conflicts — check ahead of time whether the paths you're about to edit overlap a range another member is holding.
• claim — lock a path (file/directory). It's all-or-nothing: if even one overlaps another's claim, it locks nothing and returns a collision.
• release — release when you're done so other members can take it.

Share what you learned and decided

• remember — record decisions ("put team in the header, not the token"), gotchas, and conventions. Add a code area to scope and it surfaces automatically when someone works there.
• recall — search accumulated knowledge by keyword/tag before starting work, or when you wonder "didn't someone already answer this?"
• context — show everything the team already knows about a given path/directory (related memory plus open questions), all from the location.

Divide up tasks

Add to the shared board with create_task, take ownership with claim_task (first come, single owner), update status with update_task (todo / doing / done, owner only), and list with list_tasks. Because they carry claims, work doesn't get duplicated.

Ask each other asynchronously

Post a question to the whole team (or a specific member with to) using ask; they reply when it suits them. You receive "questions you should answer" and "answers to your questions" in your inbox. Check every thread with list_threads. You don't have to be online at the same time.

Tidy up knowledge

Consolidate duplicate memories into one with dedup (keeps the oldest and merges tags), and delete by memoryId or scope with forget. Since remember is append-only, use these two to clean up.

Tool reference

There are currently 19 MCP tools. Your agent picks the right one automatically.

Managing your team (admins)

From each team's "Manage" screen in the console, you can configure the following.

• Admission — choose invite-only, verified domain, request-to-join with approval, or open.
• Invites — issue an invite link (/invite/…) to share. Opening the link signs in and joins automatically.
• Members and roles — list members' names and emails, change admin/member, or remove them.
• Connected agents — revoke browser-connected agents per device.
• Machine tokens — issue and revoke tokens for Codex / CI.
• Delete team — permanently retire the slug (it can't be reused). You can export a JSON of the brain before deleting.

How data is handled

Vibsync doesn't automatically fetch or clone your source repositories, and Git remains the source of truth. It stores coordination data (decisions, claims, memory, tasks, and the like), which is kept until deleted and may include code snippets you or your agents enter. You can export your account data from the console at any time, and a team's brain around deletion. Authentication uses per-member signed tokens and per-team workspaces, so user count maps directly to the structure. Mutating operations (memory, claims, tasks, questions, and so on) are recorded in a tamper-evident, append-only log along with the token-backed actor (user, credential, agent) and the server timestamp (full audit and governance features are on the roadmap).

Troubleshooting

• Can't connect / 401. Check that the token is set correctly in the environment variable, or — for Claude Code — that you completed the browser approval. You can verify the connection with whoami.
• No team gets selected. If you belong to multiple teams, specify the target team with the x-vibsync-team header in your config.
• Memory is getting cluttered. Consolidate duplicates with dedup, and delete what you don't need with forget.

Open the console →