bitsofchris_openaugi-obsidian-plugin/README.md

OpenAugi

The Personal Intelligence Layer for Your Agents

OpenAugi is a context engineering layer and personal agent harness for your data (currently as an Obsidian plugin). It sits between your knowledge and your AI agents — gathering the right context, dispatching tasks, and shortcutting the loop from idea to action.

Your vault is full of plans, decisions, research, and context. OpenAugi makes that context available to agents so they can actually do useful work.

Works with the OpenAugi MCP server for semantic search, hub discovery, and structured access to your vault data. (MCP server coming soon.)

Join the Discord. Parent repo.

---

What It Does

1. Context Engineering

Gather precisely the right context from your vault — not too much, not too little.

• Link traversal — Follow wikilinks up to 3 levels deep (breadth-first)
• Backlink discovery — Find notes that reference your notes, not just notes you link to
• Journal filtering — Extract only recent sections from date-headed journal notes
• Character budgets — Stay within token limits with configurable caps
• Checkbox review — Toggle individual notes on/off before processing

2. Agent Tasks

Queue work for your agents without leaving Obsidian. The Augi commands write task files to OpenAugi/Tasks/ — the OpenAugi task watcher picks them up and runs an agent session for each.

• Augi: Run review pass — Route new blocks, refresh views, surface Dashboard nominations
• Augi: Process dashboard — Execute your nomination answers only
• Augi: Distill selection — Distill the current selection (or active note) through the distill lens
• File-based trigger — Pure vault API, no shell or HTTP, works on Obsidian Mobile with a synced vault

See Agent Tasks docs.

The older Task Dispatch feature (launching tmux sessions directly from the plugin) is deprecated in favor of the task-file flow — see Task Dispatch docs.

3. Note Processing

Turn raw notes into organized, atomic knowledge.

• Voice transcripts — Break voice notes into atomic notes + tasks + summary
• Distillation — Synthesize multiple linked notes into deduplicated atomic notes
• Publishing — Turn research notes into a single polished blog post
• Custom prompts — Apply different "lenses" to extract different insights from the same content

---

Quick Start

Setup

1. Install from Obsidian Community Plugins (or manually)
2. Settings → OpenAugi → Enter your OpenAI API key
3. For agent tasks: install OpenAugi and run openaugi up (the task watcher)

Queue an Agent Task

Run Augi: Run review pass (or Augi: Process dashboard, Augi: Distill selection) from the command palette. The plugin writes a pending task file to OpenAugi/Tasks/; the task watcher launches an agent session that does the work and writes its results back into the task file.

For Augi: Distill selection, select the text you want distilled first — the selection (or the whole active note if nothing is selected) becomes the task's context.

Gather Context

1. Open any note with links to content you want to process
2. Run Process notes
3. Configure depth, filters, and character limits
4. Review discovered notes with checkboxes
5. Choose: Distill (atomic notes), Publish (blog post), or Save (raw context)

---

Commands

Command	Purpose
Augi: Run review pass	Queue a full review pass for the task watcher
Augi: Process dashboard	Queue Dashboard nomination processing for the task watcher
Augi: Distill selection	Queue a distill of the current selection or active note
Process notes	Gather linked notes → review → distill / publish / save
Process recent activity	Same flow but discovers by recent modification date
Save context	Gather and save raw context (no AI processing)
Task dispatch: Launch or attach	Deprecated — launch agent session from task note
Task dispatch: Kill session	Deprecated — kill tmux session for current task note
Task dispatch: List active sessions	Deprecated — view and manage running agent sessions
Parse transcript	Process voice transcript into atomic notes
Distill linked notes	Legacy command — use Process notes instead

---

Agent Tasks

The Augi commands are the trigger surface for the OpenAugi agent loop. Each command writes a status: pending task file to OpenAugi/Tasks/; the task watcher (openaugi up) hydrates it, launches a Claude agent session, and the agent writes its results back into the same file.

See Agent Tasks docs for the full reference, including the task-file format.

Key concepts:

• The vault filesystem is the API — the plugin only writes a file, so the commands work on mobile with a synced vault
• The same contract is shared with the openaugi review CLI and the zzz: capture grammar
• The task file doubles as the record: results and status land back in it

Task Dispatch (deprecated)

The older agent harness: reads a task note, assembles context from linked notes, creates a tmux session, and launches your agent CLI directly from the plugin. Deprecated in favor of the task-file flow above; it keeps working for now but will be removed over a release or two. See Task Dispatch docs.

---

Context Gathering

The context gathering pipeline is a three-stage flow:

1. Configure — Source mode (linked notes or recent activity), depth, filters
2. Review — Checkbox list of discovered notes with character/token counts
3. Process — Distill to atomic notes, publish as blog post, or save raw

Features:

• Breadth-first link traversal up to 3 levels
• Bidirectional: forward links + backlinks at each depth
• Journal-style date filtering
• Dataview query support
• Custom prompt lenses

---

Configuration

Settings are in Settings → OpenAugi.

Core:

• OpenAI API key (required for AI processing)
• Output folders: Summaries, Notes, Published, Prompts

Context Gathering:

• Default link depth (1-3)
• Max characters (default: 100k)
• Include backlinks (default: on)
• Journal section filtering

Task Dispatch (deprecated):

• Terminal app (iTerm2 or Terminal.app)
• tmux path (auto-detected or manual)
• Default working directory
• Repository path mappings
• Default agent CLI
• Max context characters (default: 200k)

Recent Activity:

• Days to look back (default: 7)
• Date header format
• Folder exclusions

---

Requirements

• OpenAI API key — Required for AI processing (distill, publish, parse)
• OpenAugi task watcher — Required for the Augi agent-task commands (openaugi, run openaugi up)
• tmux — Required for deprecated task dispatch (brew install tmux)
• macOS — Deprecated task dispatch terminal opening uses AppleScript (iTerm2 or Terminal.app)

---

Get Involved

OpenAugi is about augmented intelligence — using AI to help you think faster and do more, not to think for you.

Open an issue, join the Discord, or check out YouTube for updates. Parent repo.