Agents and MCP

The Octarine CLI is designed to be driven by AI agents such as Claude Code, Codex, or Cursor as well as by people. Agents can call the CLI from a shell, or connect to it as a Model Context Protocol (MCP) server. Both run the same commands, so behavior is identical either way.

Everything runs locally against your Markdown files. The desktop app does not need to be open.

agent-guide

Print a short guide that tells an agent how to find notes, read them before editing, make small revision-checked edits, and recover from conflicts.

octarine agent-guide

Paste the output into your agent's instructions, such as a project CLAUDE.md or AGENTS.md, or ask the agent to run the command itself before working with your notes:

octarine agent-guide >> AGENTS.md

help --json

Describe commands in machine-readable form: every argument with its type, default, and allowed values, plus the global options, response envelopes, and error codes.

octarine help --json
octarine help note edit --json

{"schemaVersion":1,"ok":true,"data":{"name":"octarine","version":"0.1.0","commands":[{"command":"note edit","about":"Replace exact text in a note (one match unless --all)","arguments":[{"name":"path","positional":true,"required":true,"schema":{"type":"string"}},{"name":"find","flag":"--find","required":true,"schema":{"type":"string","description":"Exact text to find"}},…]}],"globalOptions":[…],"output":{…},"errors":[…]},"meta":{"truncated":false}}

Without --json, octarine help <command> prints the same help as octarine <command> --help.

octarine mcp

Serve the CLI as MCP tools over standard input and output.

octarine mcp [--workspace <name, uuid, or path>] [--all-tools]

Connect An MCP Client

Add Octarine to Claude Code:

claude mcp add octarine -- octarine mcp --workspace "Work Notes"

For clients configured with JSON, such as Claude Desktop or Cursor, add a server entry:

{
  "mcpServers": {
    "octarine": {
      "command": "octarine",
      "args": ["mcp", "--workspace", "Work Notes"]
    }
  }
}

If the client cannot find octarine, use the full path printed by which octarine (or where octarine on Windows).

--workspace fixes the workspace for the server. Without it, the server uses the default workspace. Every tool also accepts an optional workspace argument to target a different workspace for one call.

Available Tools

Tool names follow the command path, with spaces and hyphens replaced by underscores: note replace-section becomes note_replace_section. Each tool's input schema matches the command's arguments, and each result is the command's JSON response.

By default, the server exposes a curated set of everyday tools:

Area	Tools
Workspaces	workspace_list, workspace_show, workspace_info, capabilities
Reading	note_list, note_read, note_context, note_info, note_outline, note_properties, search
Editing	note_create, note_edit, note_replace_section, note_insert, note_patch, note_append, note_prepend, note_update
Organizing	note_move, note_rename, note_duplicate, note_trash, folder_list, folder_create, folder_move
Links	link_list, link_backlinks, link_unresolved, link_orphans, link_deadends, link_mentions
Tasks, tags, and properties	note_task_list, note_task_set, task_list, tag_list, property_list, property_get, property_set, property_unset
Inbox	inbox_capture, inbox_list

Add --all-tools to expose every other command as well, including folder rename, duplicate, and trash, link_replace, views, note types, themes, property definitions, metadata, folder configuration, the rest of the Inbox commands, schema, export, and doctor.

update, completion, config, workspace use, help, agent-guide, and mcp are never exposed as tools.

Read-only tools, such as note_read and search, are marked as read-only. Tools that trash, delete, unset, or replace content, such as note_trash and note_update, are marked as destructive, so clients that ask before risky actions can prompt you.

Recommended Agent Workflow

The CLI is built so agents can edit notes precisely without overwriting your changes:

1. Find notes with search or note list --sort modified --limit 20. Follow meta.nextCursor with --cursor to page through long searches.
2. Read before editing with note context. It returns the content, its revision, the outline with line numbers, properties, links, and backlinks in one call.
3. Edit as little as possible with note edit, note replace-section, note insert, or note patch, always passing --revision. Use note update only to rewrite a whole note.
4. Chain edits using the revision each edit returns.
5. Handle conflicts. On REVISION_CONFLICT, the note changed since it was read. Re-read it, re-apply the change, and retry with error.currentRevision. On AMBIGUOUS_MATCH, include more surrounding text.

To link notes, write workspace-relative paths without .md, such as [[Projects/Launch]] or [[Projects/Launch#Goals|goals]]. Moving or renaming a note with the CLI updates links to it automatically.

Set JSON output once so the agent does not need --json on every call:

octarine config set format json

Quick Answers