Use Claude Code with your notes: a practical guide

To use Claude Code with your notes, keep the notes as plain Markdown files and let Claude Code work on them through a terminal. Loam is our app: a free, open source Markdown notebook for macOS whose loam command line runs every action of the app, with a skill that tells an agent which rules to follow. This guide covers the setup, five workflows with the real commands, and how to stay safe.

Why are Markdown files good for AI agents?

An agent needs two things to work on notes: a way to read them and a way to change them. Plain files give both, with no account, no token and no network. In Loam a note is a .md file in a folder you choose, so an agent that can read files and run shell commands has what it needs. Claude Code does both, and its permission system asks you before it edits a file or runs most shell commands.

Here is a small vault. The notes are ordinary files. The hidden .loam/ folder holds settings, and agents change them through commands, never by hand.

~/Notes/
├── Projects/
│   ├── Beta.md
│   └── Roadmap.md
├── Daily/
│   └── 2026-11-03.md
├── .loam/config.json
└── .trash/

The Loam app, the loam command line and the agent read and write these same files. The app watches the folder, so a note the agent writes shows at once in the open window. Vault commands run on your Mac and work without the app open.

How do I install Loam and its skill for Claude Code?

Loam runs on macOS 26 or later, on Apple silicon. One command installs the app and links the command line to ~/.local/bin/loam. Then loam skill install --claude installs the skill for Claude Code.

curl -fsSL https://raw.githubusercontent.com/Azilone/loam-releases/main/install.sh | bash
loam help
loam skill install --claude
loam skill status
loam guide

The skill is a short file written to ~/.claude/skills/loam/, one of the folders where Claude Code looks for personal skills. Claude Code uses a skill's description to decide when to apply it, and this skill tells the agent to run loam guide before it touches a vault. The guide matches your installed version of Loam. Without a flag, loam skill install writes every target, and loam skill status shows whether each copy is current.

You can also hand the install to Claude Code. The Agents page copies a one-line prompt that points the agent at /agents.md. The agent asks you before it installs the app, and again before it writes the skill to your home folder.

loam guide has topics for notes, commands, plugins, ui, test, app and share. loam guide notes covers how notes, tasks and collections are written, and loam guide commands lists the search and link commands.

Start Claude Code in the vault folder. loam finds a vault from the --vault option, then the LOAM_VAULT variable, then the current folder, so inside the vault the commands need no flag. The examples below assume that. Outside the vault, add --vault ~/Notes.

cd ~/Notes
claude

Every workflow below follows one loop. The agent runs a loam command, the command reads or writes the vault, and the result comes back to the agent. Results go to stdout, usually as JSON. Errors go to stderr as a JSON object with an error key, with exit code 1 for a failed command and 2 for bad usage.

Workflow 1: create a note

Ask Claude Code for a note, and it writes a Markdown file into the vault. The agent rules say to write plain formats only (CommonMark, GitHub Flavored Markdown and YAML frontmatter) and to link notes with standard Markdown links, because backlinks follow those and not [[wikilinks]]. A request such as 'create Projects/Beta.md with a plan and link it to the roadmap' gives you a file like this.

---
status: doing
created: 2026-11-03
tags: [project, work]
---

# Beta plan

Part of the [roadmap](Roadmap.md).

## Tasks
- [ ] Ship the beta due:2026-11-20 #work !high

The agent reads a note right before it writes it, because you may be typing in it. To change one property later, it runs query.set-property, and the rest of the note stays as it was. notes.backlinks lists the notes that link to a note. tasks.add also creates a note when the path does not exist.

loam query.set-property path=Projects/Beta.md key=status value=done
loam notes.backlinks path=Projects/Roadmap.md

Workflow 2: search the vault

Search needs nothing installed. search.content returns the lines of text that match, with their line numbers, and search.names matches file names with fuzzy matching. query.run tag=project finds the notes that carry a tag. A question such as 'what did I decide about the roadmap?' can become a search.content call, followed by a read of the notes it finds.

loam search.content q="roadmap"
loam search.names q=plan
loam query.run tag=project

Search takes q=. A key a command does not know is ignored with no error, and query= alone fails with a missing argument, so the agent checks spelling in loam list. Search by meaning, search.meaning, needs Truffle, a separate tool that you install with brew install azilone/tap/truffle. See Links, backlinks and search.

Workflow 3: list and check tasks

A task is a checkbox line in any note, so there is no task database to keep in sync. tasks.list returns tasks sorted by due date, then priority, and all its arguments are optional, such as done, dueOn, project and tag.

loam tasks.list done=false dueOn=today
loam tasks.add path=Work/Launch.md text="Ship the beta due:2026-11-20 #work !high"
loam tasks.toggle path=Work/Launch.md line=8 text="Ship the beta #work"

tasks.toggle takes the line and the text that tasks.list returned. It writes nothing if the line no longer holds that task, so a check made on stale data does nothing. See Tasks for the due date, priority and tag syntax.

Workflow 4: add to the daily note

daily.append adds a line to today's note and creates the note from your template if it is missing. It prints the path of the note. Add date= to write to another day. At the end of a session, ask Claude Code to log what you decided, and it appends the lines for you.

loam daily.append text="Met Bob about the beta"
loam daily.read date=2026-11-03
loam daily.prepend text="Launch day" date=2026-11-03

The note lands in the folder you set for daily notes, Daily by default, as one file per day. daily.read returns an empty result when a day has no note. See Daily notes for the template and the other daily.* commands.

Workflow 5: import with a dry run

Importers have a dry run, and an agent should always start with it. Run the dry run, read the report, then run the import for real. The dry run writes nothing. The report counts what is converted and copied, lists what is skipped because it already exists, and lists warnings for links and files that need a look.

loam import.obsidian source=~/ObsidianVault dry-run=true
loam import.obsidian source=~/ObsidianVault into=Imported
loam import.notion source=~/Downloads/Export.zip dry-run=true

An import only reads the source, and by default it never overwrites a file that exists. Bear and Apple Notes have importers too, import.bear and import.apple-notes, and macOS may ask for permission once. For Craft or another app, export Markdown from the app, and the agent copies the .md files into the vault. Copy, never move. See Import notes.

Cheat sheet: commands an agent can run

This table lists the commands from the five workflows and whether each one changes a file. Run loam list for the full set.

How do I stay safe when an agent edits my notes?

Keep the agent's work small, reviewable and reversible. Five habits do that.

• Dry run first. Every importer takes dry-run=true and writes nothing. Read the report before the real run.
• Read the prompts. Claude Code asks before it edits files or runs most shell commands, and it reads files inside its working directory without asking, so start it in a folder you are happy for it to read. Rules in a settings.json file can allow or deny commands.
• Read plugin permissions. loam plugin install never enables a plugin. The agent tells you what the plugin does and which permissions it asks for, such as vault.write or network, and enables it only after you agree. The list is shown, not enforced, so enable only plugins you trust. See Plugin permissions.
• Let deletes go to the trash. An agent never deletes a note and never runs rm. It asks you, then runs files.trash, which moves the note to .trash/, where it stays for 30 days.
• Keep a way back. Git history is the undo button, as the next section shows.

The permission rules look like this. They allow two read-only commands and block rm. Claude Code evaluates deny rules first, so a deny rule always wins.

{
  "permissions": {
    "allow": ["Bash(loam search.content *)", "Bash(loam tasks.list *)"],
    "deny": ["Bash(rm *)"]
  }
}

Sources: Claude Code: configure permissions ↗ · Claude Code: skills ↗ · Claude Code: quickstart ↗

How does Git history undo an agent's edits?

Git history is the undo button. With Git sync on, Loam commits changes about 30 seconds after the last one, with a message such as vault backup: 2026-11-03 14:05:03 (<device>). Loam merges and never rebases, and it never runs reset, clean, stash or a forced push, so history is not rewritten. After an agent session, git log -p in the vault shows what changed. Run sync.now before a big job to leave a checkpoint.

loam sync.setup url=https://github.com/<you>/<vault>.git
loam sync.now
git -C ~/Notes log -p -- Projects/Beta.md

To get an older version of a note back, restore the file from the commit you want with ordinary Git. A deleted note is in .trash/, and trash.restore brings it back.

An encrypted remote protects the copy that leaves your Mac. It does not hide notes from an agent on your Mac, which reads plain files. The key lives in the Keychain of each Mac and never in the vault, and file names, sizes and commit messages stay readable. Keep a copy of the key somewhere safe: without it, the remote can never be read again.

Do Codex, Cursor and other agents work the same way?

Yes. The commands do not depend on the agent. loam skill install --codex writes ~/.codex/skills/loam/, and --agents writes ~/.agents/skills/loam/ for Antigravity, Pi, OpenCode and Codex. For a terminal agent that the flags do not name, such as Cursor, ask it to run loam guide first. loam skill print shows the text of the skill.

If your assistant has no terminal and only speaks MCP, read Note-taking apps with MCP servers. For why the files matter, see Local-first: where your notes live.

Try Loam with Claude Code

Install Loam with the one command on the install page, open a vault, and run loam skill install --claude. Know the limits first: Loam runs on macOS 26 or later with Apple silicon, it has no iPhone or Android app, and it is a single-user app, with sharing through Git. To see how it differs from the app most people compare it with, read Loam vs Obsidian, or browse every comparison.