Obsidian and Claude Code: a shared second brain for a team

Claude Code works with an Obsidian vault because a vault is a folder of Markdown files: open Claude Code in it, add a CLAUDE.md with the rules, and keep it in Git. That is a second brain for one person. A team needs the vault on a server all of them reach. Folio does that, and each person connects their own Claude Code to it over MCP.

This guide goes in that order, and says where each step stops working for more than one person. It fits you if you already keep notes in Obsidian, use Claude Code, and want colleagues to get the same answers from the same notes. For the other ways to reach a vault from an agent, with a table, see Obsidian MCP: ways to give an AI agent your vault. For the Git and browser side, see Make Obsidian multiplayer with Folio.

1. Open Claude Code in the vault

No plugin and no server is needed for the first step. Go to the vault folder and start Claude Code there.

cd ~/vaults/team-notes
claude
> Summarise the notes tagged #decision from this month, with links to each one.

Claude Code searches and reads the files itself. It works with Obsidian closed, which is the difference from the plugin-based routes in the comparison post. Plugins that add an AI panel inside Obsidian are a different thing: they run in the app of the person who installed them, so the answer stays with that person too.

2. Write the rules of the vault in CLAUDE.md

Each Claude Code session starts with a fresh context. Anthropic's memory docs describe two things that carry knowledge across sessions: CLAUDE.md files that you write, and auto memory that Claude writes itself. For a vault, the CLAUDE.md is where the structure lives. Keep it short and specific, and treat it as guidance, not as a lock: the docs say Claude treats these files as context, not enforced configuration.

# Team notes vault

- Meeting notes: `Meetings/YYYY-MM-DD title.md`, with `attendees` and `tags` in the front matter.
- Decisions: `Decisions/`, one note each, tag `#decision`, link to the meeting where it was made.
- Use Markdown links, not wikilinks, for new links.
- Never delete or rename a note. Propose it and wait.
- Say which notes an answer came from.

3. Keep the vault in Git

An agent that can edit notes needs an undo. Git gives it: after a session, git diff shows exactly what Claude Code changed, and git restore takes it back. The multiplayer guide has the .gitignore that keeps Obsidian's workspace files out of the repository and the steps to push it to a private repository. You need that repository anyway for the next step.

4. Move the vault to a server your team shares

Here a personal second brain meets its limit. The vault is on one disk, so only one person has the agent's view of it. Colleagues who do not use Obsidian or Claude Code cannot ask it anything, and each person who copies the folder gets a copy that drifts.

Folio (foliowiki) is an open-source (MIT), self-hosted team wiki that keeps pages as Markdown files in Git. In Folio choose New space, From a git repository, and give the address and branch. When the repository holds an .obsidian folder, Folio detects the vault and connects it without adding an id to any note. Colleagues read and edit in a browser with roles and rights per page. You keep Obsidian: Folio fetches from the remote about every three minutes, and a browser edit becomes a commit after about 90 seconds of quiet. Folio vs. Obsidian compares the two for teams.

5. Connect each person's Claude Code to Folio

Each person creates a token under the user menu, API tokens. Choose the read scope first. Then one command adds Folio to Claude Code.

claude mcp add --transport http folio https://your-folio.example.com/mcp \
  --header "Authorization: Bearer folio_pat_..."
claude mcp list

For a team repository, put the connection in a .mcp.json file and keep the token in an environment variable, so it never reaches Git. Connect Claude Code to Folio has that file, the OAuth route and a plugin with a ready skill. Claude Code's own page on MCP servers covers scopes and approvals.

A token never has more rights than its owner. A page that person cannot open does not appear in the agent's search, and the read scope cannot write. So a shared second brain does not mean a shared password: every colleague's agent sees what that colleague sees.

6. Ask the questions a second brain is for

A folder gives an agent text. A wiki that indexes a vault also gives it structure, and the MCP tools expose it: search across the space, backlinks with the line each link sits on, a page's outline and properties, the link graph, unresolved links, orphan pages and the rows of an Obsidian base. Try prompts like these.

Search the Research space for our pricing decisions, read the three most relevant pages and answer with links.

Which pages in the Research space does nothing link to?

List the links in the Research space that point at pages that do not exist, grouped by the page they sit on.

Run the Open tasks base and group the rows by owner.

With a write token the same agent can create or update a page, and the change arrives as an ordinary Git commit that your colleague in Obsidian pulls. Bases are covered in Obsidian Bases outside Obsidian. If you would rather not use an outside agent, Folio AI, the assistant in the side panel, uses the same tools: Ask is read only, Agent can write, and it runs on a Cursor key that you set.

7. Where it stops

• Obsidian plugins do not run. Dataview and query blocks are shown as code, and community plugins and their CSS do not exist in the browser.
• Obsidian markup is read, never written. Folio does not turn your links into wikilinks, and a page created through MCP is plain Markdown.
• MCP does not manage rights. Roles, page access and creating or deleting a space are done in the interface, so an agent cannot widen its own access.
• Edits are not instant in Git. A commit comes after about 90 seconds of quiet. Pull before you start a long Claude Code session in a local copy.
• You run the server. Folio needs PostgreSQL and Redis. If you are the only person, the first three steps are enough.
• Agents make mistakes. Keep the vault in Git, start with a read token and review what an agent writes.

The complete list is in LIMITATIONS. Make a copy of your vault, connect it as a space, add Folio to Claude Code and ask the questions above. The public demo shows the screens, and the install guide has ten ways to run your own.

All guides