obsi

obsi

Agent-powered CLI for Obsidian note management following the Input → Distillation → Archival workflow.

Workflow Philosophy

obsi enforces a three-phase knowledge management workflow:

1. Input Phase — All raw materials go into input/ folder (flat structure, no subfolders)
2. Distillation Phase — Extract insights and create refined notes in distilled/
3. Archival Phase — Move processed inputs to archived/ for reference

This workflow prevents clutter, maintains organization, and ensures sustainable knowledge management over time.

Features

• Workflow-first design — Enforces Input → Distillation → Archival by default
• Hybrid engine — Uses Obsidian official CLI when running, falls back to direct file operations when not
• Smart classification — Auto-classifies notes based on content when distilling
• Agent-friendly — JSON-compatible output, stdin support, designed for AI agent workflows
• Claude Code integration — Ships as a Claude Code plugin with /obsi:note, /obsi:distill slash commands

Install

git clone https://github.com/Gitnapp/obsi.git
cd obsi
npm install
npm run build
npm link

Initialize

obsi init

Auto-detects Obsidian vaults on your machine and saves the config to ~/.obsirc.json.

To specify a vault path manually:

obsi init /path/to/your/vault

Claude Code Plugin

Add to your ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "obsi-plugins": {
      "source": {
        "source": "github",
        "repo": "Gitnapp/obsi"
      }
    }
  },
  "enabledPlugins": {
    "obsi@obsi-plugins": true
  }
}

Restart Claude Code. You'll get /obsi:note, /obsi:organize commands.

Commands

obsi init

Configure vault location.

obsi init                        # Auto-detect vault
obsi init /path/to/vault         # Manual path

Config is stored in ~/.obsirc.json:

{
  "vaultPath": "/path/to/vault",
  "para": {
    "resources": "1-Input",
    "projects": "Projects",
    "areas": "2-Distilled",
    "archive": "3-Archived"
  },
  "inbox": "1-Input",
  "daily": "Periodic",
  "knownAreas": [],
  "workflow": {
    "enforceInputFirst": true,
    "autoArchive": true
  }
}

Workflow Configuration:

• enforceInputFirst — When true, all notes go to input/ by default (recommended)
• autoArchive — When true, automatically moves processed notes to archived/ after distillation

obsi init inspects the target vault and writes the detected structure into config.

obsi note

Create a new note in the vault. By default, all notes go to input/ folder (workflow-first design).

# Default: Save to input/ folder (NEW BEHAVIOR)
obsi note "Docker Tutorial" --content "Learning docker compose..."
# → input/Docker Tutorial.md

# Bypass input phase with --distilled flag (auto-classify)
obsi note "Docker Tutorial" --content "..." --distilled
# → 2-Distilled/<auto-classified-area>/Docker Tutorial.md

# Specify target area directly (always distilled)
obsi note "Q1 Investment Review" --content "..." --area "Finance"
# → 2-Distilled/财富/Q1 投资复盘.md

# Target a project
obsi note "Auth Flow Design" --content "..." --project "MktGenie"
# → Projects/MktGenie/Auth Flow Design.md

# Save as resource
obsi note "REST API Cheatsheet" --content "..." --resource "Cheatsheets"
# → 1-Input/Cheatsheets/REST API Cheatsheet.md

# Read content from file
obsi note "Meeting Notes" --from-file ./meeting.md --area "商业"

# Pipe from stdin (useful for agents)
echo "Auto-generated content" | obsi note "Agent Output" --from-stdin

Options:

Flag	Description
-c, --content <text>	Note body text
-a, --area <name>	Target area (always distilled)
-p, --project <name>	Target project (always distilled)
-r, --resource <name>	Target resource folder
--distilled	Auto-classify to distilled/ (bypass input phase)
-t, --tags <tags>	Comma-separated tags
--from-file <path>	Read content from a file
--from-stdin	Read content from stdin
--source <source>	Source label: claude-code, web, manual, agent
--type <type>	Note type: note, research, project

obsi distill

Process notes from input/ folder to distilled/ folder.

# Interactive mode: Review pending inputs
obsi distill
# Shows all input notes with suggested classifications

# Auto-distill all input notes
obsi distill --auto
# Batch processes all notes with auto-classification

# Distill specific note
obsi distill "input/Docker Tutorial.md"
# → 2-Distilled/<auto-classified>/Docker Tutorial.md
# → Moves original to archived/

# Distill to specific area
obsi distill "input/Meeting Notes.md" --area "Business"
# → 2-Distilled/Business/Meeting Notes.md