obsidian-agent: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is an Obsidian plugin that implements an Agent Client Protocol (ACP) client, enabling integration with AI coding agents that support the ACP standard. The plugin spawns an external ACP-compatible agent process, communicates with it over JSON-RPC via stdin/stdout, and provides a chat UI within Obsidian.

Commands

Development

# Development build with watch mode
npm run dev

# Production build (includes type checking)
npm run build

# Version bump (used before releases)
npm run version

Installation

npm install

Architecture

Core Components

main.ts - Plugin entry point

• Extends Obsidian's Plugin class
• Registers the agent view type and ribbon icon
• Manages plugin lifecycle (load/unload)
• Creates and maintains a singleton ACPClient instance
• Provides commands: open view, connect, disconnect

acp-client.ts - ACP protocol implementation

• Spawns external agent process using Node's child_process.spawn
• Converts Node.js streams to Web Streams for ACP library compatibility
• Creates ClientSideConnection from @zed-industries/agent-client-protocol
• Implements all required ACP client methods as protocol callbacks
• Manages terminal subprocesses spawned by agent requests
• Handles vault path resolution for file operations

agent-view.ts - Chat UI component

• Extends Obsidian's ItemView to create custom view
• Displays streaming agent messages, tool calls, plans, and permission requests
• Handles in-place updates for tool calls (shows status badges)
• Renders permission requests inline with approve/deny buttons
• Auto-scrolls messages container
• Manages connection controls and message input

settings.ts / settings-tab.ts - Configuration

• Stores agent command path, arguments, and preferences
• Provides settings UI in Obsidian settings panel

Communication Flow

1. User clicks Connect → AgentView.connect()
2. ACPClient.initialize() spawns agent process, creates Web Streams, initializes connection
3. ACPClient.createSession() sends newSession request with vault path as cwd
4. User sends message → ACPClient.sendPrompt() sends prompt request
5. Agent processes request, may call back to client methods (file ops, terminal, permissions)
6. Agent sends session updates via sessionUpdate callback
7. AgentView.handleUpdate() parses update type and renders UI accordingly