agentNote

agentNote

Share local Obsidian notes and files with AI agents through a private, local-only HTTP service.

中文说明：README.zh-CN.md

agentNote is an Obsidian desktop plugin that connects your vault with agents such as Claude Code, Codex, and WorkBuddy. Share selected material through a local URL and let an agent write its work back to your vault.

Features

• Share a note, file, folder, or selected text with an agent.
• Include background context so the agent understands what the shared material is and why it matters.
• Let an agent create and update Markdown notes in your vault through natural language.
• Keep share links live: updated files resolve to their latest content.
• Show Claude Code, Codex, and WorkBuddy in the connection panel even when they are not installed.
• Connect another agent through the same installation task used by the three presets.
• Explore a local knowledge profile with reuse rankings, contribution history, activity, and archive suggestions.
• Generate a privacy-aware PNG of all-time knowledge contributions for sharing.
• Open a note directly from its title in the knowledge profile, and review its local activity history.
• Keep immutable, per-day cold copies of past activity logs, either automatically or on demand.

Start in 3 minutes

Read the illustrated How to Use guide for the complete first workflow. The short version is:

1. Open the agentNote connection panel and confirm that the local service is running.
2. Select 接入, send the copied installation task to an agent, and wait for it to report its installed Skill path.
3. Right-click a vault file or folder, choose agentNote: Share with agent, and paste the copied link into the conversation.
4. Ask the connected agent to read the link, or simply say “Write this to Obsidian.”

Installation

From the Obsidian Community Plugins directory

1. Open Settings → Community plugins in Obsidian.
2. Search for agentNote.
3. Install and enable the plugin.
4. Open the agentNote connection panel and confirm that the local service is running.

Manual installation

1. Download main.js, manifest.json, and styles.css from the latest GitHub release.
2. Create .obsidian/plugins/agentnote/ inside your vault.
3. Copy the three files into that folder.
4. Restart Obsidian or reload the plugin from Settings → Community plugins.

Basic usage

Share content with an agent

• Right-click a file or folder and choose agentNote: Share with agent.
• Select multiple files or folders in the file explorer, then choose agentNote: Share selected items with agent. The clipboard contains title-labeled links separated by horizontal rules, ready to paste together.
• Select text in the editor and use agentNote: Share selected content.
• Send the copied local URL to your agent.

The response includes the current content, its background, and the local file path. Read through the link; update shared content through the share API.

Write notes from an agent

After connecting an agent, say one of the following:

• “Write this to Obsidian.”
• “Save this to my agent notes.”
• “Remember this in my notes.”

The agentNote skill asks the agent to create a title, body, background, and tags, then write the result to the vault. The agent receives a permanent local link that can be used for later updates.

Connect an agent

Open the agentNote connection panel. Claude Code, Codex, and WorkBuddy always appear; use 接入其他 Agent for another agent. Every entry copies the same task: the agent downloads the local SKILL.md, sets up its fixed identity, and reports its actual installation path. Once registered, you can preview and edit that local Skill or add instructions specific to the agent.

Local service and privacy

• The service listens on 127.0.0.1 by default, usually at http://127.0.0.1:27182.
• It is available only while Obsidian is running.
• Vault contents are not uploaded to agentNote's servers.
• There is no account, cloud sync, telemetry service, or public sharing layer.
• The plugin uses local filesystem access and the system clipboard for its sharing and agent integration features.
• This is a desktop-only plugin because it uses Node.js, Electron, and a local HTTP server.

Documentation

The reusable Xiaoji character, mark, logo, visual identity guide, and three usage illustrations are in the brand asset kit.

For device-specific activity logs, see Git activity sync. Each device appends to its own log; statistics merge all device logs. This does not resolve conflicts in note contents or other shared state.

Development

npm ci
npm test

The build produces the Obsidian plugin bundle in main.js and the Node-compatible core test bundle in test/core-bundle.cjs.

Development commands support macOS, Windows, and Linux. npm test runs type checking, builds, and core end-to-end tests without deploying to a vault. Use npm run dev to watch for changes and rebuild.

To deploy to a local test vault, specify an existing directory (quote paths containing spaces):

npm run deploy:test -- "/absolute/path/to/test-vault"

Use Node.js 22 or newer for development. Alternatively, save AGENTNOTE_TEST_VAULT="/absolute/path/to/test-vault" in .env.local at the project root, then run npm run deploy:test. Git ignores this local file. A command-line path takes precedence over environment variables, and existing environment variables take precedence over .env.local. Append --dry-run to check the destination without writing files.

The default configuration directory is .obsidian; append --config-dir .obsidian-test for a custom directory. Deployment overwrites the three agentNote plugin files there. Reload the plugin in Obsidian afterward.

License

agentNote is released under the MIT License.

Author

Evan · GitHub