--- title: "Obsidian + Claude Code: How I Run My Company from a Vault" description: "I run my company from an Obsidian vault with Claude Code and 7 AI agents that debate with each other. Structure, MOCs, board meetings and the real cost." pubDate: "2026-04-08" category: "estrategia" language: "en" tags: ["obsidian", "claude-code", "productivity", "management", "ai", "agents", "markdown", "knowledge-management"] --- ## Plain Markdown as a business management system I have spent months running my company from a directory of Markdown files. No Notion, no Google Docs, no project management tools with pretty dashboards. An Obsidian vault connected to Claude Code with specialised agents that debate each other and help me make decisions. This is not a theoretical idea. I use it every day. The board meetings for my projects are run by a round table of AI agents. My knowledge notes create and link themselves. Each project's status updates itself after every meeting. And the total cost of this infrastructure is a Claude Max subscription ($100/month) plus a server I already had. If you are interested in building something like this, here is exactly how mine is set up. ## Why Obsidian and not something else The decision was simple. I needed something that met three conditions: 1. **Plain Markdown**: `.md` files any tool can read 2. **Local-first**: the data lives on my machine, not on a third-party server 3. **Compatible with Claude Code**: the agent can read and write without intermediate APIs Notion fails all three. You need its API to access the data, the format is proprietary, and you depend on their servers. Google Docs, the same. Any SaaS tool locks you into its ecosystem. Obsidian is a Markdown editor with superpowers (graph view, wiki-links, plugins), but what makes it perfect for this case is that **underneath there is only a folder of `.md` files**. Claude Code opens that folder and has access to everything. No configuration, no API tokens, no adapters. | Criterion | Obsidian | Notion | Google Docs | |----------|----------|--------|-------------| | Format | Plain Markdown | Proprietary | Proprietary | | Local access | ✅ File folder | ❌ API required | ❌ API required | | Native Claude Code | ✅ Reads/writes directly | ❌ Needs MCP | ❌ Needs MCP | | Portability | ✅ Copy the folder | ⚠️ Markdown export (loses advanced formatting) | ❌ Limited export | | Cost | Free | $10/month (Plus) | Free (with Google) | | Offline | ✅ | ❌ | ❌ | | Databases / Kanban | ❌ Needs plugins | ✅ Native | ❌ | | Team collaboration | ⚠️ Git or Sync | ✅ Native | ✅ Native | To be fair: if you need relational databases, kanban views, or native team collaboration, Notion is still more capable. Obsidian's trade-off is losing those functions in exchange for simplicity and direct agent access. There are people using MCP servers to connect Notion to Claude Code, and it works. But it is an intermediate layer that does not pay off in my case. If your data is already in Markdown, the agent reads it directly. Less complexity, fewer failure points. ## The vault structure My vault is called `brain-dump` and has this structure: ``` brain-dump/ ├── diario/ # Daily entries: diario/YYYY/MM/DD.md ├── personas/ │ └── trabajo/ # Colleagues and professional contacts ├── trabajo/ │ └── empresa/ │ ├── _sobre.md # Company profile │ ├── proyecto/ │ │ ├── _sobre.md │ │ └── {scope}.md │ └── clientes/ │ └── nombre-cliente/ ├── conocimiento/ │ ├── moc/ # Maps of Content (narrative indexes) │ └── notas/ # 117 knowledge notes ├── reuniones/ # Board meeting minutes └── CLAUDE.md # Rules for Claude Code ``` Every folder has a clear purpose. There are no loose files at the root (except the README and CLAUDE.md). There are no infinite subfolders. The organisation is flat and predictable. What connects everything are **Obsidian wiki-links**: `[[personas/trabajo/nombre-apellido]]`, `[[trabajo/acme/estado-actual]]`, `[[diario/2026/04/08]]`. Any file can link to any other. And Claude Code understands these links and follows them when it needs context. ### The CLAUDE.md file: the rules of the game This is key. At the root of the vault there is a `CLAUDE.md` with all the conventions: how to name files, what frontmatter to use, how to link people, how to structure knowledge notes. When Claude Code opens the directory, it reads these rules and respects them. It is the same idea I explained in my Claude Code guide: the rules in `CLAUDE.md` are the contract between you and the agent. Without clear rules, the agent improvises. With clear rules, the agent is consistent. ## How Claude Code interacts with the vault I open Claude Code in the `brain-dump/` directory and I have access to several capabilities configured as skills and agents. ### Board meetings: the leadership table This is the most powerful piece. I have a `/reunion` skill that starts a round table with 7 specialised agents: | Agent | Role | Model | |--------|-----|--------| | CEO | Moderator, synthesises the debate | Opus | | Strategy | Business decisions, priorities | Sonnet | | Marketing | Positioning, campaigns, audience | Sonnet | | SEO | Keywords, organic traffic | Sonnet | | YouTube | Channel, content, trends | Sonnet | | UX/UI | Interface, accessibility | Sonnet | | Finance | Costs, revenue, ROI | Sonnet | | Product | Roadmap, MVP, prioritisation | Sonnet | The flow works like this: 1. The CEO reads the current status of all my projects (each company's `estado-actual.md`) and the latest meeting minutes 2. It presents me with a summary and asks what I want to discuss 3. It spawns the agents relevant to the topic using [Agent Teams](/en/claude-code-agent-teams/) 4. The agents **debate each other** — they do not just report to the CEO; they challenge each other, request data from other departments, and build on each other's opinions 5. The CEO synthesises the debate and hands the floor back to me 6. I iterate until I want to close When I close the meeting, the CEO generates the minutes in `reuniones/YYYY-MM-DD.md` with the topics covered, each agent's position, the decisions taken and the pending actions. It also updates the `estado-actual.md` files of the affected projects. A real example from the last meeting: we discussed a side project with all 7 agents. Strategy said it did not fit the main portfolio (a different niche from the core). Finance calculated the break-even and recommended raising the price. Marketing proposed more emotional headlines. SEO detected that the site was not indexed in Google. Product suggested simplifying the landing page by removing a tier with no implemented UI. All that in one session. With real data from the vault files, not invented. And it was documented in the minutes without me writing a single line. ### The fundamental principle: conversation, not pipeline One thing I learned while iterating is that **the meeting works as a conversation, not as a pipeline**. It is not "strategy first, then marketing, then finance" in sequence. The agents talk to each other, challenge each other, and sometimes Finance contradicts Marketing directly. In that same meeting, what I did not expect was SEO replying to Marketing that the copy did not matter if Google could not even index the SPA. Or UX confirming that the templates worked well but the headline's promise was unrealistic. Those cross-department clashes are not something I would have raised on my own. That produces far richer debates than asking a single agent to analyse everything. The CEO moderates but does not decide — the decision is always mine. It is like having a board of directors that works for you, but is not afraid to disagree. If you already know Agent Teams, this is the same idea applied to management instead of development. The difference is that in development the agents write code, and in management the agents debate and generate documentation. ### Knowledge management I have 117 notes in `conocimiento/notas/` about everything I consider relevant: from Claude Code to mutation testing, from MCP servers to personal branding strategies. Each note is a plain Markdown file with YAML frontmatter and structured content. The key to the organisation is not the folders (the notes are flat, with no subfolders). The organisation comes from the **Maps of Content (MOCs)**. ## Maps of Content: the organisation layer MOCs are the idea that has changed how I manage knowledge the most. A MOC is not a list of links. It is a **narrative text that weaves wiki-links into the prose**. I have 12 MOCs covering development, AI, infrastructure, productivity, marketing, real estate, management, life, and several sub-MOCs for topics that grew too large (version control, MCP integrations, testing, multi-agent systems). A real fragment from my AI MOC: ```markdown On the practical side, [[conocimiento/notas/claude-code|Claude Code]] is the central tool of the AI development flow. Its [[conocimiento/notas/claude-code-extensiones|extensions and skills]] make it possible to expand capabilities without writing code manually. The ecosystem is complemented by [[conocimiento/notas/rtk|RTK]] as a CLI proxy to reduce tokens and a constantly growing [[conocimiento/notas/herramientas-desarrollo-ia|index of AI development tools]]. ``` Notice: it is not a bullet list with links. It is prose that connects ideas naturally. The wiki-links are integrated into the text as part of the explanation. When you read the MOC, you understand the relationships between concepts. When you click a link, you go deeper. ### Why narrative and not bullet points I tried it both ways. With bullet points, the MOC becomes a dead index you never revisit. With narrative prose, the MOC tells a story you can read from start to finish and that gives you context on how the pieces relate. Also, when Claude Code needs to understand a topic, the narrative format gives it far more context than a flat list of links. It reads the MOC and understands not only which notes exist, but how they relate to each other. When I create a new note, I add it to the corresponding MOC by weaving it into the text. If a note is cross-cutting (for example, something about Claude Code that applies to both development and AI), it appears in several MOCs. What organises the notes is the MOCs and the links, not the folder structure. ## Wiki-links: the connective tissue Obsidian's wiki-links (`[[path/to/file]]`) are what turn a folder of files into a knowledge graph. In my vault, everything is connected: - Diary entries link to people: `[[personas/trabajo/nombre]]` - People link to diary entries: `[[diario/2026/04/08]]` - Projects link to team members: `[[personas/trabajo/nombre]]` - Meetings link to projects: `[[trabajo/acme/estado-actual]]` - MOCs link to notes: `[[conocimiento/notas/claude-code]]` - Notes link to other notes Claude Code follows these links. If I ask it about a project's status, it reads its `estado-actual.md`, sees that it mentions another company, and can follow the link to that company's `_sobre.md` to understand the relationship. Context is built by navigating the graph. This is something Notion cannot replicate. In Notion, relationships are database properties. In Obsidian, relationships are text inside files that an AI agent can read and understand without needing a schema. ## The current status of each project Every company and project has an `estado-actual.md` file with a fixed structure: ```markdown --- proyecto: Acme Corp ultima-actualizacion: 2026-04-07 tags: [estado, acme] --- # Current Status — Acme Corp ## Summary Own company with three products: Product A (active growth), Product B (autopilot), Product C (in validation, 30-day kill criteria). ## Key metrics | Metric | Value | Trend | |---------|-------|-----------| | Product A — MRR | €850 | ↑ | | Product A — Impressions/week | 340 | ↑ | | Product B — Price | €49 one-off | → | | Product C | Kill criteria 30 Apr | ↓ | ## Recent decisions ## Next steps ## Blockers/Risks ``` These files are updated after every board meeting. And they are the first thing the CEO reads when the next meeting starts. It is a cycle: meeting → minutes → status update → next meeting reads the updated status. Without this cycle, every meeting would start from zero. With it, there is continuity. The agents remember previous decisions because they are written in files they read at the start. ## I am not the only one doing this On Twitter I see more and more people combining Obsidian with AI agents. The pattern repeats: someone realises that paying for 5 different SaaS products is absurd when an agent with access to a Markdown folder can do the same. And they start building their own system. What varies is the complexity. Some have a single agent that reads notes and generates summaries. Others build 8 autonomous agents with differentiated roles (organisation, writing, taxonomy, distribution). My setup with 7 agents debating around a table sits somewhere in the middle. The underlying idea is always the same: **Markdown files as the interface between humans and AI**. No intermediate APIs, no proprietary formats. Plain text that both you and the agent can read and write. ## The real cost and what it replaces Let us get to the numbers: | Item | Cost | What it replaces | |----------|-------|----------------| | Claude Max subscription | $100/month | Consulting, second brain, assistants | | Obsidian | $0 | Notion ($10/month), management tools | | Local server | Already had it | — | | **Total** | **$100/month** | — | What does it replace in practice? - **Project management tools**: `estado-actual.md` plus board meetings covers what Jira or Linear would do for a solopreneur or small team - **Notion/Coda as a knowledge base**: the notes plus MOCs do the same with better portability - **Informal strategic consulting**: having 7 agents debating your business does not replace a real consultant, but it forces you to articulate your decisions and gives you perspectives you would not have considered alone - **A meeting-minutes assistant**: the minutes generate themselves with a consistent format It does not replace everything. You still need real accounting, a real CRM if you have many clients, and collaborative tools if you work with a large team. This works well for solopreneurs and small teams where one person makes the decisions. ## Honest trade-offs Not everything is perfect. These are the real problems I have run into: ### What works well - **Access speed**: Claude Code reads the vault instantly, with no API latency - **Consistency**: the CLAUDE.md rules guarantee everything follows the same format - **Continuity**: the meeting → minutes → status → next meeting cycle preserves context between sessions - **Flexibility**: adding a new project means creating a folder and an `_sobre.md` ### What does not work so well - **Entry curve**: building all this takes time. My vault's CLAUDE.md has hundreds of lines of conventions. It is not "install and go" - **Model dependency**: the quality of the meetings depends heavily on the model. With Opus the debates are rich. With cheaper models, the agents state the obvious - **No native collaboration**: Obsidian is personal. If you need 5 people editing the vault, you need Git or Obsidian Sync, and both have limitations - **MOC maintenance**: narrative MOCs are better than lists, but they are also harder to maintain. Every new note requires editing prose, not adding a bullet ### What I am still iterating on - Inbox processing from Gmail with automatic triage - Automatic creation of knowledge notes from curated content - Better integration between the vault and each project's code repositories ## The diary as an operational log One piece I have not mentioned, and which has given me more than I expected: the diary. Every day has an entry in `diario/YYYY/MM/DD.md` with frontmatter (`date`, `tags`) and a summary of what mattered that day. It is not a personal "dear diary". It is an **operational log**. What I decided, what problems I hit, what I changed course on, who I spoke to. All linked with wiki-links to people, projects and meetings. When Claude Code needs temporal context — "what happened last week with Product A?" — it reads the diary entries and reconstructs the chronology. It is the system's short-term memory. The `estado-actual.md` files are the still photo; the diary is the film. It also works as an accountability system. When I review the week's diary, I see whether I moved on what I said I would move on. And Claude Code can do that review for me: "compare the pending actions from Monday's meeting with this week's diary entries". ## How to start, if you are interested Do not build it all at once. The path I recommend: **Week 1**: create an Obsidian vault with a basic structure. `diario/`, `trabajo/`, `conocimiento/notas/`. Write a `CLAUDE.md` with 10 basic formatting rules. Open Claude Code in that directory and use it to create notes and diary entries. **Week 2**: add the `estado-actual.md` files for your projects. Start linking things with wiki-links. Create your first MOC as narrative text connecting 5-10 notes. **Week 3**: experiment with specialised agents. You do not need 7 from the start. A "status review" agent that reads your `estado-actual.md` files and asks you questions already adds value. **Week 4+**: try setting up a meeting with 2-3 agents debating. Iterate from there. The key is that **the vault structure matters more than the agents**. If your files are well organised, with **consistent frontmatter** and wiki-links, any agent can do useful things. If your files are chaos, not even the best agent in the world will make sense of them. This connects with what I explained in the [SDD article](/en/spec-driven-development-openspec/): specify before executing. The vault's CLAUDE.md is the system's specification. The agents are the executors. Without a spec, chaos. ## An Obsidian vault as an operational second brain My system is an Obsidian vault with 117 knowledge notes, 12 Maps of Content, meeting minutes with 7 agents debating, project statuses that update themselves, and a diary that links everything with wiki-links. It runs in Claude Code with no intermediate APIs, no MCP servers to access the data, no databases. It is Markdown. Folders. Text files. Connected by wiki-links and processed by AI agents that follow rules written in more Markdown. It is not the solution for everyone. If you work in a team of 20, you need collaborative tools. If you do not use Claude Code, you will need some MCP server to connect your vault to your AI agent. But if you are a solopreneur or have a small team and already use Claude Code, a well-structured Obsidian vault is the most direct way to give it full context about your business. In the end, the most powerful tool for working with AI is not a SaaS with a pretty dashboard. It is a well-organised folder of `.md` files. --- **P.S.**: If you build something similar, tell me on Twitter at [@lm_martinbar](https://x.com/lm_martinbar). I am curious to see how others structure their vaults and which agents work best for them.