Obsidian as cockpit, Agent as engine. Your knowledge base is the control plane; AI coding agents are the execution layer. Sessions are vault files you can open, link, search, and resume — not just a chat panel.
Obsidian Harness turns your vault into a cockpit for AI coding agents (Claude Code, Codex, Gemini CLI, Pi, and any ACP-compatible agent). Unlike a plain "chat with agents" plugin, Harness treats every agent session as a first-class file in your vault — a .session note you move, link, and reopen like any other note — and gives you Codex-style navigators to roam your work across projects, turns, and agent backends.
Built on Agent Client Protocol (ACP) by Zed.
demo.mp4
Every AI coding agent keeps its own session in its own silo — context doesn't survive across agents, across devices, or across reboots. Harness fixes that by folding agent sessions into your knowledge base:
- Sessions are vault files. A session lives as a
.sessionnote you can move between folders, backlink from other notes, find via search, and reopen any time. The IDE becomes a file viewer; the agent does the work; you stay in the cockpit. - Readable offline. A transcript renders full conversations — user turns, assistant replies, tool calls — without a live agent running. Your history stays useful even after the backend is gone.
- Cross-agent & resumable. Sessions store in ACP format; an imported session carries an
acpBindingto its original backend, so you can resume the real conversation in place when the agent is configured locally. - One cockpit, many agents. Claude Code, Codex, Gemini CLI, Pi, or any ACP-compatible agent — switch backends without losing your session graph.
- Session Navigator — a Codex-style sidebar that organizes sessions by Project and Recents, with live run status on every row. Projects are projected from each session's working directory, so there's no separate project entity to manage.
- Turn Navigator — a left-rail track on the message list, one node per user turn. Hover to preview a turn summary, click to smooth-jump, and the active turn highlights as you scroll. Never lose your place in a long conversation.
- Session Manager — a dedicated view to browse, open, and manage every session in the vault.
- New-session modal — start a session by naming a project and (optionally) picking an agent working directory; the
.sessionentry stays in the vault while the agent works in the chosencwd.
- Session Importer (companion skill) — convert an existing Claude Code / Codex / Pi Agent / Kimi Code session into a standard, readable-and-resumable Harness session inside your vault. One session at a time, explicitly selected, idempotent.
- ACP binding & continuation — imported sessions bind to their original backend session; resume the real conversation when the agent is available, or keep reading gracefully when it's not.
- Note Mentions — pull any note's content into your prompt with
@notename. - Multi-Agent — switch between Claude Code, Codex, Gemini CLI, Pi, and custom agents.
- Multi-Session — run several agents in separate views at once.
- Floating Chat — a persistent, collapsible window for quick access.
- Mode & Model Switching — change models and agent modes from the chat.
- Slash Commands — use
/commands provided by your agent. - Terminal Integration — agents run shell commands and return results inline.
- Chat Export — save conversations as Markdown notes, with frontmatter tags and wikilinks.
- MCP Support — agents use their configured MCP servers; no extra setup in the plugin.
This plugin is not (yet) in the Obsidian Community Plugins directory. Install it with BRAT:
- Install the BRAT plugin
- Go to Settings → BRAT → Add Beta Plugin
- Paste:
https://github.com/vlln/obsidian-harness - Enable Obsidian Harness from the plugin list
- Download
main.js,manifest.json,styles.cssfrom Releases - Place them in
VaultFolder/.obsidian/plugins/obsidian-harness/ - Enable the plugin in Settings → Community Plugins
Open a terminal (Terminal on macOS/Linux, PowerShell on Windows) and run the following commands.
-
Install an agent and its ACP adapter (e.g., Claude Code):
curl -fsSL https://claude.ai/install.sh | bash # Install Claude Code npm install -g @agentclientprotocol/claude-agent-acp # Install ACP adapter
-
Login (skip if using an API key):
claude
Follow the prompts to authenticate with your Anthropic account.
-
Find the paths:
which node # macOS/Linux which claude-agent-acp where.exe node # Windows where.exe claude-agent-acp
-
Configure in Settings → Obsidian Harness:
- Node.js path: e.g.,
/usr/local/bin/node - Agents → Claude Code → Path: e.g.,
/usr/local/bin/claude-agent-acp(notclaude) - API key: Add your key, or leave empty if logged in via CLI
- Node.js path: e.g.,
-
Start working: Click the robot icon in the ribbon. Use the Session Navigator to browse sessions by project, the Turn Navigator to jump between turns, and open any
.sessionfile to read or resume a conversation.
- Claude Code
- Codex
- Gemini CLI
- Pi
- Custom Agents (OpenCode, Qwen Code, Kiro, Mistral Vibe, etc.)
This repo ships a companion skill — harness-session-importer — that converts an existing Claude Code / Codex / Pi Agent / Kimi Code session into a standard, readable-and-resumable Obsidian Harness session inside your vault. One session at a time, explicitly selected; idempotent; never overwrites on conflict.
python3 skills/harness-session-importer/scripts/import_session.py \
--harness claude-code \
--session ~/.claude/projects/<dir>/<uuid>.jsonl \
--vault <absolute-vault-path> \
--entry-dir Sessions \
--adapter <absolute-harness-adapter-path>See the Session Importer docs for supported sources, prerequisites, and the CLI contract.
npm install
npm run devFor production builds:
npm run buildApache License 2.0 - see LICENSE for details.