A Rust CLI tool for managing Bear notes on macOS. Designed for AI agent integration with structured JSON output.
- π Read & Search β Full-text search with OCR support for attachments
- βοΈ Create & Edit β Create, replace, append, prepend note content
- π·οΈ Tag Management β List tags as tree, add/rename/delete tags, find untagged notes
- π Backlinks β Find notes that link to a given note
- π Statistics β Note counts, tag distribution, monthly trends
- π¦ Batch Operations β Bulk tag and archive
- π€ Export β Export notes as Markdown with YAML frontmatter
- π Safe β Reads from SQLite directly, writes through Bear's official API
- π€ Agent-friendly β JSON output, designed for AI tool integration
Important: The CLI tool must be installed before using any AI agent integration.
Download the latest release for your Mac:
# Apple Silicon (M1/M2/M3/M4)
curl -L https://github.com/xxieen/bearclaw/releases/latest/download/bearclaw-aarch64-apple-darwin.tar.gz | tar xz
sudo mv bearclaw /usr/local/bin/
# Intel Mac
curl -L https://github.com/xxieen/bearclaw/releases/latest/download/bearclaw-x86_64-apple-darwin.tar.gz | tar xz
sudo mv bearclaw /usr/local/bin/cargo install bearclawgit clone https://github.com/xxieen/bearclaw.git
cd bearclaw
cargo install --path .bearclaw health- macOS (Bear is macOS/iOS only)
- Bear installed and running (for write operations)
# Check everything is working
bearclaw health
# Search notes
bearclaw search "rust programming"
# Read a specific note
bearclaw read <note-id>
# Create a note
bearclaw create --title "My Note" --body "Hello world" --tags "test,demo"
# View statistics
bearclaw stats| Command | Description |
|---|---|
bearclaw read <id-or-title> |
Read a note's full content |
bearclaw search <query> |
Search notes (--ocr, --tag, --since, --before, --limit) |
bearclaw create --title "x" --body "y" |
Create a new note (--tags, --body-file) |
bearclaw edit <id> --body "x" |
Replace note body (--body-file) |
bearclaw append <id> --text "x" |
Append text (--header, --text-file) |
bearclaw prepend <id> --text "x" |
Prepend text (--text-file) |
bearclaw section <id> --header "x" |
Extract a section by header |
bearclaw trash <id> |
Move note to trash |
bearclaw archive <id> |
Archive a note |
| Command | Description |
|---|---|
bearclaw tag list |
List all tags as hierarchical tree |
bearclaw tag add <id> --tags "a,b" |
Add tags to a note |
bearclaw tag rename <old> <new> |
Rename a tag |
bearclaw tag delete <name> |
Delete a tag |
bearclaw untagged |
List notes without tags |
| Command | Description |
|---|---|
bearclaw backlinks <id-or-title> |
Find notes linking to this note |
bearclaw stats |
Show statistics |
| Command | Description |
|---|---|
bearclaw batch tag --filter "q" --tags "a,b" |
Bulk add tags |
bearclaw batch archive --filter "q" |
Bulk archive |
bearclaw export --output ./dir/ |
Export as Markdown (--tag, --since, --before) |
| Command | Description |
|---|---|
bearclaw health |
Check Bear installation and database status |
| Option | Description |
|---|---|
--pretty |
Pretty-print JSON output |
--db-path <path> |
Custom database path (or BEAR_DB_PATH env var) |
All commands return structured JSON:
// Success
{"ok": true, "data": {...}, "count": 10}
// Error
{"ok": false, "error": "Note not found", "code": "NOT_FOUND"}Bearclaw is designed to work with any AI coding agent. Below are setup guides for popular agents.
Prerequisite: Install the
bearclawCLI first (see Installation above).
Install the bundled skill directly from this repository:
amp skill add xxieen/bearclaw/bearThe skill will be loaded automatically when you ask about Bear notes. First-time use will check if bearclaw is installed.
Copy the .claude/skills/bear/ directory from this repository into your project:
# Clone and copy the skill
git clone https://github.com/xxieen/bearclaw.git /tmp/bearclaw
cp -r /tmp/bearclaw/.claude/skills/bear .claude/skills/
rm -rf /tmp/bearclawOr manually create .claude/skills/bear/SKILL.md in your project. The skill will be available as /bear in Claude Code.
- Reads: Direct SQLite access (fast, no Bear app needed)
- Writes: Bear's official
x-callback-urlAPI (safe, requires Bear running) - Output: JSON to stdout for agent consumption
MIT