Agentic Copilot

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

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

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

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

Commands

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

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

Configuration

Open Settings → Agentic Copilot:

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

FAQ

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.

_{If Agentic Copilot is useful to you, consider giving it a star on GitHub — it helps others discover the project.}