Cursor and Obsidian: an AI agent for notes in your vault

Obsidian keeps notes as plain Markdown files in a folder on disk, which opens a simple path: open that folder in an editor with an agent and the AI can see all your notes at once. The "cursor ai obsidian" setup is for people with hundreds of notes that have no tags, broken links and unsorted daily logs. Below: how to open the vault, how to give the agent rules, which tasks suit it, and how to avoid damaging the structure.

Cursor AI and Obsidian: why a vault suits an agent

An Obsidian vault is an ordinary folder. Inside are .md files, attachments and a service folder .obsidian with settings. There is no closed database, so Cursor, Claude Code or Codex read and edit notes the same way they handle source code. Obsidian can stay open meanwhile: when a file changes on disk, the app usually picks the change up by itself.

Two things about notes the agent must know:

• links are written as [[Note title]] or [[Note|label]], and renaming a file by hand breaks them;
• properties live in a frontmatter block at the top of the file between --- lines: tags, dates, aliases.

If you want AI inside the Obsidian window itself, that is a different task, covered in the article on an AI plugin for Obsidian↗. Here we talk about an external agent that works on the folder.

Preparation: a safety net and rules

An agent changes many files in one go, so insurance comes first.

1. Copy the vault or turn it into a git repository: git init, then git add -A and a first commit. After the agent works you will see the exact diff and can roll back any edit.
2. Keep out what the agent should not see: personal journals, finances, passwords. Cursor has an ignore file for that; check its exact name and syntax in the Cursor documentation. The most reliable way is simpler: keep private notes outside the opened folder.
3. Put a rules file in the vault root. Cursor reads rules from .cursor/rules and from AGENTS.md (see the article on Cursor rules↗), Codex looks for AGENTS.md, Claude Code reads CLAUDE.md. The same rules text can go into both files.

An example of vault rules:

## Vault rules

- Do not touch the .obsidian folder.
- Write links between notes as [[Title]]. Do not rename or move files unless I say so.
- Frontmatter fields: tags (list), created (YYYY-MM-DD), status. Never delete existing fields.
- Use tags only from the file Tags.md. Propose new tags as a list, do not add them yourself.
- Show the plan of edits as a list of files first, change files only after I confirm.
- Do not invent facts. If a note lacks something, say so.

The last two items matter more than the rest: a plan before edits and a ban on making things up.

Connecting Zukko models

In Cursor: Settings → Models, enable your own OpenAI key fetch_..., turn on the Base URL override and set https://api.zukko.pro/v1. For Claude, take the model name from the Cursor guide↗: Cursor does not accept a name it already knows, so popular models have second names, for example cursor-sonnet-5 for Claude Sonnet 5. GPT and the cheaper lines can be entered under their regular ids, for example gpt-6.1-sol. Overriding the provider in Cursor may depend on your plan, so check the current terms on the Cursor site.

For Claude Code just go to the folder and start the agent:

cd ~/Documents/MyVault
claude

The key is set through the variables ANTHROPIC_BASE_URL=https://api.zukko.pro and ANTHROPIC_AUTH_TOKEN=fetch_... (details in the Claude Code guide↗). Codex works the same way: cd into the vault and run codex, with the provider set in ~/.codex/config.toml. So the "codex obsidian" query comes down to the same scheme: a notes folder plus an AGENTS.md in the root.

Usage examples: what to hand the agent

Tasks for "cursor ai usage examples" in a vault are mechanical or semantic. Mechanical ones are safer.

Tagging. "Go through the notes in the Projects folder. In those without frontmatter add the fields tags and created. Take tags only from Tags.md. Show the file list before editing."

Finding links. "Find notes with no incoming links and for each suggest two or three notes it should link to. Change nothing, output a table."

Weekly summary. "Read the daily notes of the last seven days in the Daily folder and build a summary: what is done, what is left, which decisions were made. Save it as a new note Weekly summary 2026-10-18. Attach a link to the source note to each item."

Link check. "Find [[...]] links that point to non-existent notes and list the files where they occur."

Splitting a long note. The agent proposes to split a file into atomic notes with links and creates them only after you agree.

Do semantic tasks (rewrite, merge, shorten) on a copy of the note or in a separate git branch. The error is hard to see there: the text stays smooth while the meaning may shift.

How not to break the vault

• Renames. Obsidian updates links itself when you rename a file in its interface. The agent works with files directly and updates links only if you demand it. It is simpler to forbid renaming and do it by hand.
• Sync. If the vault syncs through a cloud or a sync service, do not run mass edits while syncing: version conflicts are likely. Wait for sync to finish, commit, then work.
• A diff after each task. Open git diff and look through it selectively. One check per task pays off.
• Sensitive data. Everything the agent reads goes to the model. If the vault contains personal data, keep it out of the folder or mask it before sending.

What it costs

Prices on October 18, 2026, per 1M tokens. For claude-sonnet-5 input is $0.4, output $2. Example: the agent tags 40 notes of 1,500 tokens each, so it reads 60,000 tokens and writes 5,000.

Cost = 60,000 × 0.4 / 1,000,000 + 5,000 × 2 / 1,000,000 = 0.024 + 0.010 = $0.034.

For deepseek-v4.1-flash (input $0.013, output $0.038): 60,000 × 0.013 / 1,000,000 + 5,000 × 0.038 / 1,000,000 = 0.00078 + 0.00019 ≈ $0.001.

This is a lower bound: at every step the agent sends the accumulated conversation back to the model, so real spend is higher. Measure it on your own task in the "Usage" section of the dashboard and set a daily limit on the key. Current prices: GET https://api.zukko.pro/v1/models or the "Models" page in the dashboard.

FAQ

Can I keep Obsidian open while the agent works?

Usually yes: the app picks up file changes on disk. But do not start mass edits during a sync, and make a commit or a copy first.

Cursor, Claude Code or Codex: which one?

For a vault all three behave the same because they work on a folder. Cursor is handy if you want to see edits as a diff in an editor. Claude Code and Codex live in the terminal. Try them on a copy of the vault and compare spend and results.

Will the agent break links between notes?

It can, if you let it rename and move files. Forbid that in the rules, require a plan before edits and check the diff.

How can I try it without big spending?

Create a key in the Zukko dashboard↗, set a daily limit of a few dollars on it and start with a copy of the vault on a cheap model.