Set up agent access.
Install steps, the skills, memory and every command your agent can run. For the plain-language version, see the AI agents page.
You don't have to read any of this to use Jotura with an agent. The one-line installer puts the command-line tool in place, and you add the skills the way you add any other skill. This page is for anyone who wants to see every command.
The same Rust core, two surfaces.
Jotura comes with a command-line tool called jotura, built on the same Rust modules as the desktop app. Your agent talks to the CLI, and the CLI reads and writes the plain files in your vault on your own disk. Nothing in the cloud sits between your AI and your notes, and your AI provider sees only the snippets your agent chooses to send.
- Nothing to unlock.
- Your notes are plain markdown files on disk, so every CLI command works the moment your agent runs it, without a passphrase or a session to keep alive. The only key in the system belongs to cloud sync, and the desktop and CLI share it automatically.
- Your typing is safe from your agent.
- Every edit accepts a hash-based precondition. Say you're halfway through a paragraph in the desktop app when your agent tries to rewrite the same note: its write fails with a clear conflict, and your paragraph stays put. The agent then reads the note again and decides whether to retry.
- Both sides see each change within a second.
- When the CLI writes, the desktop's file tree, search index and any open tab refresh within a second, and edits you make in the desktop are on disk for the CLI about a second after you stop typing. Nobody has to hunt for a refresh button.
Install Jotura.
One command installs the desktop app and puts the jotura CLI on your PATH, with nothing else to download or compile. It leaves your AI agents' config files alone. Your instruction files are yours to write however you like, and you add the skills separately, as shown further down.
# macOS and Linux
curl -fsSL jotura.io/install.sh | bash
# Windows (PowerShell)
irm jotura.io/install.ps1 | iexThe script verifies every download's checksum before anything runs, and rerunning it upgrades in place. If you'd rather click through an installer, the download page has one for every platform.
Once Jotura is installed, confirm the CLI is on your PATH:
jotura --versionVaults are plain folders of markdown files, so every command works straight away, and your agent can read and edit notes without a passphrase or any configuration first.
On macOS, the one-line installer symlinks the CLI to /usr/local/bin/jotura for you. If you installed from the DMG, the CLI ships inside Jotura.app: open Settings → Command-line tool and click Install to create the same symlink. On Windows and Linux (deb), the installer puts it on PATH automatically. On the Linux AppImage, the first launch offers to copy it to ~/.local/bin.
Teach your agent.
The Jotura skills live in the jotura-agents repository on GitHub. Claude Code installs them as a plugin. Every other agent gets the same files by copying them into place.
Claude Code
The skills ship as a Claude Code plugin in the jotura-agents marketplace. Add the marketplace once, then install the plugin from inside a Claude Code session.
/plugin marketplace add adamrichardson14/jotura-agents
/plugin install jotura@jotura-agentsAsk Claude something like “what's in my vault?” and the jotura-vault skill should trigger, and the agent should run jotura status --json before anything else.
Other agents
Codex, Gemini CLI, GitHub Copilot, OpenCode and any other agent that runs shell commands can use the same skills. Copy the SKILL.md files and their references from the jotura-agents repository into wherever your agent loads skills or instructions, such as ~/.agents/skills for Codex.
git clone https://github.com/adamrichardson14/jotura-agents
ls jotura-agents/jotura/skillsStart a new session and ask the agent to find a note. It should call jotura status before it does anything else.
Once installed, the skills belong to you. Edit them, trim them or fold them into your own instruction files. Jotura never writes to your agent's config, so nothing overwrites your changes. To take a newer version, run /plugin marketplace update jotura-agents in Claude Code, or copy the files from the repository again.
Built for the way agents edit.
An LLM edits a note the way a careful colleague would, with small targeted changes it wants to check before they land. These six features give it exactly that, and together they open up ways of working that the desktop app alone doesn't offer.
- Hash-checked edits.
write,editand eachbatchentry accept a hash precondition. If the file changed while the agent was working, the write fails with a HashConflict and a unified diff between what the agent meant to write and what the file holds now, so the agent can see exactly what moved.- Atomic batch operations.
edit --applyruns a sequence of edits to one note with one hash check and one write.batchapplies file-level ops across many notes, checking every precondition before it writes anything and then writing each change atomically.- Dry-run + diff preview.
--dry-runcomputes the change without writing;--diffreturns unified-diff output. Put them together and you can read any edit as a diff before the agent commits to it.- Shared sync key with the desktop.
- When cloud sync is on,
jotura sync loginon either surface caches the sync key on the device: a 0600 file on macOS and Linux, the same trust model as your SSH keys, and a file encrypted for your Windows account on Windows.jotura sync statusreports it;jotura sync logoutclears it for both. - Vault-shape commands.
- Your agent gets the same tools you'd reach for in Obsidian: backlinks, links, templates, trash and restore, and grep with the ripgrep flags you already know.
- Live change events.
jotura watchstreams every vault change to stdout as one JSON object per line. A script or agent can subscribe and respond whenever something touches the vault, whether the change came from another command, the desktop app or sync.
Every command, grouped.
Here is the full surface, from reading and searching through to daily notes, documents and diagnostics, with every flag worth knowing about.
Read & explore
Find and read notes. All commands support --json for structured output.
| Command | Does |
|---|---|
jotura read <path> | Body to stdout; --numbered, --with-frontmatter |
jotura ls [--folder F] | List notes; recursive tree |
jotura search <q> | Fuzzy full-text via Tantivy |
jotura quick-open <q> | Filename and frontmatter-alias fuzzy match |
jotura grep <pattern> | Regex over note content with --ignore-case, --include, --files-with-matches |
jotura backlinks <path> | Notes that link to <path> |
jotura links <path> | Outgoing links from <path> |
Targeted edits
Edits match on a string by default and fail when the match is ambiguous. When you know the line numbers, edit by position instead.
| Command | Does |
|---|---|
edit --replace OLD --with NEW | Strict; --all or --nth N for multiples |
edit --replace-line N | Replace single line |
edit --replace-lines N:M | Replace inclusive range |
edit --insert-before/--insert-after N | Insert at line position |
edit --delete-lines N:M | Remove range |
edit --append / --prepend | End, or top (after frontmatter) |
write <path> | Body-default; --full for whole file |
Atomic batches
Send many edits in one call, with fewer round trips and every precondition checked as a single transaction.
| Command | Does |
|---|---|
edit --apply <FILE> | Multi-edit one note; ops apply sequentially |
batch <FILE> | Multi-file batch; plan + preconditions atomic |
Notes lifecycle
Create, rename and delete notes. Anything sent to the trash can be restored.
| Command | Does |
|---|---|
jotura create <parent> <name> | Auto-suffixes on collision; --template |
jotura rename <old> <new> | Refuses if destination exists |
jotura trash <path> | Soft-delete; recoverable |
jotura trash list/restore/empty/purge | Manage trashed items |
jotura delete <path> | Permanent delete; escape hatch |
Frontmatter & tags
Edit commands leave frontmatter alone, so changes to YAML keys and tags go through these commands instead.
| Command | Does |
|---|---|
frontmatter get <path> [key] | Read full YAML or one key |
frontmatter set <path> <key> <val> | Set value; preserves order |
frontmatter delete <path> <key> | Remove a key |
tag add <path> <tag> | Append to tags array (idempotent) |
tag remove <path> <tag> | Remove from tags array |
tag list <path> | List tags |
Templates
Reusable note skeletons stored alongside your notes.
| Command | Does |
|---|---|
templates list / show <name> | Browse available templates |
templates create <name> | From stdin or --from <existing> |
templates delete <name> | Remove a template |
create --template <name> | Spin up from template |
today --template <name> | Today's daily note from template |
Variables | {{date}}, {{time}}, {{datetime}}, {{filename}}, {{title}} |
Daily notes
First-class workflow for journals and daily logs.
| Command | Does |
|---|---|
jotura today | Open or create today's note (Daily/YYYY/MM/...) |
today --read | Print today's body |
today --append <TEXT> | Append a line (or from stdin) |
today --date YYYY-MM-DD | Operate on a specific date |
today --template daily | Create from a template |
Documents
Import PDFs, Word files, spreadsheets and more. Each one gets a searchable markdown mirror in .md_store/.
| Command | Does |
|---|---|
jotura import <file> | Copy into the vault; --folder, --as |
jotura search-documents <q> | Search the mirrors; returns ORIGINAL paths |
jotura ls-documents | List documents + conversion status |
jotura read .md_store/<path>.<ext>.md | Read the converted text |
jotura regenerate-md-store --stale-only | Refresh stale conversions |
Agent memory
Decisions, facts and open follow-ups are ordinary notes with frontmatter under Memory/Decisions, Memory/Facts and Memory/Followups. The skill tells the agent when to run each of these.
| Command | Does |
|---|---|
jotura context "<task>" | Conventions, relevant memory and open follow-ups for a task |
jotura memory recall "<topic>" | Ranked recall; smart by default, keyword without an index |
memory log --kind decision|fact|followup | Record a memory; --title, --occurred YYYY-MM-DD |
memory list --kind K --status S | Browse memories |
memory supersede OLD --by NEW | Mark an old memory as replaced |
memory resolve <path> | Close a follow-up |
memory doctor [--fix] | Find stale or broken memory; --fix backfills dates only |
Diagnostics & extras
Manage the sync key, check the vault's health, stream changes, and set up shell completion.
| Command | Does |
|---|---|
jotura sync status / login / logout | Sync key cache, shared with the desktop |
jotura status / doctor | Vault state; diagnostic checks |
jotura vault info | Note count, total size, sync state |
jotura watch | Stream change events as JSON lines |
jotura completion <shell> | bash/zsh/fish/elvish/powershell |
Every mutating command except trash (write, edit, create, rename, delete, frontmatter, tag, batch) accepts --dry-run for previews and --diff for unified-diff output, and every command takes --json for structured output. Write, edit and each batch entry also accept a hash precondition (--if-hash, or ifHash in batch JSON) for safety. Errors arrive on stderr as JSON with distinct exit codes (HashConflict, NotFound, Ambiguous, OutOfRange) so an agent can react without parsing prose.
What the agent reads.
The jotura-vault skill is a short entry point that teaches any agent how to edit safely, which commands it will use every day and which exit codes it should react to. Reference files sit beside it and load only when a task needs them. A second skill, jotura-notes, covers where notes belong and how memory gets captured.
references/search.md: semantic and smart search, grep flags, backlinks and links, searching documentsreferences/documents.md: importing PDFs, Word and spreadsheets; plaintext and HTML files; md_store mirrorsreferences/batch.md: more than one edit in a note, and atomic edits across notesreferences/lifecycle.md: create, rename, trash and restore, templates, whole-body writes, watch, completion, doctorreferences/images.md: looking at an image a note embeds, adding an image to a note, image sizing syntax
What the agent does with it.
Here are six requests you might type to your agent, with the commands it runs to answer each one.
What did I write about Project X last week?
The agent checks the vault, searches it, reads the most relevant hit and hands you a summary.
jotura status --json
jotura search "project x" --json | jq '.[:5]'
jotura read Daily/2026/05/2026-05-22.mdSummarise the PDF I dropped in the vault.
Jotura turns imported documents into searchable markdown on its own. The agent searches those mirrors and reads the converted text, because markitdown has already done the PDF parsing for it.
jotura search-documents "vendor agreement" --json
jotura read ".md_store/attachments/vendor-agreement.pdf.md"Mark every TODO in today's note done.
The agent reads the note with its hash, builds a multi-op edit, and applies every replacement with one hash check and one atomic write.
HASH=$(jotura read inbox/today.md --json | jq -r .hash)
echo '[
{"kind":"replace","old":"TODO: reply to alice","new":"DONE: replied to alice"},
{"kind":"replace","old":"TODO: file expenses","new":"DONE: filed expenses"},
{"kind":"replace","old":"TODO","new":"DONE","all":true}
]' | jotura edit inbox/today.md --apply - --if-hash "$HASH" --diffFind every note linking to a doc and add a tag.
Backlinks find every note that points at the doc, and one atomic batch tags them all.
jotura backlinks docs/policy.md --json \
| jq -r '.hits[].path' \
| jq -R -s 'split("\n") | map(select(length > 0))
| map({path: ., op: {kind: "tag-add", tag: "policy-link"}})' \
| jotura batch -Spin up a meeting note from a template and watch for additions.
One command fills in the template variables, and a second streams changes back so the agent can follow along while you take notes in the meeting.
jotura create meetings 2026-05-27-product-sync --template meeting
jotura watch --paths "meetings/**" &
# Agent can now react to every save as the meeting progressesRename a note and update its backlinks.
The agent checks which notes link to it, previews the move, then renames it. The rename rewrites every link that pointed at the old name.
jotura backlinks projects/old-name.md --json
jotura rename projects/old-name.md projects/new-name.md --dry-run # preview
jotura rename projects/old-name.md projects/new-name.md --json # reports linksUpdatedYou decide what your agent sees.
Your notes stay as plain files on your machine, and your agent reads only the ones it asks for. If you turn on sync, each note is encrypted on your device before it uploads, so our servers only ever hold ciphertext.