@mseep/obsidian-agent-client 0.10.6

package/docs/help/faq.md

@@ -0,0 +1,181 @@
+# FAQ
+
+Frequently asked questions about Agent Client.
+
+## General
+
+### What is Agent Client?
+
+Agent Client is an Obsidian plugin that lets you chat with AI agents directly within Obsidian. It supports Claude Code, Codex, Gemini CLI, and any ACP-compatible agent. The plugin uses the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) to communicate with agents.
+
+### Is this an official Anthropic/OpenAI/Google plugin?
+
+No. Agent Client is a community-developed plugin. It uses official agent packages but is not affiliated with any AI provider.
+
+### Does this work on mobile?
+
+No. Agent Client is desktop-only. Agents run as local processes, which is not supported on mobile devices.
+
+### Is my data sent to AI providers?
+
+Yes. When you send a message, it's processed by the AI provider behind your selected agent (Anthropic, OpenAI, Google, etc.). Review each provider's privacy policy for details.
+
+## Note Mentions
+
+### How do I reference my notes in a conversation?
+
+Type `@` in the input field and a dropdown appears with matching notes. Select a note to insert a mention in `@[[Note Name]]` format. The note's content is sent to the agent.
+
+See [Note Mentions](/usage/mentions) for details.
+
+### Can I change the character limit for mentions?
+
+Yes. Configure **Max note length** and **Max selection length** in **Settings → Agent Client → Mentions**. The default is 10,000 characters each.
+
+### What is auto-mention?
+
+When enabled (**Settings → Agent Client → Mentions → Auto-mention active note**), the currently open note is automatically included as context. Unlike manual mentions, auto-mention only sends the note's file path—not its content. The agent can use its Read tool to access the content if needed.
+
+### Can I include just part of a note?
+
+Yes. If you select text in your note, only that selection is sent as context. The auto-mention badge shows the line range (e.g., `@My Note:5-10`).
+
+### How do I temporarily disable auto-mention?
+
+Click the **×** button next to the auto-mention badge above the input field. Click **+** to re-enable it. This only affects the current message.
+
+## Agents
+
+### How do I switch between agents?
+
+Click the **⋮** (ellipsis) menu in the chat header. Under **"Switch agent"**, select the agent you want to use. This is a one-time change for that view only.
+
+To change the default agent for new chat views, go to **Settings → Agent Client → Default agent**.
+
+### Can I run multiple agents at the same time?
+
+Yes. Open multiple chat views using **"Open new chat view"** from the command palette or the **⋮** menu in the chat header. Each view runs an independent agent process.
+
+See [Multi-Session Chat](/usage/multi-session) for details.
+
+### How do I send the same prompt to multiple agents?
+
+Use the **Broadcast** commands:
+1. Type your prompt in one chat view
+2. Open command palette and run **"Broadcast prompt"** to copy it to all views
+3. Run **"Broadcast send"** to send simultaneously
+
+### Where do new chat views open?
+
+By default, new views open in the right pane. You can change this in **Settings → Agent Client → Display → Chat view location** to open in editor tabs or splits instead.
+
+### What is a custom agent?
+
+Any ACP-compatible agent beyond the built-in ones (Claude Code, Codex, Gemini CLI). You can add custom agents in **Settings → Agent Client → Custom agents**. See [Custom Agents](/agent-setup/custom-agents).
+
+### Do all agents support the same features?
+
+No. Features like slash commands, modes, and models depend on the agent. The plugin adapts its UI based on what the agent supports. For example, the mode dropdown only appears if the agent provides multiple modes.
+
+## Slash Commands
+
+### Why don't I see slash commands?
+
+Slash commands are provided by the agent, not the plugin. If the input placeholder doesn't show `/ for commands`, your current agent doesn't support slash commands.
+
+### Why are the commands different from what I expected?
+
+Each agent provides its own commands. Claude Code, Codex, and Gemini CLI all have different command sets. Refer to your agent's documentation for available commands.
+
+## Permissions
+
+### Why does the agent ask for permission?
+
+Some agents request permission before performing certain actions (like editing files or running commands). This is a safety feature controlled by the agent.
+
+### Can I auto-approve all permissions?
+
+Yes. Enable **Settings → Agent Client → Permissions → Auto-allow permissions**. Use with caution—this gives agents full access without confirmation prompts.
+
+### Some agents don't ask for permission at all?
+
+Correct. Permission behavior is agent-specific. Some agents may edit files directly without requesting permission.
+
+## Exporting
+
+### How do I export a conversation?
+
+Click the **export button** in the chat header. The conversation is saved as a Markdown file in your vault.
+
+### Where are exports saved?
+
+By default, exports are saved to the `Agent Client` folder in your vault. You can change this in **Settings → Agent Client → Export → Export folder**.
+
+### Can I auto-export conversations?
+
+Yes. Enable **Auto-export on new chat** or **Auto-export on close chat** in export settings.
+
+### Can I customize the frontmatter tag?
+
+Yes. In **Settings → Agent Client → Export → Frontmatter tag**, you can set a custom tag. Nested tags like `projects/agent-client` are supported.
+
+## Session History
+
+### How do I resume a previous conversation?
+
+Click the **History** button (clock icon) in the chat header to open the session history modal. Select a session and click the **Restore** button (play icon) to continue where you left off.
+
+See [Session History](/usage/session-history) for details.
+
+### What's the difference between Restore and Fork?
+
+**Restore** continues the existing session—new messages are added to the same conversation. **Fork** creates a new session branching from that point, leaving the original session unchanged.
+
+### The modal says "This agent does not support session restoration"
+
+Not all agents support session restoration. You can still view and delete locally saved sessions, but you won't be able to restore or fork them with that agent.
+
+### Are my sessions saved automatically?
+
+Yes. The plugin automatically saves session metadata and message history when you send messages. Sessions are stored locally in Obsidian's data folder.
+
+### Can I delete old sessions?
+
+Yes. Open the session history modal and click the **Delete** button (trash icon) on any session. Deletion is permanent.
+
+## Windows
+
+### What is WSL mode?
+
+WSL (Windows Subsystem for Linux) mode runs agents inside a Linux environment on Windows. Enable it in **Settings → Agent Client → Windows Subsystem for Linux → Enable WSL mode**. This is useful for agents that work better in Linux environments.
+
+### Do I need to specify a WSL distribution?
+
+Only if you have multiple WSL distributions installed and want to use a specific one. Leave it empty to use your default distribution.
+
+## Cost & Billing
+
+### Is Agent Client free?
+
+The plugin itself is free and open source. However, using AI agents may incur costs depending on the agent and your authentication method.
+
+### API key vs account login—what's the difference?
+
+- **API key**: Billed per usage by the AI provider. You pay for what you use.
+- **Account login**: Uses your subscription's included usage. May have limits depending on your plan.
+
+## Getting Help
+
+### Where can I get help?
+
+1. Check the [Troubleshooting](/help/troubleshooting) page
+2. Search [GitHub Issues](https://github.com/RAIT-09/obsidian-agent-client/issues)
+3. Open a new issue if your problem isn't covered
+
+### How do I report a bug?
+
+[Open an issue on GitHub](https://github.com/RAIT-09/obsidian-agent-client/issues/new) with:
+- Your OS and Obsidian version
+- The agent you're using
+- Steps to reproduce
+- Error messages (enable **Debug Mode** in **Settings → Agent Client → Developer**)

package/docs/help/troubleshooting.md

@@ -0,0 +1,221 @@
+# Troubleshooting
+
+This guide covers common issues and solutions for Agent Client.
+
+## Connection Issues
+
+### "Connecting to [Agent]..." doesn't complete
+
+The plugin is trying to start the agent process but isn't receiving a response.
+
+**Common causes:**
+- Incorrect agent path
+- Missing Node.js
+- Agent not installed
+
+**Solutions:**
+
+1. **Verify the agent path** in **Settings → Agent Client → [Agent Name] → Path**
+   - On macOS/Linux, find the path with: `which claude-agent-acp`
+   - On Windows, find the path with: `where claude-agent-acp`
+
+2. **Verify Node.js path** in **Settings → Agent Client → Node.js path**
+   - Many agents require Node.js
+   - Find it with: `which node` (macOS/Linux) or `where node` (Windows)
+
+3. **Reload the plugin** after changing path settings (disable then re-enable in Settings → Community plugins)
+
+### "Command Not Found" error
+
+The agent executable cannot be found at the specified path.
+
+**Solutions:**
+
+1. Verify the agent is installed by running it directly in Terminal
+2. Try the **Auto-detect** button in the agent's path setting, or use the full absolute path
+3. On Windows, include the `.cmd` extension if needed
+
+## Authentication Issues
+
+### "Authentication Required" error
+
+The agent requires authentication before processing requests.
+
+**For Claude Code:**
+- **API key**: Set in **Settings → Agent Client → Claude Code (ACP) → API key**
+- **Account login**: Run `claude` in Terminal first and complete the login flow
+
+**For Codex:**
+- Set your OpenAI API key in **Settings → Agent Client → Codex → API key**
+
+**For Gemini CLI:**
+- Set your Google API key in **Settings → Agent Client → Gemini CLI → API key**
+- Or run `gemini` in Terminal first to authenticate with your Google account
+
+### "No Authentication Methods" error
+
+The agent didn't provide authentication options.
+
+**Solution:** Check your agent configuration. The agent may not be properly initialized—try reloading the plugin.
+
+## Rate Limiting
+
+### "Rate Limit Exceeded" error
+
+You've sent too many requests.
+
+**Solutions:**
+
+1. Wait before sending another message
+2. Check your usage limits at the provider's console:
+   - Anthropic: [console.anthropic.com](https://console.anthropic.com/)
+   - OpenAI: [platform.openai.com](https://platform.openai.com/)
+   - Google: [console.cloud.google.com](https://console.cloud.google.com/)
+
+## Session Issues
+
+### "Session Creation Failed" error
+
+The agent connected but couldn't create a session.
+
+**Solutions:**
+
+1. Click **New Chat** (+ button in header) to create a fresh session
+2. Check if your vault path contains special characters that might cause issues
+3. Reload the plugin
+
+### "Agent Not Found" error
+
+The selected agent ID doesn't exist in settings.
+
+**Solution:** Go to **Settings → Agent Client** and select a valid agent from the **Active agent** dropdown.
+
+## Message Sending Issues
+
+### "Cannot Send Message" error
+
+No active session available.
+
+**Solutions:**
+
+1. Wait for the connection to complete (status shows agent name, not "Connecting...")
+2. Click **New Chat** to create a fresh session
+
+### "Send Message Failed" error
+
+The message was sent but the agent returned an error.
+
+**Solutions:**
+
+1. Check the error message for details
+2. Verify your API key or login status
+3. Try a simpler message to test the connection
+
+## Export Issues
+
+### "Failed to export chat" notification
+
+The conversation couldn't be saved.
+
+**Solutions:**
+
+1. Check that the export folder exists (**Settings → Agent Client → Export → Export folder**)
+2. Verify the folder name is valid (no special characters that aren't allowed in folder names)
+3. Check the filename template for invalid characters (**Settings → Agent Client → Export → Filename**)
+
+## Multi-Device Vault Sync
+
+### Agent paths break when syncing across machines
+
+If you sync your vault (e.g., via Nextcloud, Syncthing, or iCloud) across machines with different environments (macOS, Linux, WSL2), absolute paths stored in `data.json` will not work on every machine.
+
+**Solution:** Leave the agent path and Node.js path fields **empty**. The plugin uses bare command names by default (e.g., `claude-agent-acp`) and resolves them through each machine's login shell PATH.
+
+## Windows-Specific Issues
+
+### WSL mode not working
+
+**Prerequisites:**
+- WSL must be installed: Run `wsl --status` in Command Prompt
+- A Linux distribution must be installed: Run `wsl --list`
+
+**Settings:**
+- Enable **Settings → Agent Client → Windows Subsystem for Linux → Enable WSL mode**
+- Optionally specify your distribution in **WSL distribution**
+
+### Agent works in Terminal but not in Obsidian
+
+The PATH environment may differ between Terminal and Obsidian.
+
+**Solutions:**
+
+1. Try the **Auto-detect** button, or use full absolute paths for both agent and Node.js
+2. Enable WSL mode for better compatibility
+3. Add the agent's directory to your system PATH (not just user PATH)
+
+## macOS-Specific Issues
+
+### Agent installed via Homebrew not found
+
+Homebrew binaries may not be in Obsidian's PATH.
+
+**Solution:** Try the **Auto-detect** button, or use the full path (find it with `which <agent-name>` in Terminal).
+
+## Linux-Specific Issues
+
+### Agent not found when using Flatpak version of Obsidian
+
+The Flatpak version of Obsidian runs in a sandbox that cannot access paths like `/usr/local/bin`.
+
+**Solution:** Use the AppImage or .deb version of Obsidian instead of Flatpak.
+
+### Agent works in Terminal but not in Obsidian
+
+Desktop applications on Linux may not inherit PATH settings from `.bashrc`.
+
+**Solutions:**
+
+1. Try the **Auto-detect** button, or use the full absolute path (e.g., `/usr/local/bin/gemini`)
+2. Ensure the agent is installed in a standard location (`/usr/bin` or `/usr/local/bin`)
+
+## Debug Mode
+
+If you need more detailed information about an issue, enable Debug mode:
+
+1. Go to **Settings → Agent Client → Developer → Debug mode**
+2. Enable the toggle
+3. Open DevTools:
+   - macOS: `Cmd + Option + I`
+   - Windows/Linux: `Ctrl + Shift + I`
+4. Go to the **Console** tab
+5. Filter by these prefixes:
+   - `[AcpClient]` - Agent process and connection
+   - `[AcpHandler]` - Agent event handling
+   - `[PermissionManager]` - Permission requests
+   - `[VaultService]` - Vault access
+   - `[useAgentSession]` - Session management
+
+## Common Error Messages
+
+| Error | Meaning | Quick Fix |
+|-------|---------|-----------|
+| Command Not Found | Agent executable not at specified path | Check Path setting |
+| Authentication Required | API key missing or login needed | Add API key or run agent in Terminal first |
+| No Authentication Methods | Agent configuration issue | Reload the plugin |
+| Rate Limit Exceeded | Too many API requests | Wait and retry |
+| Session Creation Failed | Agent couldn't start session | Click New Chat |
+| Agent Not Found | Invalid agent ID in settings | Select valid agent |
+| Cannot Send Message | No active session | Wait for connection or click New Chat |
+| Send Message Failed | Agent returned an error | Check error details |
+
+## Getting Help
+
+If you're still experiencing issues:
+
+1. Enable **Debug mode** and check console logs
+2. Search [GitHub Issues](https://github.com/RAIT-09/obsidian-agent-client/issues)
+3. Open a new issue with:
+   - Your OS and Obsidian version
+   - The agent you're using
+   - Steps to reproduce
+   - Error messages from Debug mode

package/docs/index.md

@@ -0,0 +1,63 @@
+---
+layout: home
+
+hero:
+  name: "Agent Client"
+  text: "AI Agents in Obsidian"
+  tagline: Chat with Claude Code, Codex, Gemini CLI, and more — right from your vault
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /getting-started/
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/RAIT-09/obsidian-agent-client
+
+features:
+  - icon: 🤖
+    title: Direct Agent Integration
+    details: Chat with AI coding agents in a dedicated right-side panel
+  - icon: 📝
+    title: Note Mentions
+    details: Mention any note with @notename to include its content in your prompt
+  - icon: ⚡
+    title: Slash Commands
+    details: Use / commands to quickly trigger agent actions
+  - icon: 🔄
+    title: Multi-Agent Support
+    details: Switch between Claude Code, Codex, Gemini CLI, and custom agents
+  - icon: 🎛️
+    title: Mode & Model Selection
+    details: Change AI models and agent modes directly from the chat
+  - icon: 💻
+    title: Terminal Integration
+    details: Let your agent execute commands and return results in chat
+---
+
+<div style="max-width: 800px; margin: 2rem auto;">
+  <video controls autoplay loop muted playsinline style="width: 100%; border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15);">
+    <source src="/demo.mp4" type="video/mp4">
+  </video>
+</div>
+
+## What is Agent Client?
+
+Agent Client is an Obsidian plugin that brings AI coding agents directly into your vault. Built on the [Agent Client Protocol (ACP)](https://github.com/agentclientprotocol/agent-client-protocol), it enables seamless communication with various AI agents.
+
+### Supported Agents
+
+| Agent | Provider | Integration |
+|-------|----------|-------------|
+| **[Claude Code](https://github.com/anthropics/claude-code)** | Anthropic | via [ACP adapter](https://github.com/agentclientprotocol/claude-agent-acp) |
+| **[Codex](https://github.com/openai/codex)** | OpenAI | via [Zed’s adapter](https://github.com/zed-industries/codex-acp) |
+| **[Gemini CLI](https://github.com/google-gemini/gemini-cli)** | Google | with `--experimental-acp` option |
+| **Custom** | Various | [Any ACP-compatible agent](https://agentclientprotocol.com/overview/agents) (e.g., OpenCode, Qwen Code, Kiro) |
+
+### Key Features
+
+- **Note Mentions**: Reference your Obsidian notes in conversations with `@notename`
+- **File Editing**: Let agents read and modify files with permission controls
+- **Chat Export**: Save conversations for future reference
+- **Terminal Integration**: Agents can execute shell commands and show results inline
+
+Ready to get started? Check out the [Installation Guide](/getting-started/).

package/docs/reference/acp-support.md

@@ -0,0 +1,110 @@
+# ACP Protocol Support
+
+This page documents which Agent Client Protocol (ACP) features are supported by this plugin.
+
+## What is ACP?
+
+The [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) is an open standard for communication between AI agents and client applications. It defines how clients send prompts, receive responses, handle permissions, and manage sessions.
+
+Agent Client implements ACP as a **client**, communicating with ACP-compatible agents like Claude Code, Codex, and Gemini CLI.
+
+## Methods
+
+### Client → Agent
+
+Methods the plugin can call on agents.
+
+| Method | Status | Notes |
+|--------|--------|-------|
+| `initialize` | ✅ Supported | |
+| `authenticate` | ✅ Supported | |
+| `session/new` | ✅ Supported | |
+| `session/prompt` | ✅ Supported | |
+| `session/cancel` | ✅ Supported | |
+| `session/set_mode` | ✅ Supported | |
+| `session/load` | ✅ Supported | |
+| `session/set_model` | ✅ Supported | Unstable API |
+| `session/list` | ✅ Supported | Unstable API |
+| `session/resume` | ✅ Supported | Unstable API |
+| `session/fork` | ✅ Supported | Unstable API |
+| `session/set_config_option` | ✅ Supported | |
+
+::: tip
+Methods marked "Unstable API" may change in future ACP versions. They are prefixed with `unstable_` in the SDK.
+:::
+
+### Agent → Client (Notifications)
+
+Session updates the plugin can receive from agents via `session/update`.
+
+| Update Type | Status | Notes |
+|-------------|--------|-------|
+| `agent_message_chunk` | ✅ Supported | Text only |
+| `agent_thought_chunk` | ✅ Supported | Text only |
+| `user_message_chunk` | ✅ Supported | Text only; used for session history replay |
+| `tool_call` | ✅ Supported | |
+| `tool_call_update` | ✅ Supported | |
+| `plan` | ✅ Supported | |
+| `available_commands_update` | ✅ Supported | |
+| `current_mode_update` | ✅ Supported | |
+| `session_info_update` | ✅ Supported | |
+| `usage_update` | ✅ Supported | Context window usage |
+| `config_option_update` | ✅ Supported | |
+
+### Agent → Client (Requests)
+
+Requests agents can make to the plugin.
+
+| Method | Status | Notes |
+|--------|--------|-------|
+| `session/request_permission` | ✅ Supported | |
+| `terminal/create` | ✅ Supported | |
+| `terminal/output` | ✅ Supported | |
+| `terminal/wait_for_exit` | ✅ Supported | |
+| `terminal/kill` | ✅ Supported | |
+| `terminal/release` | ✅ Supported | |
+| `fs/read_text_file` | — | Agents use their own Read tools |
+| `fs/write_text_file` | — | Agents use their own Write tools |
+
+## Content Types
+
+### Prompt Content (Client → Agent)
+
+Content types the plugin can send in `session/prompt`.
+
+| Type | Status | Notes |
+|------|--------|-------|
+| `text` | ✅ Supported | |
+| `image` | ✅ Supported | Requires agent support |
+| `audio` | ❌ Not supported | |
+| `resource_link` | ✅ Supported | File attachments |
+| `resource` | ✅ Supported | Embedded context; requires agent support |
+
+### Tool Call Content (Agent → Client)
+
+Content types the plugin can display in tool calls.
+
+| Type | Status | Notes |
+|------|--------|-------|
+| `diff` | ✅ Supported | |
+| `terminal` | ✅ Supported | |
+| `content` | ❌ Not supported | |
+
+## Client Capabilities
+
+Capabilities advertised to agents during initialization.
+
+| Capability | Value |
+|------------|-------|
+| `fs.readTextFile` | `false` |
+| `fs.writeTextFile` | `false` |
+| `terminal` | `true` |
+
+::: info
+The plugin does not implement filesystem operations (`fs/read_text_file`, `fs/write_text_file`). Agents handle file operations through their own tools.
+:::
+
+## See Also
+
+- [Agent Client Protocol Specification](https://agentclientprotocol.com/)
+- [ACP Schema Reference](https://agentclientprotocol.com/protocol/schema)