A modular OpenCode setup for working with an Obsidian vault using a thin agent, a dedicated ingest command, and a skill-based control plane.
This repository is designed so each top-level folder can be symlinked into the appropriate global OpenCode config location.
Most of us are drowning in information but starving for wisdom. We capture bookmarks, save snippets, and record meetings, but that data usually just sits in a digital graveyard. Tiago Forte's "Second Brain" methodology offers a way out. This system relies on the CODE framework: Capture what resonates, Organize for actionability, Distill the essence, and Express your ideas. By offloading the burden of remembering everything to a structured system, you free up your biological brain for what it does best: thinking and creating. This is cognitive offloading in practice. Over time, your vault starts to gain cumulative value as old ideas connect with new ones in ways you didn't expect.
In this system, organization isn't about filing things away by topic. Instead, we use the PARA method: Projects, Areas, Resources, and Archives. This shifts the focus from "where does this belong?" to "when will I use this?" Projects are active efforts with deadlines. Areas cover ongoing responsibilities, while Resources house topics of interest for future use. Archives hold everything else. This structure ensures that the most relevant information is always at your fingertips when you're actually working. It turns a static library into a dynamic workspace.
For developers, a Second Brain is a significant advantage. This is where you keep your debugging journals. You don't just record the fix; you document the "why" behind it so you don't have to solve the same problem twice. Your personal code cookbook lives here too, filled with reusable patterns and snippets that you've actually tested. This also serves as a decision log for architectural choices that seemed obvious at the time but need context six months later. Most importantly, it makes context switching between projects less painful. When you can pull up a project dashboard that links to every relevant meeting, decision, and task, you're back in the flow in minutes instead of hours. Your vault becomes the perfect context for AI-augmented development. When your AI assistant can "read" your notes, it understands your specific patterns and constraints.
The specific problem this repository solves is the "transcript trap." We record meetings and generate high-fidelity transcripts using tools like Whisper, but those transcripts are often too noisy to be useful. They're ephemeral. Obsidian Overseer automates the process of turning that raw noise into searchable knowledge. It pulls transcripts into your vault and performs surgical filtering to remove the fluff. The system extracts structured summaries, key decisions, action items, and open questions. By using bidirectional links, it connects these insights to the right projects and people automatically. This turns a one-hour meeting into a five-minute read that actually helps you get things done.
This setup bridges the gap between your Obsidian vault and your AI assistants via OpenCode. The repository provides a modular, skill-based control plane that understands how to navigate and update your Second Brain without making a mess. We use a thin agent approach to keep things fast and predictable. Storing notes is only the beginning. Our goal is to make your knowledge actionable so you can spend less time searching and more time building.
obsidian-overseer separates Obsidian behavior into a parallel subagent architecture that optimizes performance for three distinct usage patterns:
-
agents/obsidian.mdA thin Obsidian-focused agent that delegates to the skill router. -
agents/obsidian-read.mdSpecialized agent for transcript analysis and extraction (speakers, topics, decisions, action items). -
agents/obsidian-write.mdSpecialized agent for note creation and updates with PARA-aware routing. -
agents/obsidian-ingest-orchestrator.mdCentral coordinator for parallel transcript processing with 6-phase workflow.
commands/obsidian-ingest.mdA slash command for parallel transcript ingestion into the current vault.
-
skills/obsidian/SKILL.mdMain router that dispatches tasks to appropriate agents and subagents. -
skills/obsidian/references/Reference files for specific operations:read-workflow.md- Grounded reading disciplinewrite-routing.md- Note creation and editing rulespara-routing.md- Note placement (Projects, Areas, Resources, Archives)integrity-sweep.md- Post-write safety checkstranscript-ingestion.md- Transcript processing rulestask-conventions.md- Task extraction and formattingpeople-style-profile.md- Communication style profilinglink-discovery.md- Related note suggestionsingest-orchestration.md- Parallel processing rules
The goal is to avoid one large monolithic prompt and instead load only the guidance needed for the current operation, with parallel processing for transcript ingestion.
.
├── AGENTS.md # Root project overview with architecture details
├── README.md # This file
├── agents/
│ ├── obsidian.md # Thin Obsidian agent wrapper
│ ├── obsidian-read.md # Specialized transcript analysis agent
│ ├── obsidian-write.md # Specialized note creation/update agent
│ └── obsidian-ingest-orchestrator.md # Parallel processing coordinator
├── commands/
│ └── obsidian-ingest.md # Transcript ingestion command
└── skills/
├── AGENTS.md # Skills directory coordination
└── obsidian/
├── AGENTS.md # Core Obsidian skill logic
├── SKILL.md # Main router with subagent dispatch
└── references/
├── AGENTS.md # Reference-level guidance
├── ingest-orchestration.md # Parallel processing rules
├── integrity-sweep.md
├── link-discovery.md
├── para-routing.md
├── people-style-profile.md
├── read-workflow.md
├── task-conventions.md
├── transcript-ingestion.md
└── write-routing.md
The AGENTS.md files form a hierarchical knowledge base:
./AGENTS.md: Root project overviewskills/AGENTS.md: Skill-level coordinationskills/obsidian/AGENTS.md: Obsidian-specific skill logicskills/obsidian/references/AGENTS.md: Reference-level guidance
This repo uses a parallel subagent architecture that optimizes performance for three distinct usage patterns:
| Pattern | Use Case | Subagent Overhead | Performance |
|---|---|---|---|
| General Queries | "What happened in Project Atlas?" | None (fast path) | ~2-3 seconds |
| Note Editing | "Update the Atlas project note" | Optional (complex edits only) | ~3-10 seconds |
| Transcript Ingestion | /obsidian-ingest |
Full orchestration (parallel) | 60-70% faster for 5+ transcripts |
┌─────────────────────────────────────────────────────────────────────────┐
│ USER INTERACTION LAYER │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ THIN AGENT (agents/obsidian.md) │
│ - Minimal wrapper (23 lines) │
│ - Delegates to skill │
│ - No logic duplication │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ SKILL ROUTER (skills/obsidian/SKILL.md) │
│ ┌────────────────────────────────────┐ │
│ │ Task Type Analysis │ │
│ └────────────────────────────────────┘ │
│ │ │ │ │
│ ┌───────────────┘ │ └───────────────┐ │
│ ▼ ▼ ▼ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐│
│ │ General │ │ Note │ │ Transcript ││
│ │ Query │ │ Editing │ │ Ingestion ││
│ │ (Fast Path) │ │ (Optional) │ │ (Orchestrated)││
│ └───────────────┘ └───────────────┘ └───────────────┘│
└─────────────────────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────┐ ┌───────────────────────┐
│ Read Workflow │ │ Write Route │ │ Ingest Orchestrator │
│ (Direct) │ │ (Direct or │ │ (Subagent Parallel) │
│ │ │ Subagent) │ │ │
└─────────────────┘ └─────────────┘ └───────────────────────┘
| Subagent | File | Role | Responsibilities |
|---|---|---|---|
| Read Subagent | agents/obsidian-read.md |
Transcript analysis specialist | Extract speakers, topics, decisions, action items, open questions from transcripts |
| Write Subagent | agents/obsidian-write.md |
Note creation/update specialist | Create/update meeting notes, person notes, project notes, area notes with proper PARA routing |
| Orchestrator | agents/obsidian-ingest-orchestrator.md |
Central coordinator | Manage 6-phase ingestion workflow, dispatch parallel subagents, run integrity sweeps |
| Use Case | Current | New Architecture | Improvement |
|---|---|---|---|
| General queries | Fast | Fast (unchanged) | 0% |
| Simple edits | Moderate | Moderate | 0% |
| Complex edits | Moderate | Faster | +20-30% |
| Ingestion (1 transcript) | Slow | Moderate | +30-40% |
| Ingestion (5+ transcripts) | Very slow | Fast | +60-70% |
| Batch Size | Expected Time | Notes |
|---|---|---|
| 1 transcript | 30-40s | Single subagent path |
| 5 transcripts | 45-60s | Full parallelization |
| 10 transcripts | 60-90s | Two batches of 5 |
| 20 transcripts | 2-3 min | Four batches of 5 |
- Discovery & Planning - Scan intake folders, build ingestion plan
- Parallel Read Dispatch - Dispatch Read Subagents (max 5 concurrent)
- Parallel Write Dispatch - Dispatch Write Subagents (max 5 concurrent)
- Integrity Sweep - Run integrity checks on processed notes
- Archive Source Transcripts - Move processed transcripts to archive
- Final Reporting - Generate comprehensive ingestion report
When you ask a question like "What happened in Project Atlas?", the system:
- Routes directly to
read-workflow.md - Searches the vault for relevant notes
- Reads incrementally and answers from what was actually reviewed
- No subagent overhead - completes in ~2-3 seconds
For note updates like "Update the Atlas project note with the rollout timeline":
- Routes to
write-routing.md - Simple edits: Direct processing (no subagent)
- Complex edits: Optional Write Subagent for multi-file operations
- Runs integrity sweep after changes
When you run /obsidian-ingest:
- Discovery Phase: Scan
Inbox/Transcripts/orInbox/Transcriptions/for unprocessed transcripts - Read Phase: Dispatch parallel Read Subagents (max 5 concurrent) to analyze transcripts
- Write Phase: Dispatch parallel Write Subagents (max 5 concurrent) to create/update notes
- Integrity Phase: Run integrity sweeps on processed groups
- Archive Phase: Move processed transcripts to
Archive/Transcripts/ - Reporting: Generate summary of successes, failures, and pending items
Parallel Processing Rules:
- Safe to parallelize: Reading different transcripts, writing to independent notes, integrity checks on separate groups
- Cannot parallelize: Multiple writes to the same file, writes with dependencies
- Concurrency limit: 5 subagents per operation type
- Timeout: 60s for reads, 90s for writes, 30s for integrity
Error Handling:
- Single subagent failures: Log error, continue with remaining operations
- Never rollback successful writes
- Report partial success with details for manual review
NEW: Parallel processing rules for transcript ingestion:
- Orchestrator responsibilities and 6-phase workflow
- Parallel processing rules (when to parallelize, concurrency limits)
- Synchronization points and barriers between phases
- Error handling and rollback procedures (never rollback successful writes)
- File conflict prevention strategies
- Performance expectations and batching strategies
Rules for grounded reading:
- create a read plan first
- search before loading notes
- read incrementally
- answer from notes actually reviewed
Rules for note creation and editing:
- create a write plan first
- keep changes minimal
- use
obsidian-markdownfor note-writing behavior if available
Rules for routing notes into:
Projects/Areas/Resources/Archive/Inbox/Dashboards/
Rules for post-write safety:
- repair links and embeds
- check for stale references
- propagate updates where needed
- avoid duplicate tasks or ambiguous titles
Transcript-specific interpretation and update rules:
- intake folders
- speaker identity handling
- transcript conversion to Obsidian markdown
- meeting/person/project note updates
- archive behavior after successful ingest
Task extraction and propagation rules:
- task formatting
- task placement
- deduplication logic
- ownership handling
Guidance for maintaining evidence-based communication and cognition notes for people in the vault.
Rules for discovering and suggesting related notes when manually creating new content:
- search the vault for potentially related notes
- present 3-5 suggestions with context
- auto-link only explicit connections (project, person, direct mentions)
- leave thematic/implicit connections for user to decide
This repository is intended to be used by symlinking each directory into the appropriate OpenCode global config location.
Typical pattern:
ln -s /path/to/obsidian-overseer/agents /path/to/global/config/agents
ln -s /path/to/obsidian-overseer/commands /path/to/global/config/commands
ln -s /path/to/obsidian-overseer/skills /path/to/global/config/skillsIf your OpenCode setup expects the contents rather than the folders themselves, symlink the individual files or directories instead.
Example:
ln -s /path/to/obsidian-overseer/agents/obsidian.md /path/to/global/config/agents/obsidian.md
ln -s /path/to/obsidian-overseer/commands/obsidian-ingest.md /path/to/global/config/commands/obsidian-ingest.md
ln -s /path/to/obsidian-overseer/skills /path/to/global/config/skills/obsidianAdjust the destination paths to match your environment.
Ask normally through the Obsidian agent or any agent that can access the Obsidian skill.
Examples:
- "Find the latest notes about Project Atlas and summarize open questions."
- "What recent meetings mention the migration plan?"
Ask for the change normally.
Examples:
- "Update the Atlas project note with the rollout timeline."
- "Add these action items to the meeting note and related project page."
Run:
/obsidian-ingest
This is the explicit entrypoint for processing transcripts from the vault intake area.
This repo works best with these optional companion skills installed:
Purpose: Specialized markdown formatting for Obsidian notes (wikilinks, embeds, callouts, properties).
Installation: https://github.com/kepano/obsidian-skills/tree/main/skills/obsidian-markdown
Benefit: When available, write-routing.md directs note-writing and note-editing tasks to this skill so markdown formatting rules are not duplicated here. This keeps obsidian-overseer focused on vault behavior, routing, note placement, integrity, and transcript handling, while leaving markdown authoring to the specialist skill.
Purpose: Remove AI-writing patterns from text to make it sound more natural and human-written.
Installation: https://github.com/blader/humanizer
Benefit: Used for final user-facing responses to ensure natural-sounding communication that doesn't reveal AI-generated writing patterns.
Note: Both skills are optional. The core functionality works fine without them, but installing these skills significantly improves the quality of output.
This repo favors:
- grounded answers over memory
- planning before reading or writing
- small, reversible changes
- minimal duplication
- idempotent repeated runs
- conservative handling of ambiguous identities, links, and routing
- automatic link discovery for manual note creation
- Transcript intake may use either
Inbox/Transcripts/orInbox/Transcriptions/, depending on vault convention. - PARA routing defaults are conservative and try to avoid creating new top-level structures unnecessarily.
- If speaker identity or routing is ambiguous, the system should prefer conservative handling rather than confident guessing.
