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:
| 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) | — |
| 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 |
| Setting | Description | Default |
|---|
| Max concurrent sessions | Maximum simultaneous agent sessions | 5 |
| 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
# 1. Bump version
npm version patch # 1.0.0 → 1.0.1 (or: minor, major)
# 2. Push the tag — triggers the release workflow
git push --follow-tags
GitHub Actions builds the plugin and creates a release with main.js, manifest.json, styles.css, and a zip archive.
Note: Release tags must be bare version numbers (1.0.1), not prefixed with v. This is required by both BRAT and the Obsidian community plugin system.
Project Structure
src/
├── main.ts # Plugin entry: onload, commands, views
├── constants.ts # Settings interface, view type IDs
├── settings.ts # PluginSettingTab implementation
├── adapters/
│ ├── types.ts # AgentAdapter interface
│ ├── claude-code.ts # Claude Code adapter
│ ├── opencode.ts # Opencode adapter
│ ├── generic-cli.ts # Generic fallback adapter
│ └── detector.ts # Auto-detection logic
├── session/
│ ├── session-manager.ts # Process lifecycle management
│ └── message-queue.ts # Stream buffering
├── views/
│ ├── chat-view.ts # Main chat panel (ItemView)
│ ├── chat-renderer.ts # Markdown + tool-use rendering
│ └── onboarding-view.ts # First-run setup
└── utils/
├── vault-context.ts # Vault/file/selection context
└── platform.ts # Cross-platform utilities
Troubleshooting
The plugin couldn't find any known CLI binaries on your PATH.
- Verify installation — open a terminal and run
claude --version or opencode version
- Check PATH — Obsidian inherits the system PATH. If you installed via a version manager (nvm, fnm, mise), ensure the binary is on the default PATH
- Use a custom binary path — Settings → Agentic Copilot → set Agent to "Custom" → enter the full path (e.g.,
/Users/you/.nvm/versions/node/v20/bin/claude)
- Restart Obsidian — detection runs on plugin load
- Click the Stop button to kill the process
- Use
Agentic Copilot: Restart agent session from the command palette
- Verify the CLI works standalone:
claude -p "hello" should produce output
- Temporarily clear any custom CLI args in settings to rule out conflicts
The CLI tool crashed. Common causes:
- Missing API key — most agents need an env var (e.g.,
ANTHROPIC_API_KEY). Set it in your shell profile so Obsidian inherits it
- Rate limiting — you've exceeded the provider's rate limit. Wait and retry
- Network error — check your internet connection
This plugin is desktop only. It requires Node.js child_process to spawn CLI tools, which is only available in Obsidian's Electron environment.
The plugin uses Obsidian's CSS variables for all styling. If something looks off:
- Try switching themes to confirm it's not a theme-specific issue
- File an issue with your theme name and a screenshot
FAQ
No. The plugin itself sends nothing externally. It passes context to your locally-installed CLI agent, which then communicates with its configured LLM provider. Your data flows through the same path it would if you ran the CLI tool directly in a terminal.
No. The plugin requires Node.js child_process to spawn CLI tools, which is only available on desktop (Electron).
The plugin auto-detects both. By default it uses the first one found (Claude Code takes priority). You can switch anytime via Settings or the Switch agent command.
Yes. Set Agent to "Custom" in settings and enter the binary name or full path. The plugin will pipe your prompt as a CLI argument and read stdout as the response.
The plugin passes the vault path as the working directory, and optionally the active file's content and your text selection. The CLI agent can then read files within that directory as it normally would — same access as running it from a terminal in your vault folder.
If installed via Community Plugins or BRAT, updates are automatic. For manual installs, download the latest release files and replace the old ones.
Contributing
Contributions are welcome! Here's how to get involved:
- Add a new agent adapter — the most impactful contribution. See Adding a New Agent
- Report bugs — open an issue with reproduction steps
- Request features — open an issue describing your use case
- Submit a PR — fork, branch, and open a pull request. All PRs are welcome
Please read the Code of Conduct before contributing.
Acknowledgements
Built with the Obsidian Plugin API. Inspired by the growing ecosystem of agentic coding tools and the Obsidian community's relentless drive to connect everything.
License
MIT — use it, fork it, ship it.
@spencermarx