Setup guide — Vibe Mind

★

One-line setup (recommended)

Send this line to your agent (Claude Code, Cursor…). It reads the setup guide, adds the MCP server, asks whether you want browser authorization or an access token, then writes the working habits and installs the skill.

Send to your agent

Set up Vibe Mind by following https://vibe-mind.iguos.com/install.md?lang=en

Or configure it yourself with the steps below.

1

Sign up and verify your email

Open Vibe Mind, sign up with your email, then click the link in the verification email. You can also skip this: when you connect, the browser opens the authorization page and you can sign up right there.

Open Vibe Mind

2

Choose how to authenticate

For agents that support MCP OAuth (Claude Code, Cursor…), browser authorization is recommended: when the agent connects, the Vibe Mind authorization page opens; sign in, choose which projects it can access and click Allow. No token to copy, and it refreshes itself every hour. For agents without OAuth support, create an access token on the AI access page in the sidebar:

Limit which projects the token can access and set an expiry
The full token is shown only once, when it is created — keep it safe
Create a separate token for each machine or agent so each can be revoked on its own

3

Add the MCP configuration to your agent

The Manual tab on the AI access page gives the configuration for each agent; here are examples. The recommended OAuth setup needs no token; with an access token, replace vm_xxxxxxxxxxxxxxxx with yours.

Claude Code

Recommended: run these two commands. The second opens the authorization page in your browser; sign in and click Allow (or type /mcp in Claude Code and pick vibe-mind → Authenticate):

Terminal

claude mcp add --transport http --scope user vibe-mind https://vibe-mind.iguos.com/mcp
claude mcp login vibe-mind

Or use an access token:

Terminal

claude mcp add --transport http --scope user vibe-mind https://vibe-mind.iguos.com/mcp \
  --header "Authorization: Bearer vm_xxxxxxxxxxxxxxxx"

Or put it in .mcp.json at the project root to share the config with your team (each person sets the token in the VIBE_MIND_TOKEN environment variable):

.mcp.json

{
  "mcpServers": {
    "vibe-mind": {
      "type": "http",
      "url": "https://vibe-mind.iguos.com/mcp",
      "headers": {
        "Authorization": "Bearer ${VIBE_MIND_TOKEN}"
      }
    }
  }
}

Codex

Recommended: add this to ~/.codex/config.toml, then run codex mcp login vibe-mind in a terminal, sign in and click "Allow" in the browser:

~/.codex/config.toml

[mcp_servers.vibe-mind]
url = "https://vibe-mind.iguos.com/mcp"

Or use an access token: add bearer_token_env_var to the same section and set the VIBE_MIND_TOKEN environment variable to your token in your shell profile (Codex only reads tokens from environment variables):

~/.codex/config.toml

[mcp_servers.vibe-mind]
url = "https://vibe-mind.iguos.com/mcp"
bearer_token_env_var = "VIBE_MIND_TOKEN"

Gemini CLI

Recommended: put just the URL under mcpServers in ~/.gemini/settings.json (merge with what's there), then type /mcp auth vibe-mind in Gemini CLI, sign in and click "Allow" in the browser:

~/.gemini/settings.json

{
  "mcpServers": {
    "vibe-mind": {
      "httpUrl": "https://vibe-mind.iguos.com/mcp"
    }
  }
}

Or use an access token:

~/.gemini/settings.json

{
  "mcpServers": {
    "vibe-mind": {
      "httpUrl": "https://vibe-mind.iguos.com/mcp",
      "headers": {
        "Authorization": "Bearer vm_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor

Recommended: put just the URL in Cursor's MCP config (global ~/.cursor/mcp.json or the project's .cursor/mcp.json), then sign in from Cursor's MCP settings and click Allow in the browser:

mcp.json

{
  "mcpServers": {
    "vibe-mind": {
      "url": "https://vibe-mind.iguos.com/mcp"
    }
  }
}

Or use an access token:

mcp.json

{
  "mcpServers": {
    "vibe-mind": {
      "url": "https://vibe-mind.iguos.com/mcp",
      "headers": {
        "Authorization": "Bearer vm_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Generic agent

Any agent that supports remote MCP (Streamable HTTP) can connect: if it supports OAuth, just enter the server URL and authorize in the browser when asked; otherwise send Authorization: Bearer <your access token> in the request header. The server URL is https://vibe-mind.iguos.com/mcp

4

Check the connection

Start a new agent conversation (ones already open can't see the Vibe Mind you just connected), then ask it to call project_list. If it returns your project list (a new account has at least the default project @knowhow — your know-how), you're connected — the AI access page also shows when the authorization or token was last used. Your Brain is off by default: to have agents work your way, turn it on on the Brain page in the console, and @brain joins the list.

5

Install the hooks so every session goes through Vibe Mind

Habits alone get forgotten. The hooks make Vibe Mind the source of truth every time (Claude Code, Codex, Gemini CLI and Cursor are supported):

At session start, the current project's memory and the rules go into context, so the agent doesn't have to read them itself; when you send your first message, the memories relevant to it are added (looked up once per session)
At the end, if code changed, a commit was made, or you corrected something or set a rule, and none of it was written to Vibe Mind, the agent is stopped once to record it; if a session is closed or compacted midway, it catches up at the next start (plain chat isn't affected)
The agent's built-in local memory stays as a fallback; if they disagree, Vibe Mind wins

Claude Code: download the hook script, then merge the block below into ~/.claude/settings.json. The hook token goes in ~/.vibe-mind/hook-token: with OAuth, have the agent call the MCP tool hook_token; with an access token, use the same token.

Terminal

mkdir -p ~/.vibe-mind && curl -fsSL https://vibe-mind.iguos.com/hooks/vibe-mind-hook.sh \
  -o ~/.vibe-mind/hook.sh && chmod +x ~/.vibe-mind/hook.sh

~/.claude/settings.json

{
  "hooks": {
    "SessionStart": [{ "matcher": "startup|clear|compact",
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh claude start en" }] }],
    "UserPromptSubmit": [{
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh claude prompt en" }] }],
    "Stop": [{
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh claude stop en" }] }],
    "SessionEnd": [{
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh claude end en" }] }],
    "PreCompact": [{
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh claude end en" }] }]
  }
}

Codex: same script; merge this into ~/.codex/hooks.json, then type /hooks in Codex and trust these hooks (untrusted hooks don't run).

~/.codex/hooks.json

{
  "hooks": {
    "SessionStart": [{ "matcher": "startup|resume|clear|compact",
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh codex start en" }] }],
    "UserPromptSubmit": [{
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh codex prompt en" }] }],
    "Stop": [{
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh codex stop en" }] }],
    "SessionEnd": [{
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh codex end en" }] }],
    "PreCompact": [{
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh codex end en" }] }]
  }
}

Gemini CLI: same script; merge this into ~/.gemini/settings.json.

~/.gemini/settings.json

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh gemini start en" }] }],
    "BeforeAgent": [{
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh gemini prompt en" }] }],
    "AfterAgent": [{
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh gemini stop en" }] }],
    "SessionEnd": [{
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh gemini end en" }] }],
    "PreCompress": [{
      "hooks": [{ "type": "command", "command": "bash ~/.vibe-mind/hook.sh gemini end en" }] }]
  }
}

Cursor: same script; merge this into ~/.cursor/hooks.json. Cursor's prompt hook can't add context, so there's no first-message event; the rules loaded at session start have the agent look things up after your first message.

~/.cursor/hooks.json

{
  "version": 1,
  "hooks": {
    "sessionStart": [{ "command": "bash ~/.vibe-mind/hook.sh cursor start en" }],
    "stop": [{ "command": "bash ~/.vibe-mind/hook.sh cursor stop en" }],
    "sessionEnd": [{ "command": "bash ~/.vibe-mind/hook.sh cursor end en" }],
    "preCompact": [{ "command": "bash ~/.vibe-mind/hook.sh cursor end en" }]
  }
}

One-line setup installs all of this. Full instructions (including project-level / cloud setup) in install.md

6

Make the most of Vibe Mind's memory

Once connected, these habits help your agent record and reuse knowledge well:

Before starting, have the agent call memory_context with what it is about to do, to get the project overview and the relevant memories in one go
After a decision or a fix, have the agent record the context, conclusion and reasons under the right module
Review regularly in the console and save confirmed versions as snapshots
Have your agent put summaries, progress and open questions for you into work notes

Put these habits in your agent's global instructions (Claude Code: ~/.claude/CLAUDE.md, Codex: ~/.codex/AGENTS.md, Gemini CLI: ~/.gemini/GEMINI.md) and it follows them every session. You can use the block below as is; keep the first and last marker lines — when a new version comes out, the agent replaces only what's between them.

~/.claude/CLAUDE.md · ~/.codex/AGENTS.md · ~/.gemini/GEMINI.md

<!-- VIBE_MIND_START -->
## Vibe Mind: brain, hands and work notes (different purposes, don't mix them up)
- Rule of thumb: will a future agent need to read this before starting work? Yes → memory (memory_write). Only for people to read → work notes (worknote_write).
- Where memory goes: true only for this project (anyone taking it over must follow it) → the current project, named after the repo, path "module/category/title", category one of conventions / decisions / pitfalls / runbooks / external / architecture / todo; about the user and true across projects → one of the 5 fixed files in project=@brain (the user may call it "Brain" or "灵犀") (boundaries / soul / goals / workstyle / profile), only what the user stated or corrected, with the evidence for each point, edited with append / replace_text; skills useful in other projects too → project=@knowhow.
- When the user corrects you or sets a rule, decide where it goes by scope, not by the fact that the user said it: true only in this project (how branches are cut, how releases go, who runs SQL, this product's feature choices) → the project's conventions; personal habits true in any project (reply language, commit attribution, taste, how to communicate) → @brain; when unsure, put it in the project. E.g. "cut bugfix branches from next" is a project convention, not the Brain.
- Starting work: call project_list, then memory_context with what you're about to do to get the Brain, relevant know-how, the project overview and memories in one call; work the way the Brain says, boundaries first, and weigh things by the soul when unsure. For a new project, first add three pages: README (what it is), project/runbooks/setup (how to set up a new computer; for keys, only where they live), project/todo/next-steps (progress and next steps). After a decision or a fix, write it down, reusing existing project and module names; before you finish, update progress and next steps under todo. Code is the truth for how things are now; memory is the truth for why and what's next; fix memory on the spot when they disagree.
- Tidying up: when the user says "tidy up", or the session-start context suggests it, call memory_tidy for the checklist, then merge duplicates, refile misplaced entries, fix stale ones and move general know-how into @knowhow; write a "tidy-up log" work note, then call memory_tidy again with done=true. Finish the task at hand first.
- Work notes: written for people, not read at session start — summaries, progress updates, investigations, option comparisons, questions that need a human decision. Write them with worknote_write by "project + title" (writing the same title again updates it; append adds progress), then share the returned link with the user. Notes you wrote can be viewed with worknote_list / worknote_read and deleted with worknote_delete (to the trash); notes written (or taken over) by the user are read-only for you.
- Don't put summaries or reports for people into memory; don't keep experience future agents need only in work notes (they aren't read at session start).
- Vibe Mind is the source of truth: experience always goes to Mind; your built-in local memory is only a fallback (note it locally when Mind is unreachable and write it to Mind once it's back); if they disagree, Mind wins.
- If a Vibe Mind tool the user asks for isn't in your tool list, this MCP connection was made before that tool shipped: ask the user to reconnect the Vibe Mind MCP server or start a new session; don't work around it another way.
- Version of these notes: vibe-mind-habits-v6. When the session-start context says there's a newer version, replace the part between VIBE_MIND_START and VIBE_MIND_END as instructed, without asking the user.
<!-- VIBE_MIND_END -->

You can also install the Vibe Mind skill: Claude Code reads it from ~/.claude/skills/vibe-mind/; Codex, Gemini CLI and Cursor from ~/.agents/skills/vibe-mind/. SKILL.md

Terminal

# Claude Code
mkdir -p ~/.claude/skills/vibe-mind && curl -fsSL https://vibe-mind.iguos.com/skills/vibe-mind/SKILL.md \
  -o ~/.claude/skills/vibe-mind/SKILL.md
# Codex, Gemini CLI, Cursor
mkdir -p ~/.agents/skills/vibe-mind && curl -fsSL https://vibe-mind.iguos.com/skills/vibe-mind/SKILL.md \
  -o ~/.agents/skills/vibe-mind/SKILL.md

Connect Vibe Mind to your agent

One-line setup (recommended)

Sign up and verify your email

Choose how to authenticate

Add the MCP configuration to your agent

Claude Code

Codex

Gemini CLI

Cursor

Generic agent

Check the connection

Install the hooks so every session goes through Vibe Mind

Make the most of Vibe Mind's memory