Obsidian Agent

Terminal AI agent for Obsidian vaults on Windows. The tool runs manually from CLI, reads and writes Markdown files directly in your vault, and uses a semi-autopilot workflow by default (plan + diff preview before apply).

What it does

• init: creates .obsidian-agent/ with config, templates, backups folder, and index file.
• scan / index: builds .obsidian-agent/index.json with note metadata (path, title, aliases, tags, type).
• topic: creates or expands topic notes with structure, YAML Properties, tags, and wiki-links.
• ingest-text: extracts key points/facts/entities/tasks from raw text and proposes note updates.
• inbox-add: stores text in Inbox/ without LLM.
• inbox-process: classifies inbox notes, proposes filing plan, updates/creates notes, and can archive inbox items.
• Safety model:
  • dry-run by default (--dry-run)
  • apply only with --apply
  • backups before write/delete/move in .obsidian-agent/backups/<timestamp>/
  • max changed files per run (max_files, overridable by --max-files)

Architecture

• Python 3.11+
• src layout
• Typed core modules:
  • config (Pydantic config loading/validation)
  • vault (safe paths, read/write, backup, diff)
  • frontmatter (YAML parse/update)
  • index (vault indexing and relevant note lookup)
  • llm (OpenAI-compatible Chat Completions client)
  • planner (strict JSON plan generation)
  • executor (plan validation, dry-run, apply)
  • cli (Typer + Rich terminal UI)

Installation

pip

pip install -e .

pipx

pipx install .

Poetry

poetry install
poetry run obsidian-agent --help

Quick start

obsidian-agent init --vault "C:\Vault"
obsidian-agent scan --vault "C:\Vault"
obsidian-agent topic "Теория вероятностей" --vault "C:\Vault" --apply

Semi-autopilot default behavior:

obsidian-agent topic "Bayes theorem" --vault "C:\Vault"

This shows plan + diff only (no write). Add --apply to commit changes.

CLI examples

obsidian-agent init --vault "C:\Vault"
obsidian-agent scan --vault "C:\Vault"
obsidian-agent topic "Knowledge graphs" --vault "C:\Vault" --apply
obsidian-agent ingest-text --vault "C:\Vault" --apply
obsidian-agent inbox-add --vault "C:\Vault" --title "Raw idea" --text "..." --apply
obsidian-agent inbox-process --vault "C:\Vault" --apply

ingest-text can read stdin:

type input.txt | obsidian-agent ingest-text --vault "C:\Vault" --apply

Configuration

Generated on init at: .obsidian-agent/config.yaml

Example:

vault_path: "C:/Vault"
language: auto
mode: semi
max_files: 20
llm:
  base_url: "https://api.openai.com/v1"
  model: "gpt-4o-mini"
  api_key: null
  timeout: 60.0
folders:
  inbox: Inbox
  notes: Notes
  projects: Projects
  people: People
  companies: Companies
  meetings: Meetings
  daily: Daily
  resources: Resources
  archive: Archive
note_rules:
  required_properties:
    - title
    - type
    - tags
    - aliases
    - created
    - updated
    - source
  type_to_folder:
    concept: Notes
    project: Projects
    person: People
    company: Companies
    meeting: Meetings
    daily: Daily
    reference: Resources
    inbox: Inbox
  type_to_template:
    concept: concept.md
    project: project.md
    person: person.md
    company: company.md
    meeting: meeting.md
    daily: daily.md
    reference: reference.md
    inbox: inbox.md

Runtime overrides:

• --vault PATH
• --config PATH
• --dry-run/--apply
• --language ru|en|auto
• --mode draft|semi|auto
• --max-files N
• --model MODEL
• --base-url URL
• --api-key KEY or env OBSIDIAN_AGENT_API_KEY

Local models via OpenAI-compatible base_url

You can point to any OpenAI-compatible server:

• Ollama gateway
• LM Studio server
• local/proxy OpenAI-compatible endpoints

Example:

obsidian-agent topic "Distributed systems" \
  --vault "C:\Vault" \
  --base-url "http://127.0.0.1:1234/v1" \
  --model "local-model" \
  --apply

Templates

Default templates are created in:

• .obsidian-agent/templates/concept.md
• .obsidian-agent/templates/project.md
• .obsidian-agent/templates/person.md
• .obsidian-agent/templates/company.md
• .obsidian-agent/templates/meeting.md
• .obsidian-agent/templates/daily.md
• .obsidian-agent/templates/reference.md
• .obsidian-agent/templates/inbox.md

Templates support placeholders like {{title}}, {{date}}, {{source}}.

Semi-autopilot and backups

• In semi mode, commands produce a strict JSON plan and unified diffs.
• Without --apply, nothing is written.
• With --apply, changed source files are backed up first.
• Markdown outputs are normalized with YAML frontmatter and required properties.

Security notes

• Do not store API keys in git.
• Prefer env var OBSIDIAN_AGENT_API_KEY.
• See SECURITY.md for details on what context is sent to LLM.

Limitations

• LLM quality depends on the selected model and prompt adherence.
• JSON-only planner contract may still fail on weak local models.
• Inbox processing behavior is prompt-driven; review diffs before applying.

Roadmap

• Better local NLP fallback for no-LLM mode
• Smarter entity resolution and link suggestion ranking
• Optional plugin bridge for richer Obsidian metadata (without replacing CLI)
• Optional integrations with external systems (mail/calendar/messengers) after MVP

Development

pip install -e .[dev]
ruff check .
ruff format --check .
pytest

Contacts

• Email: karsakovillya@yandex.ru
• Telegram: @nicto999