# Obsidian Plugin
Source: https://dorkos.ai/docs/guides/obsidian-plugin

Run DorkOS inside Obsidian as a sidebar plugin, so you can talk to your coding agent without leaving your notes



# Obsidian Plugin [#obsidian-plugin]

DorkOS can run inside Obsidian as a sidebar panel, so your coding agent sits next to your notes instead of in a separate terminal window. No alt-tabbing required.

<Callout type="warn">
  This is an early, staged surface. It isn't in Obsidian's Community Plugin directory yet, so
  installing it means cloning the DorkOS repository and building it yourself. If that sounds like
  more setup than you want today, use the [standalone web cockpit](/docs/getting-started/quickstart)
  instead. Everything here is built and works, but it hasn't been tested as widely as the web app.
</Callout>

## What You Get [#what-you-get]

* **Active file tracking**: the note you have open is automatically included as context.
* **Drag-and-drop**: drag files from Obsidian's file explorer into the chat.
* **File navigation**: click a file reference in the chat to open it in Obsidian.
* **Vault-aware sessions**: the working directory is set automatically to your vault's parent folder (your repository root).
* **Theme integration**: the panel adapts to your Obsidian light or dark theme.

## Requirements [#requirements]

* **Obsidian Desktop**: the plugin needs Obsidian's desktop app. It does not run on Obsidian Mobile.
* **Claude Code**: DorkOS bundles Claude Code, so you normally don't need to install anything separately.

<Callout type="info">
  Claude Code ships with DorkOS as a per-platform binary. If the bundled binary isn't available on
  your machine, install it manually as a fallback:

  ```bash
  # macOS / Linux
  curl -fsSL https://claude.ai/install.sh | bash

  # Windows (PowerShell)
  irm https://claude.ai/install.ps1 | iex
  ```
</Callout>

## Installation [#installation]

The plugin isn't published yet, so you install it by building it from source.

**1. Build the plugin** from the DorkOS monorepo root:

```bash
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:

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

On Windows:

```powershell
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**: go to Settings → Community Plugins, find "DorkOS Copilot," and turn it on.

Once the plugin reaches the Community Plugin directory, this whole section collapses to a single click. Until then, this is the path.

## Configuration [#configuration]

### API Key [#api-key]

The plugin uses the same Claude Code setup as the rest of DorkOS. The simplest path is the one the [Quickstart](/docs/getting-started/quickstart) walks you through: set `ANTHROPIC_API_KEY` in your environment. See [Configuration](/docs/getting-started/configuration) for the full picture, including how DorkOS stores credentials by reference rather than as plain text.

One Obsidian-specific catch: Obsidian needs to see that environment variable when it launches. If you open Obsidian from macOS Spotlight or the Windows Start Menu, it may not inherit your shell's environment. Launching Obsidian from a terminal (where you've already set the key) sidesteps this.

### Working Directory [#working-directory]

The plugin sets the working directory to your vault's parent directory (your 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/
```

That gives DorkOS access to your slash commands, your full repository, and Git.

## Usage [#usage]

### Opening the Sidebar [#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`, then search for "Open Copilot."
3. **Custom hotkey**: assign one under Settings → Hotkeys.

The copilot opens as a panel in the right sidebar.

### Adding Context [#adding-context]

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

You can also drag files from Obsidian's file explorer into the chat area; the drop zone highlights while you drag. Files you add this way stay in the chat until you remove them with the "x" button. Both the active file and anything you dragged in are sent along with your next message.

### Opening Files from Chat [#opening-files-from-chat]

Click a file path in the agent's response to open it in the Obsidian editor.

### Session Management [#session-management]

The session list shows every chat session for this working directory, including ones you started from the CLI or the standalone web app. Sessions live in `~/.claude/projects/{slug}/` and can't be deleted from the plugin's UI.

## How It Differs from Standalone Mode [#how-it-differs-from-standalone-mode]

The plugin isn't just the web app in a sidebar. Because it runs inside Obsidian's own process, a few things work differently:

| Feature              | Standalone Web               | Obsidian Plugin               |
| -------------------- | ---------------------------- | ----------------------------- |
| Connection to DorkOS | HTTP/SSE to a running server | In-process, no network calls  |
| Session ID storage   | URL query parameter          | Internal state                |
| Active file context  | Not available                | Auto-tracked                  |
| File drag-and-drop   | Not available                | From Obsidian's file explorer |
| Open file action     | Not available                | Opens in the Obsidian editor  |
| Theme                | DorkOS's own theme           | Obsidian's theme              |
| Working directory    | Set with a directory picker  | Vault parent, automatic       |

## Troubleshooting [#troubleshooting]

### Plugin Won't Load [#plugin-wont-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'"**: a dependency is missing. Rebuild the plugin.
* **"Claude Code executable not found"**: the bundled Claude Code binary couldn't be resolved and no `claude` is on your PATH. Install it manually as a fallback: `curl -fsSL https://claude.ai/install.sh | bash` (macOS/Linux) or `irm https://claude.ai/install.ps1 | iex` (Windows).
* **"ANTHROPIC\_API\_KEY not set"**: the API key isn't in your environment. See [API Key](#api-key) above.

### API Key Not Available [#api-key-not-available]

* Verify with `echo $ANTHROPIC_API_KEY`.
* Launch Obsidian from a terminal that sources your shell profile.
* On macOS, run `launchctl setenv ANTHROPIC_API_KEY your-key` to set it system-wide.

### Text Not Selectable [#text-not-selectable]

A known Obsidian quirk, not a DorkOS bug: some Obsidian themes make plugin panel text unselectable by default. The plugin ships a `user-select: text` fix in `styles.css`. If text still won't select, confirm `styles.css` exists in the plugin directory.

### Active File Not Updating [#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 [#session-list-empty]

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

### Performance Issues [#performance-issues]

The plugin bundles the React client and the Claude Agent SDK into a single file (around 23MB, about 6MB gzipped). On older machines this can slow the initial load or cause occasional UI lag. If that's a problem, use the standalone web interface instead.

## Support [#support]

If you run into something not covered here:

1. Check the [developer console](#plugin-wont-load) for error details.
2. Search existing issues in the [GitHub repository](https://github.com/dork-labs/dorkos).
3. Open a new issue with the console error, reproduction steps, your Obsidian version, and your DorkOS version (from `manifest.json`).

## Reference (for contributors) [#reference-for-contributors]

The rest of this page is for people building or modifying the plugin itself, not for people using it.

### Build Architecture [#build-architecture]

The plugin builds with Vite in library mode, targeting CommonJS so the output works inside Electron (Obsidian's desktop runtime). 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.

The plugin uses `DirectTransport`: the same services that back the web app's HTTP API run in-process inside Obsidian's Electron environment instead, with no HTTP or SSE layer in between. That's what makes the plugin fast, and it's also why standard Node.js module patterns need the adaptations above to run inside Electron.

### Hot Reload [#hot-reload]

Install the [Hot Reload](https://github.com/pjeby/hot-reload) community plugin, then:

```bash
touch apps/obsidian-plugin/dist/.hotreload
```

Subsequent builds auto-reload in Obsidian without a restart.

### Multiple Vaults [#multiple-vaults]

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

## Next Steps [#next-steps]



<Cards>
  <Card title="Tool Approval" href="/docs/guides/tool-approval">
    Review and manage tool approval flows.
  </Card>

  <Card title="Keyboard Shortcuts" href="/docs/guides/keyboard-shortcuts">
    Navigate DorkOS efficiently with hotkeys.
  </Card>

  <Card title="Building Integrations" href="/docs/integrations/building-integrations">
    The full Transport reference: how DirectTransport and HttpTransport work under the hood.
  </Card>
</Cards>