obsidian-ai

Bring agentic CLI tools into Obsidian as a workspace copilot. Claude Code • Opencode • Gemini CLI • Any custom agent

= 1.5.0" />

Agentic Copilot is a thin orchestration layer that connects Obsidian to whatever agentic coding tool you already use. It doesn't reinvent the wheel — it gives the wheel a steering column inside your knowledge base. Auto-detects your environment. Zero configuration required.

Table of Contents

• Why Agentic Copilot?
• Quickstart
• Features
• Supported Agents
• Commands
• Configuration
• How It Works
• Development
• Troubleshooting
• FAQ
• Contributing
• License

---

Why Agentic Copilot?

Most AI plugins ship their own LLM integration, locking you into a specific provider and model. Agentic Copilot takes a different approach: it connects to the CLI tools you already have installed — tools that handle auth, model selection, context windows, and tool use on their own.

You (Obsidian) <-> Agentic Copilot <-> CLI Agent <-> LLM Provider
                   ~~~~~~~~~~~~~~~
                   (this plugin)

What you get:

• Use the same agent, same config, same API keys as your terminal workflow
• Every improvement to Claude Code / Opencode / Gemini CLI lands in Obsidian automatically
• Swap agents with a single command — no settings migration, no API key juggling
• Your data never touches an intermediary — it flows directly from plugin to your local CLI tool

---

Quickstart

1. Install a CLI agent

# Claude Code (recommended)
npm install -g @anthropic-ai/claude-code

# — or —

# Opencode
curl -fsSL https://opencode.ai/install | bash

2. Install the plugin

Method	Steps
Community Plugins	Settings → Community Plugins → Browse → search "Agentic Copilot" → Install → Enable
BRAT (beta/pre-release)	Install BRAT → Add beta plugin → enter spencermarx/obsidian-ai
Manual	Download main.js, manifest.json, styles.css from the latest release into <vault>/.obsidian/plugins/agentic-copilot/ → restart Obsidian → enable

3. Open the chat panel

Click the bot icon in the ribbon, or run Ctrl/Cmd+P → "Agentic Copilot: Open chat panel".

That's it. The plugin auto-detects your agent and you're ready to go.

---

Features

💬 Chat Panel

A conversational side panel that streams agent responses in real-time, rendered with Obsidian's native markdown engine — links, code blocks, and themes all just work.

📎 Vault-Aware Context

Every prompt automatically includes your active file, text selection, and vault path so the agent knows what you're looking at. Fully configurable in settings.

⚡ Slash Commands

Type / in the chat input to autocomplete agent-native commands — /commit, /compact, /review-pr, /help, and more. Commands come directly from the connected CLI tool.

📝 File Edit Diffs

When the agent suggests file changes, they appear as inline diffs with Accept / Reject buttons. No changes are applied without your confirmation (unless you enable auto-apply).

🪟 Multi-Session

Open multiple independent chat panels, each with its own agent session. Use different agents in different panels, or run parallel conversations with the same one.

✏️ Editor Integration

Select text in any file, then:

• Right-click → Ask Agent — send the selection as a prompt
• Right-click → Explain Selection — get an explanation
• Command palette — Explain, Refactor, Ask about file, Run slash command

🔍 Multi-Agent Auto-Detection

On load, the plugin scans your PATH for known CLI tools and presents the first one found. Switch agents anytime via the command palette or settings.

---

Supported Agents

Agent	Binary	Output Mode	Status
Claude Code	claude	--output-format stream-json (structured streaming)	✅ Full support
Opencode	opencode	run mode (text/JSON)	✅ Full support
Custom	any	stdin/stdout pipes	✅ Generic adapter
Gemini CLI	gemini	—	🚧 Planned

Want to add your agent? See Adding a New Agent — it's a single file.

---

Commands

Open with Ctrl/Cmd+P (command palette):

Command	Description
Open chat panel	Open or focus the chat sidebar
Open new chat session	Open an additional chat panel (multi-session)
Ask agent about current file	Send the active file to the agent
Ask agent about selection	Send selected text to the agent
Explain selection	Ask the agent to explain selected text
Refactor selection	Ask the agent to refactor selected code
Run agent slash command	Fuzzy-search and execute an agent slash command
Restart agent session	Kill and restart the current session
Switch agent	Switch between detected CLI agents

All commands are prefixed with Agentic Copilot: in the command palette.

---

Configuration

Open Settings → Agentic Copilot:

Agent Settings

Setting	Description	Default
Agent	Which CLI tool to use (Auto-detect, specific agent, or Custom)	Auto-detect
Custom binary path	Full path or command name for a custom CLI agent	—
Extra CLI arguments	Additional args appended to every invocation (e.g., --model opus)	—

Context Settings

Setting	Description	Default
Working directory	Agent's cwd: vault root or active file's parent directory	Vault root
Include active file	Auto-include the active file's content in every prompt	On
Include selection	Auto-include the current text selection in every prompt	On

Session Settings

Setting	Description	Default
Max concurrent sessions	Maximum simultaneous agent sessions	5

Advanced Settings

Setting	Description	Default
Auto-apply file edits	Apply agent-suggested edits without confirmation. Use with caution.	Off

---

How It Works

Architecture

┌────────────────────────────────────────┐
│            Obsidian Plugin             │
│                                        │
│  ┌──────────┐    ┌──────────────────┐  │
│  │Chat View │    │ Editor Actions   │  │
│  │(ItemView)│    │ (context menu,   │  │
│  │          │    │  command palette) │  │
│  └────┬─────┘    └───────┬──────────┘  │
│       │                  │             │
│  ┌────▼──────────────────▼──────────┐  │
│  │       Session Manager            │  │
│  │  (spawn, lifecycle, streaming)   │  │
│  └──────────────┬───────────────────┘  │
│                 │                      │
│  ┌──────────────▼───────────────────┐  │
│  │       Adapter Layer              │  │
│  │  ┌──────────┐ ┌────────┐        │  │
│  │  │Claude    │ │Opencode│ ┌────┐ │  │
│  │  │Code      │ │        │ │Any │ │  │
│  │  │(stream-  │ │(run    │ │CLI │ │  │
│  │  │ json)    │ │ mode)  │ │    │ │  │
│  │  └──────────┘ └────────┘ └────┘ │  │
│  └──────────────────────────────────┘  │
└────────────────┬───────────────────────┘
                 │ child_process.spawn()
                 ▼
          ┌─────────────┐
          │  CLI Agent   │
          │  (your tool) │
          └──────┬──────┘
                 │ API calls
                 ▼
          ┌─────────────┐
          │ LLM Provider │
          └─────────────┘

Why child_process.spawn (not node-pty)?

node-pty requires native compilation per platform — impractical for an Obsidian plugin that must install without a build step. Instead, we use Node.js child_process.spawn with piped stdio, and rely on structured output modes (e.g., Claude Code's --output-format stream-json) for rich, parseable data.

Trade-off: no full TTY emulation. Benefit: zero native dependencies, instant cross-platform install.

Adding a New Agent

Implement the AgentAdapter interface in src/adapters/:

interface AgentAdapter {
  readonly id: string;            // unique identifier
  readonly displayName: string;   // shown in UI
  readonly binaryName: string;    // CLI binary name

  detect(): Promise<boolean>;     // is it installed?
  getVersion(): Promise<string | null>;

  buildSpawnArgs(opts: {
    prompt: string;
    context: VaultContext;
    cwd: string;
  }): SpawnArgs;

  parseOutputStream(stdout: Readable): AsyncIterable<AgentMessage>;

  getSlashCommands(cwd?: string): Promise<SlashCommand[]>;
  getBuiltinSlashCommands(): SlashCommand[];
  executeSlashCommand(command: string, args: string): Promise<SlashCommandResult>;
}

Then register it in src/adapters/detector.ts:

const ADAPTER_CONSTRUCTORS: Array<() => AgentAdapter> = [
  () => new ClaudeCodeAdapter(),
  () => new OpencodeAdapter(),
  () => new YourNewAdapter(),  // <-- add here
];

That's it. Detection, settings UI, and chat panel all pick it up automatically.

---

Development

Prerequisites

• Node.js >= 18
• An Obsidian vault for testing

Setup

git clone https://github.com/spencermarx/obsidian-ai.git
cd obsidian-ai
npm install

Dev Mode

npm run dev

Watches src/ and rebuilds main.js on every change. Symlink into a test vault:

# macOS / Linux
ln -s "$(pwd)" "/path/to/vault/.obsidian/plugins/agentic-copilot"

# Windows (PowerShell, as admin)
New-Item -ItemType SymbolicLink -Path "C:\path\to\vault\.obsidian\plugins\agentic-copilot" -Target "$(Get-Location)"

Then reload Obsidian (Ctrl/Cmd+R) to pick up changes.

Production Build

npm run build

Releasing