Obsidian Plugin

DorkOS runs as a sidebar plugin inside Obsidian — your coding agent available directly inside your thinking environment, with no context switch to a terminal.

What You Get

• Active file tracking — the currently open file is automatically included as context
• Drag-and-drop — drag files from Obsidian's file explorer into the chat
• File navigation — click file references in chat to open them in Obsidian
• Vault-aware sessions — working directory is automatically set to your vault's parent (repository root)
• Theme integration — adapts to your Obsidian light/dark theme

Requirements

• Obsidian Desktop — the plugin requires Obsidian's Electron desktop app. Mobile is not supported.
• Claude Code CLI — install globally:

npm install -g @anthropic-ai/claude-code

Verify:

claude --version

Installation

The plugin is currently in development and requires manual installation.

1. Build the plugin from the DorkOS monorepo root:

turbo run build --filter=@dorkos/obsidian-plugin

This outputs three files to apps/obsidian-plugin/dist/:

• main.js — the plugin code
• styles.css — plugin styles
• manifest.json — plugin metadata

2. Symlink the dist directory into your vault's plugins folder:

# From your vault directory
cd .obsidian/plugins
ln -s /path/to/dorkos/apps/obsidian-plugin/dist dorkos-copilot

On Windows:

mklink /D dorkos-copilot C:\path\to\dorkos\apps\obsidian-plugin\dist

3. Restart Obsidian (or reload with Ctrl/Cmd + R)

4. Enable the plugin — Settings → Community Plugins → find "DorkOS Copilot" → toggle on

Future

The plugin will eventually be published to Obsidian's Community Plugin directory for one-click installation.

Configuration

API Key

The plugin uses the Claude Code CLI, so it needs the same API key:

export ANTHROPIC_API_KEY="your-api-key-here"

Add this to your shell profile (~/.zshrc, ~/.bashrc, etc.) to persist across sessions.

Important: Obsidian must be launched from a context where this environment variable is available. Launching from macOS Spotlight or Windows Start Menu may not inherit your shell environment.

Working Directory

The plugin sets the working directory to your vault's parent directory (repository root). This assumes your vault lives inside a Git repository:

my-project/           ← Working directory (repo root)
├── .claude/
│   └── commands/     ← Slash commands
├── workspace/        ← Your Obsidian vault
│   ├── .obsidian/
│   └── notes/
└── .git/

This gives DorkOS access to your slash commands, full repository context, and Git operations.

Usage

Opening the Sidebar

Three ways to open the copilot:

1. Ribbon icon — click the robot icon in the left sidebar
2. Command palette — Ctrl/Cmd + P → "Open Copilot"
3. Custom hotkey — assign one in Settings → Hotkeys

The copilot opens in the right sidebar as a panel.

Adding Context

Active File (Automatic)

The currently open file is automatically tracked and shown as a context chip above the chat input. It updates as you switch files.

Drag-and-Drop (Manual)

Drag files from Obsidian's file explorer into the chat area. The drop zone highlights when you drag over it. Manually added context chips persist until you remove them with the "x" button.

Both the active file and any manually added files are included when you send a message.

Opening Files from Chat

Click file paths in Claude's responses to open them in the Obsidian editor.

Session Management

The session list shows all your chat sessions — including those started from the CLI or standalone web interface. Sessions persist in ~/.claude/projects/{slug}/ and cannot be deleted from the UI.

How It Differs from Standalone Mode

The plugin uses DirectTransport — services run in-process inside Obsidian's Electron environment with no HTTP or SSE. This is what makes the plugin fast and what makes standard Node.js module patterns require adaptation for Electron.

Build Architecture

The plugin builds via Vite lib mode targeting CommonJS for Electron compatibility. Four post-processing plugins run on the output:

• copyManifest — copies manifest.json into the dist directory
• safeRequires — rewrites require() calls for Electron's module resolution
• fixDirnamePolyfill — patches __dirname references that break in Electron's bundled context
• patchElectronCompat — applies additional compatibility fixes for Electron's sandboxed environment

Troubleshooting

Plugin Won't Load

Open the developer console (Cmd+Option+I on macOS, Ctrl+Shift+I on Windows/Linux) and check the Console tab.

Common errors:

• "Cannot find module 'X'" — dependency missing. Rebuild the plugin.
• "Claude Code executable not found" — CLI not installed or not in PATH. Run npm install -g @anthropic-ai/claude-code.
• "ANTHROPIC_API_KEY not set" — API key not in environment. See API Key above.

API Key Not Available

• Verify with echo $ANTHROPIC_API_KEY
• Launch Obsidian from a terminal that sources your shell profile
• On macOS, use launchctl setenv ANTHROPIC_API_KEY your-key to set a system-wide value

Text Not Selectable

A known Obsidian style quirk. The plugin includes a user-select: text CSS fix in styles.css. If text still isn't selectable, confirm styles.css exists in the plugin directory.

Active File Not Updating

• Switch files by clicking in the main editor, not just hovering
• Check the developer console for event listener errors
• Close and reopen the copilot sidebar

Session List Empty

Sessions are read from ~/.claude/projects/{slug}/. If no sessions exist for your working directory, the list will be empty. Sessions created from the CLI or standalone web interface with the same working directory will appear here.

Performance Issues

The plugin bundles the React client and Claude Agent SDK into a single file (~10.4MB, 2.7MB gzipped). On older machines this may cause slow initial load or occasional UI lag. Consider using the standalone web interface if performance is a concern.

Development

Hot Reload

Install the Hot Reload community plugin, then:

touch apps/obsidian-plugin/dist/.hotreload

Subsequent plugin builds will auto-reload in Obsidian without restarting.

Multiple Vaults

Sessions are stored in ~/.claude/projects/ keyed by repository path. Two vaults in the same repository share sessions; vaults in different repositories maintain independent session lists.

Support

If you encounter issues not covered here:

1. Check the developer console for error details
2. Search existing issues in the GitHub repository
3. Open a new issue with the console error, reproduction steps, your Obsidian version, and your DorkOS version (from manifest.json)

Next Steps