obsidian-axi

AXI-compliant Obsidian CLI wrapper — token-efficient TOON output for AI agents.

obsidian-axi wraps the Obsidian CLI with the AXI (Agent eXperience Interface) design principles — structured, token-efficient TOON output that AI agents love.

Why AXI?

Benchmarks show AXI-compliant tools outperform both raw CLI and MCP:

| Condition | Success | Avg Cost | Avg Duration | Avg Turns | |-----------|---------|----------|-------------|-----------| | gh-axi (AXI) | 100% | $0.050 | 15.7s | 3 | | gh CLI (raw) | 86% | $0.054 | 17.4s | 3 | | GitHub MCP | 87% | $0.148 | 34.2s | 6 | | GitHub MCP + Code | 84% | $0.101 | 43.4s | 7 |

The same principles apply to Obsidian: agents get leaner output, contextual suggestions, and discover faster with fewer turns.

Commands

| Command | Description | |---------|-------------| | obsidian-axi | Dashboard — vault info, tasks, tags | | obsidian-axi search <query> | Search vault with TOON results | | obsidian-axi note list [folder] | List notes | | obsidian-axi note view <path> | Read a note (truncated, --full for complete) | | obsidian-axi note create --title <name> | Create a note | | obsidian-axi backlinks <path> | Show incoming references | | obsidian-axi tags | List tags with counts | | obsidian-axi tasks | List open tasks | | obsidian-axi daily read\|path\|append | Daily note operations | | obsidian-axi graph <path> | Show outgoing links | | obsidian-axi vault | Vault info |

Installation

npm install -g obsidian-axi

Prerequisites:

• Obsidian installed and the obsidian CLI on your PATH
• Obsidian app running with your vault open

Session hooks (Claude Code, Codex, OpenCode)

obsidian-axi setup hooks

Agent Skill

npx skills add HermitCountry/obsidian-axi --skill obsidian-axi

Example Usage

# Dashboard
$ obsidian-axi
bin: ~/.local/bin/obsidian-axi
description: Token-efficient Obsidian CLI wrapper for AI agents
vault: VALIS
files: 342
tasks: 3 todo (15 total)
tags: 47
help[4]:
  Run `obsidian-axi search <query>` to search vault
  Run `obsidian-axi note view <path>` to read a note
  Run `obsidian-axi tasks` to see open tasks
  Run `obsidian-axi tags` to explore tags

# Search
$ obsidian-axi search "machine learning"
count: 12
results[12]{file,matches}:
  Research/ML/index.md,4 matches
  Projects/Model Training/log.md,2 matches
help[1]:
  Run `obsidian-axi note view Research/ML/index.md` to read a result

# Backlinks
$ obsidian-axi backlinks "Meta/Open Items.md"
backlinks[3]{file,links}:
  Projects/obsidian-axi/index.md,1 link
help[1]:
  Run `obsidian-axi note view Meta/Open Items.md` to read a linked note

Design Principles

This tool follows the 10 AXI principles:

1. Token-efficient output — TOON format saves ~40% tokens over JSON
2. Minimal default schemas — 3-4 fields per item
3. Content truncation — note bodies truncated with --full escape hatch
4. Pre-computed aggregates — counts upfront, no round trips
5. Definitive empty states — explicit "0 results"
6. Structured errors — errors on stdout, idempotent mutations, no prompts
7. Ambient context — session hooks for Claude Code, Codex, OpenCode
8. Content first — obsidian-axi with no args shows live dashboard
9. Contextual disclosure — next-step suggestions after every output
10. Consistent help — per-subcommand --help with examples

Development

git clone https://github.com/HermitCountry/obsidian-axi
cd obsidian-axi
npm install
npm run build
npm test

Test suite

| Layer | What it covers | Runs in CI | |-------|---------------|------------| | Unit | Field extraction, TOON formatting, suggestions table | ✅ Always | | Integration | Mock Obsidian CLI → command output | ✅ Always | | E2E | Real Obsidian CLI, live vault journeys | 🔶 Opt-in (CI_E2E=true) |

Contributing

PRs welcome! See CONTRIBUTING.md.

License

MIT — see LICENSE.

Related

• AXI — Agent eXperience Interface
• gh-axi — AXI-compliant GitHub CLI
• axi-sdk-js — AXI SDK for Node.js