Building a Better Human-Bot Collaboration Environment in Obsidian

Intro

AI promises leverage, but it still amplifies whatever mess you hand it.

This article is not really about getting AI into Obsidian. It is about what happens after that. It is about building an environment where your notes, your tools, and your AI collaborator share enough structure to do useful work together.

For me, that became real when I learned I might have one more chance to reinvent my professional self after spending 21 years with the same employer. I started documenting my career in Obsidian: projects, turning points, accomplishments, lessons, half-remembered stories, and scattered evidence of work done across two decades.

Because I had already been working with Gen AI for a while, I used that moment to test a bigger idea. Could I turn those uneven notes into working context? Could I build the kind of second brain people keep promising?

After a week of evenings typing in career notes, I asked Codex to build me a professional website from that still-incomplete vault.

The first result was good enough to be useful and rough enough to be instructive. The site told a coherent story, but it also did what AI often does when source material is thin: it filled gaps confidently and polished uncertainty into claims that sounded firmer than they should have.

That was the useful moment.

It showed me that the notes were already valuable before they were finished. It also showed me what kind of environment I would need if this was going to become genuinely trustworthy: a shared workspace where Obsidian holds the raw thinking, configuration keeps the structure legible, and the bot can help turn rough notes into usable outputs without guessing in the dark.

The Real Problem

At first, the friction looked like a tooling problem. It was not. It was a context problem.

I did not need AI to merely read markdown files. I needed a setup where:

• Obsidian could remain the place where I think, collect, and draft
• VS Code could remain the place where implementation happens
• Codex could work inside the same workspace without inventing its own map
• Git could preserve boundaries between notes, automation, and published outputs

Scattered notes do not become a second brain just because an AI can see them. They become one when there is enough structure for both a human and a machine to move through them without distorting them too badly.

Without that structure, the bot sees fragments. With that structure, the bot can start seeing relationships.

The Case Study

The career-site experiment became both the proof of concept and the warning.

I was not starting from a polished resume package. I was starting from incomplete notes written over a week of evenings. Some were detailed. Some were vague. Some were little more than prompts to myself. Still, there was enough there for an AI agent to begin assembling a narrative.

When Codex built the first version of the site, two things became obvious.

First, the setup worked. Notes written for myself could be transformed into something outward-facing, coherent, and useful.

Second, the setup was not trustworthy enough yet. The website was coherent, but it also overstated a few things and smoothed over uncertainty that should have remained visible.

That tension is exactly why structure matters.

If the vault is organized well, if paths are explicit, if the bot knows which notes are raw material and which outputs are publishable, and if the workflow has checkpoints, then AI stops being just a text generator and starts becoming a practical collaborator.

That is the real reframing. The interesting part is not that AI could generate a website from notes. The interesting part is that a structured Obsidian environment made that possible early, exposed the weaknesses immediately, and revealed what needed to improve next.

What We Changed

Once the website experiment exposed the weak spots, the priorities became clearer. We did not need a more magical prompt. We needed a better working relationship.

That led to a few concrete decisions:

• keep the vault inside a shared workspace instead of treating it like an isolated personal notebook
• define path contracts so the human and the bot agree on where vaults, apps, websites, and automation live
• require explicit targeting instead of depending on hidden application state
• separate coordination concerns from publishable products with a Git model that supports multiple repositories
• document operating rules so important lessons do not disappear into chat history

In other words, we shifted from asking, “Can the bot use Obsidian?” to asking, “What would make this collaboration trustworthy enough to reuse?”

Lessons Learned

The most useful lessons were not just technical. They were collaborative.

The first lesson is humbling: I do not automatically know what Codex needs in order to support me well. I know my goals and my history, but I do not naturally think in terms of what context an AI agent is missing, what assumptions it is likely to make, or what structure would help it operate more safely.

The second lesson is the mirror image of the first: Codex knows nothing about the context I never share, but it will still try to be helpful. That means it will fill in gaps. Sometimes that looks like a reasonable inference. Sometimes it turns into confident nonsense. Either way, silence does not stay neutral for long.

That leads to a third lesson: Once I explain the context clearly, I can ask Codex where the friction is in the workflow itself. That matters. If I only ask for outputs, I usually get outputs. If I also ask how the collaboration could work better, the environment starts improving alongside the work.

Another lesson came from changing things behind the scenes. If I reorganize the structure without keeping Codex in the loop, something is likely to break. Paths drift. Assumptions go stale. Operating rules stop matching reality. But when I keep Codex involved, and especially when I let it do the heavy lifting of updating the structure, the system stays cleaner and the shared map stays aligned.

We also learned when a repeated workflow is ready to become infrastructure. Once we have worked through a use case a few times, that is usually the moment to ask Codex to turn the pattern into a skill, agent, or playbook. Repetition is the signal that a useful behavior should stop living only in chat history.

And one final lesson follows from that: skills, agents, playbooks, and saved memories are not one-and-done assets. As the structure changes, it is worth revisiting the older workflow assets so they continue to match reality. Otherwise yesterday’s helpful automation becomes tomorrow’s hidden source of friction.

Why Structure and Rules Matter

The most useful artifact in this setup is not a clever prompt. It is the structure that tells everyone where things belong, along with the rules that keep the collaboration from drifting.

When the workspace has named roots for vaults, websites, apps, and automation, the bot no longer has to infer intent from a pile of folders. It can follow contracts instead of vibes.

That matters even more when your notes are incomplete. In my case, the source material for the career website was still evolving. The system needed to support that messiness without letting the bot mistake rough notes for final claims or scatter outputs into random places.

A small configuration file and a few shared operating rules can do a surprising amount of invisible work:

• identify the default vault
• define the expected folder layout
• create shared assumptions that survive across sessions
• lower the odds of the bot operating in the wrong place
• make edits easier to verify
• reduce the need to restate the same expectations every time

This is boring infrastructure, which is exactly why it matters. Good structure is what lets creative work remain intelligible after the fact.

Some of our most useful rules are simple:

• always specify the target vault explicitly
• inspect before editing
• make the smallest viable change
• verify outputs early
• summarize what changed before moving on

Those rules reduce the chance that a bot turns ambiguity into confident nonsense. They also reduce human cognitive load. The environment itself starts carrying part of the context.

That creates a useful feedback loop: explain the context, ask where the friction is, improve the workflow, and then update the reusable assets that support it. That is when the setup starts to feel less like a demo and more like a second brain.

Boundaries Matter

The repository model also needs to match how the work is likely to grow.

The root repository acts as the coordination layer. It holds shared configuration, automation, and the folder structure that tells the human and the bot how the workspace is organized.

Inside that workspace, the major surfaces can become their own repositories:

• vaults/* for note systems
• apps/* for supporting tools
• websites/* for published outputs

This has real advantages. It keeps the working environment connected while preserving clean boundaries. A vault can remain private and evolve independently. A website can have its own deployment history. Automation can improve without polluting the history of every downstream artifact.

For the career-site case study, that separation is especially useful. The notes are one thing. The generated public-facing website is another. They are related, but they do not need to live in the same Git boundary forever.

The Shape of the Setup

If you were building this from scratch, the shape is straightforward.

1. Start with a shared workspace root

Create a workspace folder that can hold your vaults, automation, apps, and websites. A simple layout looks like this:

your-workspace/
  obsidian.config.json
  automation/
  vaults/
    .gitkeep
  apps/
    .gitkeep
  websites/
    .gitkeep

Keep the root as the collaboration layer. This is where the shared config, automation, and playbooks live. If you want the empty top-level folders to survive cloning, track lightweight placeholders such as .gitkeep files or tiny README files.

2. Define the path contracts

Add an obsidian.config.json file that tells the human and the bot where each category of work belongs. Shared path contracts eliminate a remarkable amount of ambiguity.

At minimum, define:

• the vault root
• the apps root
• the websites root
• the automation root
• a default vault identifier
• any default website identifier

If you plan to split products into their own repositories later, encode that policy here as well.

Here is a minimal example:

{
  "paths": {
    "vaults_root": "vaults",
    "apps_root": "apps",
    "websites_root": "websites",
    "automation_root": "automation"
  },
  "defaults": {
    "vault_id": "my-vault",
    "website_id": "my-website"
  },
  "vaults": {
    "my-vault": {
      "path": "vaults/my-vault",
      "role": "default"
    }
  }
}

3. Put the vault inside the workspace

Store the Obsidian vault under vaults/<vault-name>. Choose a stable vault name and use it consistently.

One of our most important lessons came from this: always target the vault explicitly in automation instead of depending on hidden application state.

4. Use VS Code as the implementation side

Open the workspace root in VS Code, not just the vault folder.

That gives the human and the bot access to:

• the vault content
• the automation scripts
• the config file
• the website and app folders

That matters because the collaboration usually crosses boundaries. The note, the script, the config, and the website output often all matter in the same session.

There is one VS Code setting worth changing if your actual Git repositories live a few levels below the workspace root. VS Code documents git.repositoryScanMaxDepth as the control for repository-discovery depth. In this setup, repositories inside paths like vaults/<vault-name>/... may not appear unless you increase:

"git.repositoryScanMaxDepth": 3

Set it to at least 3 for this workspace so VS Code can find nested repositories reliably.

5. Give the bot operating rules, not just tasks

This is where the environment starts to feel intentional rather than improvised.

Document the rules that matter, such as:

• always specify the target vault
• never depend on hidden state
• inspect before editing
• use checklists for repeatable workflows
• checkpoint frequently
• summarize changes after each meaningful step

We turned those rules into separate skills so the lessons became reusable instead of conversational folklore.

6. Choose a Git model that matches publishing reality

Use the root repository for shared coordination.

Then decide which folders should become independent repositories over time. In our case, it makes sense for vaults, apps, and websites to each have the option of living in their own Git boundary.

For websites in particular, separate repositories are useful because they align neatly with GitHub Pages hosting for eligible public repositories.

A simple root .gitignore can enforce that separation while still preserving the top-level workspace skeleton:

_scratch/

vaults/*
!vaults/.gitkeep
!vaults/README.md

apps/*
!apps/.gitkeep
!apps/README.md

websites/*
!websites/.gitkeep
!websites/README.md

That policy keeps the coordination repo focused on shared assets while still preserving the intended folder skeleton. The child repositories continue to manage their own tracked content and history, but the root repo retains just enough structure to make the workspace easier to clone, understand, and bootstrap.

7. Work in short loops

Do not try to define everything upfront.

Pick the next step, verify it, capture what you learned, and move on. The goal is not just progress. The goal is trustworthy progress.

Final Thought

The most important outcome here was not that I got an Obsidian-related workflow working or that Codex generated a website from my notes.

It was realizing that, with the right structure, my notes had already become more than personal archive material. They had become working context.

I now have vaults where I can think in fragments, a workspace where those fragments can be organized into something useful, and an AI collaborator that can help turn incomplete notes into draft outputs without pretending uncertainty does not exist.

That is the real promise of this setup. Not automation for its own sake, but a calmer, more durable way to turn lived experience into usable momentum while steadily improving the collaboration itself.