obsidian-agent-fleet 0.4.2 → 0.4.4

package/README.md

@@ -1,157 +1,288 @@
 # Agent Fleet for Obsidian
 
-**File-backed AI agents, task scheduling, and interactive chat — all inside Obsidian.**
+**Turn Obsidian into an AI-powered command center. Create autonomous agents, schedule tasks, chat in real-time, connect via Slack, and hook into any MCP service — all from your vault.**
 
-Agent Fleet lets you create, configure, and run AI agents directly from your Obsidian vault. Every agent, skill, task, and run log is a markdown file with YAML frontmatter. If the plugin disappears, your knowledge stays.
+![Agent Fleet Dashboard](screenshot.png)
 
-## Key Features
+---
 
-- **Interactive Chat** — chat with agents in a side panel with streaming markdown responses
-- **Session Persistence** — conversations survive panel close and Obsidian restarts via Claude CLI `--resume`
-- **Task Scheduling** — cron-based recurring tasks, one-shot runs, and manual execution
-- **Skill System** — reusable skill libraries that agents can share
-- **Agent Memory** — persistent context across runs via `[REMEMBER]...[/REMEMBER]` tags
-- **Live Dashboard** — overview with charts, run history, kanban board, and approval workflow
-- **Lucide Icon Picker** — searchable icon selector for agent avatars (1,400+ icons)
-- **18 Built-in Skills** — PDF, PPTX, DOCX, XLSX, Claude API, MCP Builder, Frontend Design, and more
-- **Run Output** — rendered markdown with collapsible tool call summaries
+## What is Agent Fleet?
 
-## Requirements
+Agent Fleet is an Obsidian plugin that lets you build, configure, and run AI agents directly from your vault. Agents are powered by **Claude Code CLI** — works with a Claude Max/Pro subscription or Anthropic API key. Every agent, skill, task, and run log is a markdown file. If the plugin disappears, your knowledge stays.
 
-- **Obsidian** 1.6.0 or later (desktop only)
-- **[Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)** installed and authenticated
-  ```bash
-  npm install -g @anthropic-ai/claude-code
-  claude  # authenticate on first run
-  ```
-- **Claude Max subscription** or Anthropic API key (for Claude Code CLI)
+### Core Capabilities
+
+🤖 **AI Agents** — Create specialized agents with system prompts, skills, permissions, heartbeat schedules, and memory. Each agent is a folder of markdown files you fully own and control.
+
+💬 **Interactive Chat** — Dock a chat panel anywhere in Obsidian. Switch between agents. Attach documents and images. Send follow-up messages while the agent works.
+
+📡 **Slack Channels** — Chat with your agents from Slack. Multi-agent routing via `@agent-name` prefix. Native "is thinking..." indicator via Slack Assistants API. Session persistence across restarts.
 
-## Installation
+💓 **Heartbeat** — Autonomous periodic agent runs. Define what an agent does when no one is asking — monitoring, reports, health checks — with results posted to Slack.
 
-### Via BRAT (recommended — auto-updates)
+📋 **Task Board** — Kanban view with scheduling, priority, real-time progress tracking, and abort. Tasks run on cron schedules or on-demand.
 
-1. Install the [BRAT plugin](https://github.com/TfTHacker/obsidian42-brat) from Community Plugins
-2. Open BRAT settings → **Add Beta Plugin**
-3. Paste: `denberek/obsidian-agent-fleet`
-4. Enable **Agent Fleet** in Settings → Community Plugins
+🔌 **MCP Integration** — Discover, authenticate, and inspect MCP servers. One-click OAuth 2.1 authentication. Assign MCP tools to specific agents.
 
-### Manual Install
+🧠 **Agent Memory** — Agents persist context across sessions using `[REMEMBER]` tags stored as markdown.
 
-1. Download `main.js`, `manifest.json`, and `styles.css` from the [latest release](https://github.com/denberek/obsidian-agent-fleet/releases)
-2. Create folder: `<your-vault>/.obsidian/plugins/agent-fleet/`
+📊 **Dashboard** — Overview with run charts, success rates, token/cost tracking, activity timeline, fleet status, and streaming output from active agents.
+
+---
+
+## Quick Start
+
+### Install
+
+**Via npm (recommended):**
+```bash
+npm install -g obsidian-agent-fleet
+```
+The installer automatically finds your Obsidian vaults and copies the plugin files.
+
+**Via BRAT:**
+1. Install the [BRAT plugin](https://github.com/TfTHacker/obsidian42-brat)
+2. Add beta plugin: `denberek/obsidian-agent-fleet`
+3. Enable Agent Fleet in Settings → Community Plugins
+
+**Manual:**
+1. Download `main.js`, `manifest.json`, `styles.css` from the [latest release](https://github.com/denberek/obsidian-agent-fleet/releases)
+2. Create `<vault>/.obsidian/plugins/agent-fleet/`
 3. Copy the 3 files into that folder
-4. Restart Obsidian → Settings → Community Plugins → Enable **Agent Fleet**
+4. Restart Obsidian → Enable Agent Fleet
+
+### Requirements
+
+- **Obsidian** 1.6.0+ (desktop only)
+- **[Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)** — the engine behind all agent execution:
+  ```bash
+  npm install -g @anthropic-ai/claude-code
+  claude  # authenticate on first run
+  ```
+- **Claude subscription** (Max or Pro) or **Anthropic API key** — Claude Code works with your existing subscription, no separate API costs. If you're already paying for Claude, you're ready to go.
 
-## First Launch
+### First Launch
 
-On first launch, Agent Fleet creates a `_fleet/` folder in your vault root with:
+On first launch, Agent Fleet creates a `_fleet/` folder in your vault:
 
 ```
 _fleet/
 ├── agents/
-│   └── fleet-orchestrator/    ← default agent (knows how to manage the fleet)
+│   └── fleet-orchestrator/    ← default agent (manages the fleet)
 ├── skills/                    ← 18 built-in skills
 ├── tasks/
+├── channels/
 ├── runs/
 └── memory/
 ```
 
-The **Fleet Orchestrator** agent is ready to use — click **Chat** to ask it to create new agents, tasks, or skills.
+The **Fleet Orchestrator** agent is ready — click Chat to ask it to create new agents, tasks, skills, or channels.
+
+### Update
 
-## How It Works
+```bash
+npm update -g obsidian-agent-fleet
+```
+
+Or via BRAT: settings → check for updates.
+
+---
+
+## Features
 
 ### Agents
 
-Each agent is a folder in `_fleet/agents/<name>/` with these files:
+Agents are AI assistants with specific personalities, capabilities, and permissions. Each agent is a folder in `_fleet/agents/` containing markdown files:
+
+```
+agents/my-agent/
+├── agent.md       ← Identity: name, description, system prompt
+├── config.md      ← Runtime: model, timeout, permissions
+├── SKILLS.md      ← Agent-specific skills
+├── CONTEXT.md     ← Project context
+└── HEARTBEAT.md   ← Autonomous periodic run instruction (optional)
+```
+
+**What you can configure:**
+
+| Setting | Description |
+|---------|-------------|
+| **Name & Description** | Identity shown in the dashboard |
+| **Avatar** | Lucide icon picker (1,400+ icons) or emoji |
+| **System Prompt** | Core instructions that define the agent's behavior |
+| **Model** | Claude Opus 4.6, Sonnet 4.6, Haiku 4.5, Bedrock models, or custom |
+| **Adapter** | Claude Code (more adapters coming soon) |
+| **Working Directory** | Where the agent operates (defaults to vault root) |
+| **Timeout** | Max execution time in seconds |
+| **Permission Mode** | bypassPermissions, dontAsk, acceptEdits, or plan |
+| **Allow/Deny Lists** | Fine-grained tool control (e.g., allow `Bash(curl *)`, deny `Bash(rm -rf *)`) |
+| **Skills** | Shared skills from the skill library |
+| **MCP Servers** | Which MCP servers the agent can access |
+| **Memory** | Persistent context across sessions via `[REMEMBER]` tags |
+| **Heartbeat** | Autonomous periodic run with schedule and instruction |
+
+**Permission Modes:**
+
+| Mode | Behavior |
+|------|----------|
+| `bypassPermissions` | Auto-runs everything except deny list |
+| `dontAsk` | Only allow-listed commands run |
+| `acceptEdits` | File edits auto-approved, bash blocked unless allowed |
+| `plan` | Read-only — no writes, no commands |
+
+---
+
+### Heartbeat
+
+A heartbeat gives an agent autonomous behavior — what it does when no one is asking. Think periodic monitoring, daily reports, health checks, or trend analysis.
 
-| File | Purpose |
-|------|---------|
-| `agent.md` | Identity, description, system prompt, skill assignments |
-| `config.md` | Model, timeout, permission mode, working directory |
-| `CONTEXT.md` | Project-specific context (optional) |
-| `SKILLS.md` | Agent-specific skills not shared with others (optional) |
-| `permissions.json` | Claude Code allow/deny rules (optional) |
+**Setup:** Create a `HEARTBEAT.md` file in the agent's folder, or configure it in the dashboard's agent edit page:
 
-**Example `agent.md`:**
 ```yaml
 ---
-name: site-monitor
-description: Checks website uptime and alerts on failures
-avatar: globe
 enabled: true
-tags: [monitoring]
-skills:
-  - agent-fleet-system
+schedule: "0 */6 * * *"     # every 6 hours
+notify: true                 # Obsidian notice on completion
+channel: my-slack            # post results to Slack (optional)
 ---
 
-You are a website monitoring agent. Check the specified URL,
-report its HTTP status code, response time, and any errors.
+Check all monitored endpoints for availability and response time.
+Compare with previous checks using your memory. Report anomalies.
+If everything is healthy, respond with a one-line "all clear".
 ```
 
-### Skills
+**Key behaviors:**
+- The **"Run Now" button** on any agent with a heartbeat uses the heartbeat instruction (no more generic fallback)
+- **Agent memory integration** — heartbeats can use `[REMEMBER]` tags to track trends across runs
+- **Slack delivery** — results automatically posted to a configured Slack channel
+- **Dashboard** — heartbeat status shown on the agent's Overview tab with enable/disable toggle, schedule, and next run time
 
-Reusable instruction sets in `_fleet/skills/<name>/`:
+---
 
-| File | Purpose |
-|------|---------|
-| `skill.md` | Core instructions and description |
-| `tools.md` | CLI/API tool documentation (optional) |
-| `references.md` | Background docs, conventions (optional) |
-| `examples.md` | Few-shot examples (optional) |
+### Slack Channels
 
-Agents reference skills by name in their `agent.md` frontmatter. Multiple agents can share the same skill.
+Chat with your agents from Slack — every message flows through the same Claude CLI session pipeline, with full tool use, session persistence, and agent memory.
 
-### Tasks
+> **📖 [Step-by-step Slack setup guide →](SLACK_SETUP.md)** — complete walkthrough from creating the Slack app to sending your first message.
 
-Scheduled or one-shot tasks in `_fleet/tasks/<name>.md`:
+**Quick overview:**
+1. Create a Slack app at [api.slack.com](https://api.slack.com/apps) with Socket Mode + Agents & AI Apps enabled
+2. Add credentials in Settings → Agent Fleet → Channel Credentials
+3. Create a channel via the dashboard or as `_fleet/channels/my-slack.md`
+4. DM the bot from Slack
 
 ```yaml
 ---
-task_id: check-website
-agent: site-monitor
-schedule: "0 * * * *"    # every hour
-type: recurring
+name: my-slack
+type: slack
+default_agent: fleet-orchestrator
+allowed_agents:
+  - fleet-orchestrator
+  - site-monitor
+  - code-reviewer
 enabled: true
+credential_ref: my-slack-creds
+allowed_users:
+  - U0AQW6P37N1
+per_user_sessions: true
+channel_context: |
+  You are being contacted via Slack. Keep replies concise.
 ---
-
-Check https://example.com — report status code and response time.
 ```
 
-**Task types:**
-- `recurring` — runs on a cron schedule
-- `once` — runs at a specific time (`run_at` field)
-- `immediate` — runs once on creation
+**Features:**
+- **Socket Mode** — outbound WebSocket, works behind NAT/firewalls, no public URL needed
+- **Slack Assistants API** — native "is thinking..." indicator, threaded conversations, thread titles
+- **Multi-agent routing** — type `@agent-name: message` to switch agents mid-thread. Each agent gets its own isolated session. `/agents` slash command lists available agents.
+- **Session persistence** — conversations survive Obsidian restarts via `claude --resume`
+- **Idle hibernation** — subprocess eviction after configurable idle time, transparent resume on next message
+- **Allowlist** — only approved Slack users (by user ID) can reach the bot
+- **Rate limiting** — per-conversation sliding window to prevent budget burn
+- **Markdown → mrkdwn** — automatic formatting conversion with fence-aware chunking for long replies
 
-### Chat
+**Important:** Obsidian must be running for channels to work. When Obsidian is closed, the bot goes offline.
 
-Click **Chat** on any agent to open an interactive conversation panel. Features:
+---
 
-- **Streaming responses** — text appears in real-time as the agent works
-- **Markdown rendering** — headers, lists, code blocks, tables render properly
-- **Tool activity indicator** — shows what the agent is doing ("Working… (Read)")
-- **Collapsible tool summary** — "🔧 12 tool calls" after each response
-- **Session persistence** — close and reopen, your conversation is still there
-- **`--resume` sessions** — Claude CLI maintains full tool context between turns
-- **New Chat** button to start fresh
+### Interactive Chat
 
-### Run History
+The chat panel is a first-class Obsidian view — dock it in the sidebar, center, or any split.
 
-Every execution (scheduled or manual) is logged in `_fleet/runs/YYYY-MM-DD/` with:
-- Status (success, failure, timeout, cancelled, pending_approval)
-- Duration, token count, model used
-- Full prompt and output
-- Tools used with commands
+**Features:**
+- **Agent Switcher** — dropdown to switch between agents instantly. Each agent has its own conversation.
+- **Session Persistence** — conversations survive Obsidian restarts via Claude CLI `--resume`
+- **Bidirectional Streaming** — send follow-up messages while the agent is working. Steer it mid-task.
+- **Document Attachment** — click + to attach the active document. Agent gets the full content; you see a compact pill.
+- **Image Paste & Drop** — paste from clipboard or drag images into chat. Saved to vault, passed to Claude.
+- **Stop Button** — + button becomes ■ while agent works. Click to abort.
+- **Streaming Markdown** — responses render in real-time with syntax highlighting
+- **Code Block Copy** — hover any code block for a copy button
+- **Tool Activity** — see which tools the agent is using in real-time
 
-### Agent Memory
+---
+
+### Task Board
+
+A kanban view for managing agent tasks with five columns:
+
+| Column | Description |
+|--------|-------------|
+| **Backlog** | Tasks with no schedule, waiting to be run manually |
+| **Scheduled** | Tasks with a cron schedule, enabled and waiting |
+| **Running** | Currently executing — shows real-time progress bar tied to timeout |
+| **Done** | Completed today |
+| **Failed** | Failed, timed out, or cancelled today |
+
+**Task features:**
+- **Priority** — low / medium / high / critical (color-coded left border)
+- **Real-time Progress** — progress bar shows elapsed time vs timeout, updates every second
+- **Stop Button** — red ■ on running cards to abort (shows as "Cancelled", not "Failed")
+- **Cron Scheduling** — human-friendly picker (daily, weekdays, weekly, monthly, custom)
+- **Catch Up If Missed** — auto-run overdue tasks when Obsidian opens
+- **Run Now** — execute any task immediately regardless of schedule
+- **Drag & Drop** — move tasks between backlog and scheduled columns
+
+---
+
+### MCP Servers
+
+Discover and manage all MCP (Model Context Protocol) servers configured in Claude Code.
+
+**Discovery:**
+- **stdio servers** — spawned and probed directly via JSON-RPC (~1-2s)
+- **HTTP/SSE servers** — probed with OAuth tokens for full tool schemas
+- **Plugin metadata** — descriptions from Claude's plugin directory
+
+**OAuth 2.1 Authentication:**
+
+One-click browser-based auth for MCP servers:
+1. Click "Authenticate" on any server card
+2. Plugin discovers OAuth endpoints automatically
+3. Registers via Dynamic Client Registration
+4. Opens browser for approval (PKCE flow)
+5. Tokens stored in plugin settings, auto-refresh
+
+**Server Management:**
+- Enable/disable toggle per server (writes to Claude's settings)
+- Server cards show status, tool count, type, description
+- Detail slideover with full tool list, descriptions, input schemas, parameters
+- Assign MCP servers to specific agents in the agent editor
+
+---
+
+### Skills
+
+Reusable instruction sets that agents share. Each skill is a folder:
 
-When `memory: true` in config, agents can persist context using:
 ```
-[REMEMBER]Something important to remember[/REMEMBER]
+skills/my-skill/
+├── skill.md          ← Core instructions
+├── tools.md          ← CLI/API tool documentation
+├── references.md     ← Background docs
+└── examples.md       ← Few-shot examples
 ```
 
-These entries are appended to `_fleet/memory/<agent-name>.md` and included in future prompts.
-
-## Built-in Skills
+**18 Built-in Skills:**
 
 | Skill | Description |
 |-------|-------------|
@@ -168,21 +299,77 @@ These entries are appended to `_fleet/memory/<agent-name>.md` and included in fu
 | `pptx` | Create, read, edit PowerPoint (.pptx) files |
 | `skill-creator` | Create, evaluate, and optimize skills |
 | `slack-gif-creator` | Animated GIFs optimized for Slack |
-| `theme-factory` | Apply visual themes to artifacts |
-| `web-artifacts-builder` | Multi-component HTML artifacts with React/Tailwind |
-| `webapp-testing` | Test web apps with Playwright |
-| `xlsx` | Create, read, edit spreadsheet files |
+| `taste-skill` | Senior UI/UX engineering for frontend design |
+| `frontend-slides` | HTML presentation creation |
+| And more... | |
+
+---
+
+### Dashboard
+
+The main overview with:
 
-## Dashboard
+- **Stat Cards** — active agents, runs today, tokens used (with cost), scheduled tasks
+- **Run Activity Chart** — 14-day bar chart with green (success), yellow (cancelled), red (failure)
+- **Success Rate Donut** — overall success percentage
+- **Active Agent Cards** — fixed-height streaming output from running agents with agent→task title
+- **Activity Timeline** — recent runs with status, duration, tokens
+- **Fleet Status** — agent list with quick-run capability
 
-The dashboard provides:
+**Sidebar navigation:**
+- Dashboard / Agents / Tasks Board / Run History / Approvals / Skills / MCP Servers / Channels
 
-- **Overview** — agent status cards with run charts
-- **Agents** — manage agents with enable/disable toggles
-- **Tasks Board** — kanban view of pending, completed, and failed runs
-- **Run History** — searchable table of all executions
-- **Skills Library** — browse and manage shared skills
-- **Approvals** — review and approve/reject pending tool uses
+**Agent detail page tabs:**
+- Overview (stats, heartbeat status, skills, permissions, recent runs)
+- Config (all settings, system prompt, heartbeat instruction)
+- Runs (full history for this agent)
+- Memory (learned context)
+
+---
+
+### Agent Memory
+
+Agents persist context across sessions:
+
+1. Agent includes `[REMEMBER]important context[/REMEMBER]` in its output
+2. Extracted and appended to `_fleet/memory/<agent-name>.md`
+3. Injected into the agent's prompt on every future run
+4. Memory is agent-scoped — shared across all conversations including Slack channels
+
+---
+
+### Run History
+
+Every execution is logged in `_fleet/runs/YYYY-MM-DD/`:
+
+```yaml
+---
+run_id: abc123
+agent: fleet-orchestrator
+task: daily-report
+status: success
+started: 2026-04-03T09:00:00
+completed: 2026-04-03T09:02:30
+duration_seconds: 150
+tokens_used: 4500
+cost_usd: 0.07
+model: claude-opus-4-6
+tags: [heartbeat]
+---
+
+## Prompt
+...
+
+## Output
+...
+
+## Tools Used
+...
+```
+
+Click any run in the dashboard to see full details in a slideover panel.
+
+---
 
 ## Configuration
 
@@ -192,81 +379,79 @@ The dashboard provides:
 |---------|---------|-------------|
 | Fleet Folder | `_fleet` | Root folder for all fleet data |
 | Claude CLI Path | `claude` | Path to Claude Code CLI |
-| Default Model | `default` | Default model for agents |
-| Max Concurrent Runs | `3` | Parallel execution limit |
-| Run Log Retention | `30` days | Auto-cleanup old run logs |
-| Catch Up Missed Tasks | `true` | Run missed tasks on startup |
+| Default Model | `default` | Default model for new agents |
+| AWS Region | `us-east-1` | For AWS Bedrock model support |
+| Max Concurrent Runs | `2` | Parallel task execution limit |
+| Run Log Retention | `30` days | Auto-cleanup old logs |
+| Catch Up Missed Tasks | `true` | Run overdue tasks on startup |
 | Notification Level | `all` | `all`, `failures-only`, `none` |
 
-### Agent Permission Modes
+### Channel Settings
 
-| Mode | Behavior |
-|------|----------|
-| `bypassPermissions` | Auto-runs everything except deny list |
-| `dontAsk` | Only allow-listed commands run |
-| `acceptEdits` | File edits auto-approved |
-| `plan` | Read-only, no execution |
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Max Concurrent Sessions | `5` | Live claude subprocesses across all channels |
+| Idle Timeout | `15` min | Hibernate sessions after inactivity |
+| Rate Limit | `20` msgs / `5` min | Per-conversation sliding window |
 
-## Architecture
+### File Structure
+
+All data lives in `_fleet/` as plain markdown:
 
 ```
-src/
-├── main.ts                    Plugin entry point
-├── defaults.ts                Embedded default agents + skills
-├── fleetRepository.ts         File I/O and vault management
-├── types.ts                   TypeScript interfaces
-├── constants.ts               View types and defaults
-├── settingsTab.ts             Plugin settings UI
-├── services/
-│   ├── chatSession.ts         Interactive chat with --resume
-│   ├── executionManager.ts    Claude CLI process spawning
-│   ├── fleetRuntime.ts        Runtime state and orchestration
-│   └── taskScheduler.ts       Cron-based task scheduling
-├── views/
-│   ├── dashboardView.ts       Main dashboard (3700+ lines)
-│   ├── agentsView.ts          Sidebar agent list
-│   ├── sidebarView.ts         Navigation sidebar
-│   └── inboxView.ts           Inbox view
-├── modals/
-│   ├── iconPickerModal.ts     Lucide icon selector
-│   ├── taskModal.ts           Task creation
-│   ├── createAgentModal.ts    Agent creation wizard
-│   └── confirmDeleteModal.ts  Deletion confirmation
-├── components/
-│   ├── chartRenderer.ts       Bar and donut charts
-│   ├── dragDrop.ts            Drag and drop utilities
-│   └── scheduleEditor.ts      Cron schedule editor
-└── utils/
-    ├── icons.ts               Icon helper
-    └── markdown.ts            Frontmatter parser
+_fleet/
+├── agents/           Agent folders (agent.md, config.md, HEARTBEAT.md, etc.)
+├── skills/           Shared skill folders (skill.md, tools.md, etc.)
+├── tasks/            Task files with frontmatter
+├── channels/         Channel bindings (Slack, etc.)
+├── runs/             Execution logs by date
+│   └── YYYY-MM-DD/
+├── memory/           Agent memory files
+└── chat-images/      Images pasted into chat
 ```
 
-## Development
+Everything is searchable, version-controllable, and fully yours.
 
-```bash
-# Clone
-git clone https://github.com/denberek/obsidian-agent-fleet.git
-cd obsidian-agent-fleet
+---
 
-# Install dependencies
-npm install
+## FAQ
 
-# Development build (watches for changes)
-npm run dev
+**Q: Do I need an API key?**
+Not necessarily. Agent Fleet works with your **Claude Max or Pro subscription** via Claude Code CLI. No separate API key or billing. If you prefer, you can also use an Anthropic API key directly.
 
-# Production build
-npm run build
+**Q: Does it work without internet?**
+No — agents need the Claude API to run. But all your data (agents, tasks, skills, memory) is local markdown.
 
-# Type check
-npx tsc --noEmit
+**Q: Can I use different models per agent?**
+Yes. Each agent has its own model setting. Supports Anthropic direct (Opus, Sonnet, Haiku) and AWS Bedrock models.
 
-# Run tests
-npm test
+**Q: What happens if I delete the plugin?**
+Your `_fleet/` folder stays. All agents, tasks, skills, run logs, and memory are plain markdown files in your vault.
 
-# Symlink to vault for development
-ln -s $(pwd) ~/path-to-vault/.obsidian/plugins/agent-fleet
-```
+**Q: Can multiple agents run at the same time?**
+Yes, up to `maxConcurrentRuns` (default 2). Additional tasks queue until a slot opens.
+
+**Q: Does the chat remember previous conversations?**
+Yes. Each agent has persistent chat sessions that survive Obsidian restarts via Claude CLI `--resume`.
+
+**Q: Does the Slack bot work when Obsidian is closed?**
+No. The bot runs inside Obsidian via Socket Mode — when Obsidian is closed, the bot goes offline. Slack buffers messages briefly during short disconnects.
 
-## License
+**Q: Can I use multiple agents in Slack?**
+Yes. Type `@agent-name: message` to switch agents within a Slack thread. Each agent maintains its own session. Use `/agents` to see available agents.
+
+**Q: What is a heartbeat?**
+An autonomous periodic run — what an agent does on a schedule without user input. Configured via `HEARTBEAT.md` in the agent's folder. Results can be posted to a Slack channel automatically.
+
+---
+
+## Links
+
+- [Slack Setup Guide](SLACK_SETUP.md)
+- [Releases](https://github.com/denberek/obsidian-agent-fleet/releases)
+- [npm package](https://www.npmjs.com/package/obsidian-agent-fleet)
+- [Report Issues](https://github.com/denberek/obsidian-agent-fleet/issues)
+
+---
 
-MIT
+© 2026 Denis Berekchiyan. All rights reserved.

package/SLACK_SETUP.md

@@ -0,0 +1,285 @@
+# Slack Setup Guide
+
+Connect your Agent Fleet agents to Slack so you can chat with them from your phone, desktop, or anywhere Slack runs.
+
+---
+
+## Prerequisites
+
+Before you start, make sure you have:
+
+- **Agent Fleet plugin** installed and running in Obsidian
+- **At least one agent** configured in your fleet (the default Fleet Orchestrator works)
+- **A Slack workspace** where you have permission to install apps (your own workspace or admin access)
+
+---
+
+## Part 1: Create the Slack App
+
+### Step 1 — Create a new app
+
+1. Go to **https://api.slack.com/apps**
+2. Click **Create New App** → **From scratch**
+3. **App Name:** `Agent Fleet` (or any name you prefer)
+4. **Pick a workspace:** select the Slack workspace you want to use
+5. Click **Create App**
+
+### Step 2 — Enable Socket Mode
+
+Socket Mode lets the bot connect to Slack via an outbound WebSocket — no public URL, no port forwarding, works behind any firewall or NAT.
+
+1. In the left sidebar, click **Socket Mode**
+2. Toggle **Enable Socket Mode** → ON
+3. You'll be prompted to create an App-Level Token:
+   - **Token Name:** `socket-token`
+   - **Scope:** select `connections:write`
+   - Click **Generate**
+4. **Copy the `xapp-...` token** — this is your **App Token**. Save it somewhere safe, you won't see it again without regenerating.
+
+### Step 3 — Enable Agents & AI Apps
+
+This gives you the native "is thinking..." indicator and threaded assistant conversations.
+
+1. In the left sidebar, click **Agents & AI Apps**
+2. Click **Opt In** (or toggle ON)
+3. Save
+
+### Step 4 — Add Bot Token Scopes
+
+1. In the left sidebar, click **OAuth & Permissions**
+2. Scroll down to **Bot Token Scopes**
+3. Click **Add an OAuth Scope** and add ALL of the following (one at a time):
+
+| Scope | Purpose |
+|-------|---------|
+| `assistant:write` | Native "is thinking..." indicator and thread titles |
+| `chat:write` | Send messages and replies |
+| `commands` | Handle the `/agents` slash command |
+| `im:history` | Read DM conversation history |
+| `im:read` | Access DM metadata |
+| `im:write` | Open DM conversations |
+| `app_mentions:read` | Respond when @mentioned in channels |
+| `reactions:write` | Add/remove emoji reactions (legacy, harmless to keep) |
+
+### Step 5 — Subscribe to Bot Events
+
+1. In the left sidebar, click **Event Subscriptions**
+2. Toggle **Enable Events** → ON
+3. Expand **Subscribe to bot events**
+4. Click **Add Bot User Event** and add all four:
+
+| Event | Purpose |
+|-------|---------|
+| `assistant_thread_started` | Detect new assistant conversations |
+| `assistant_thread_context_changed` | Context switching (reserved for future use) |
+| `message.im` | Receive DM messages |
+| `app_mention` | Respond to @mentions in channels |
+
+5. Click **Save Changes** at the bottom of the page
+
+### Step 6 — Enable the Messages Tab
+
+1. In the left sidebar, click **App Home**
+2. Scroll to **Show Tabs**
+3. Under **Messages Tab**, check: **Allow users to send Slash commands and messages from the messages tab**
+
+### Step 7 — Register the /agents Slash Command
+
+1. In the left sidebar, click **Slash Commands**
+2. Click **Create New Command**
+3. Fill in:
+   - **Command:** `/agents`
+   - **Short Description:** `List available agents`
+   - **Usage Hint:** _(leave blank)_
+4. Click **Save**
+
+### Step 8 — Install the App to Your Workspace
+
+1. In the left sidebar, click **Install App**
+2. Click **Install to Workspace**
+3. Review and approve the permission screen
+4. **Copy the Bot User OAuth Token** (`xoxb-...`) — this is your **Bot Token**
+
+You now have two tokens:
+- **App Token** (`xapp-...`) from Step 2
+- **Bot Token** (`xoxb-...`) from Step 8
+
+---
+
+## Part 2: Configure Agent Fleet
+
+### Step 1 — Add Slack Credentials
+
+1. Open Obsidian
+2. Go to **Settings → Agent Fleet**
+3. Scroll down to **Channel Credentials**
+4. Under **Add a Slack credential:**
+   - **Reference name:** `slack` (or any name — this is what your channel file will reference)
+   - **Bot token:** paste your `xoxb-...` token
+   - **App-level token:** paste your `xapp-...` token
+5. Click **Add credential**
+
+You should see the credential appear in the list above the form.
+
+### Step 2 — Create a Channel
+
+**Option A — Via the dashboard (recommended):**
+
+1. Open the Agent Fleet dashboard
+2. Click the **Channels** tab (last tab)
+3. Click **+ New Channel**
+4. Fill in:
+   - **Name:** `my-slack`
+   - **Type:** Slack (only option for now)
+   - **Credential:** select the credential you just added
+   - **Enabled:** ON
+   - **Default agent:** pick which agent handles messages by default
+   - **Allowed agents:** check the agents you want reachable via `@agent-name` prefix (leave unchecked for all)
+   - **Per-user sessions:** ON (each Slack user gets their own Claude session)
+   - **Allowed users:** enter your Slack user ID (see below how to find it)
+   - **Channel context:** optionally add instructions like "Keep replies concise, use Slack formatting"
+5. Click **Create Channel**
+
+**Option B — Via markdown file:**
+
+Create `_fleet/channels/my-slack.md` in your vault:
+
+```yaml
+---
+name: my-slack
+type: slack
+default_agent: fleet-orchestrator
+allowed_agents:
+  - fleet-orchestrator
+enabled: true
+credential_ref: slack
+allowed_users:
+  - U0AQW6P37N1
+per_user_sessions: true
+channel_context: |
+  You are being contacted via Slack. Keep replies concise.
+---
+```
+
+### Step 3 — Find Your Slack User ID
+
+The `allowed_users` field requires Slack user IDs (not usernames). To find yours:
+
+1. Open Slack
+2. Click your **avatar** or **profile picture** (top-right on desktop, or tap your name on mobile)
+3. Click **Profile**
+4. Click the **⋯** (three dots / more) button
+5. Click **Copy member ID**
+6. You'll get something like `U0AQW6P37N1`
+
+Paste this into the **Allowed users** field.
+
+### Step 4 — Verify the Connection
+
+1. Go to the **Channels** tab in the Agent Fleet dashboard
+2. Your channel card should show a **green status dot** within a few seconds
+3. Status should say **connected**
+
+**If the status is red**, open the Obsidian developer console (`Cmd+Opt+I` on Mac, `Ctrl+Shift+I` on Windows) and check for error messages:
+
+| Error | Fix |
+|-------|-----|
+| `invalid_auth` | Wrong token — double-check both tokens in Settings |
+| `not_enabled_for_socket_mode` | Go back to api.slack.com → Socket Mode → make sure it's ON |
+| `missing_scope` | A required scope is missing — check Step 4 of Part 1 |
+| `no_permission` | App wasn't reinstalled after adding scopes — reinstall in api.slack.com |
+
+---
+
+## Part 3: Start Chatting
+
+### Send Your First Message
+
+1. Open **Slack**
+2. Find your bot in the **Apps** section of the left sidebar (not Direct Messages — Agents & AI Apps moves the bot to Apps)
+3. Click on the bot → click **New chat** to start an assistant thread
+4. Type a message: `Hey, what can you do?`
+5. You should see:
+   - **"is thinking..."** indicator below the message composer
+   - A reply from the agent within 5-30 seconds
+
+### Switch Between Agents
+
+If you configured multiple agents in `allowed_agents`, you can switch mid-conversation:
+
+```
+@site-monitor: check if example.com is up
+```
+
+The thread title updates to show the active agent. Each agent gets its own isolated Claude session — switching back and forth resumes where each left off.
+
+### List Available Agents
+
+Type `/agents` in Slack. An ephemeral message (only visible to you) lists all agents configured for this channel.
+
+### Use the Bot in Channels
+
+You can also invite the bot to Slack channels:
+
+1. Go to a channel (e.g., `#monitoring`)
+2. Type `/invite @Agent Fleet`
+3. Now anyone in the channel can mention the bot: `@Agent Fleet check the deployment status`
+
+---
+
+## Troubleshooting
+
+### Bot Doesn't Appear in Slack
+
+- Make sure you completed Step 6 (Enable Messages Tab)
+- The bot appears under **Apps** in the sidebar, not under **Direct Messages** (this is how Slack's Agents & AI Apps works)
+
+### Messages Are Silently Dropped
+
+- Check that your Slack user ID is in the `allowed_users` list
+- Empty `allowed_users` means NO ONE can reach the bot — add at least one user ID
+
+### "is thinking..." Indicator Doesn't Show
+
+- Verify the `assistant:write` scope is added (Step 4 of Part 1)
+- Make sure you **reinstalled the app** after adding scopes (Step 8)
+
+### Bot Stops Working When Obsidian Closes
+
+This is expected. The Slack bot runs inside Obsidian via Socket Mode — when Obsidian is closed, the bot goes offline. Slack buffers messages briefly (~1 minute) during disconnects.
+
+### Token Rotation After Reinstall
+
+Every time you reinstall the Slack app (required after scope changes), the **Bot Token (`xoxb-...`) rotates**. You must:
+1. Copy the new bot token from api.slack.com → Install App
+2. Update it in Obsidian → Settings → Agent Fleet → Channel Credentials (remove old, add new)
+
+The **App Token (`xapp-...`) does NOT rotate** on reinstall — it stays the same.
+
+### Multiple Obsidian Instances
+
+If you run the plugin on two machines pointed at the same Slack app, one will get kicked off the Socket Mode connection. Only one instance can be active per app token.
+
+---
+
+## Heartbeat → Slack Delivery
+
+You can configure agents to post their heartbeat results to Slack automatically:
+
+1. Open the agent's edit page in the dashboard
+2. Scroll to the **Heartbeat** section
+3. Enable heartbeat and set a schedule
+4. Set **Post to channel** to your Slack channel name (e.g., `my-slack`)
+5. Write the heartbeat instruction
+6. Save
+
+Every time the heartbeat runs, the result is posted to the Slack channel as a DM to the first user in the allowed list, prefixed with the agent's name.
+
+---
+
+## Security Notes
+
+- **Credentials** are stored in the plugin's `data.json` inside your vault's `.obsidian` folder. If you sync `.obsidian` across devices, credentials sync too. Do not commit this file to a public git repository.
+- **Allowed users** is checked against Slack's cryptographically signed sender field (Socket Mode envelopes). It cannot be spoofed.
+- **Agents with `approval_required`** cannot be bound to channels — they would deadlock because Slack has no approval UI.
+- **Rate limiting** (default 20 messages per 5 minutes per conversation) protects against accidental or hostile budget burn.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-agent-fleet",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Obsidian plugin for file-backed AI agents, task scheduling, channels (Slack), heartbeat, and interactive chat.",
   "main": "plugin/main.js",
   "bin": {
@@ -11,13 +11,15 @@
     "plugin/main.js",
     "plugin/manifest.json",
     "plugin/styles.css",
-    "README.md"
+    "README.md",
+    "SLACK_SETUP.md"
   ],
   "scripts": {
     "build": "node esbuild.config.mjs production",
     "dev": "node esbuild.config.mjs",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "postinstall": "node bin/cli.js install --auto || true"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",

package/plugin/main.js

@@ -3677,7 +3677,8 @@ var DEFAULT_SETTINGS = {
   maxConcurrentChannelSessions: 5,
   channelIdleTimeoutMinutes: 15,
   channelRateLimitPerConversation: 20,
-  channelRateLimitWindowMinutes: 5
+  channelRateLimitWindowMinutes: 5,
+  defaultFileHashes: {}
 };
 var FLEET_SUBFOLDERS = ["agents", "skills", "tasks", "runs", "memory", "channels"];
 
@@ -15425,6 +15426,14 @@ function asNumber(value, fallback) {
 function asStringArray(value) {
   return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
 }
+function simpleHash(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const ch = str.charCodeAt(i);
+    hash = (hash << 5) - hash + ch | 0;
+  }
+  return hash.toString(36);
+}
 var FleetRepository = class {
   constructor(vault, settings) {
     this.vault = vault;
@@ -15463,6 +15472,39 @@ var FleetRepository = class {
       await this.createFileIfMissing(fullPath, file.content);
     }
   }
+  /**
+   * Update default files that the user hasn't customized. For each default file:
+   * - If missing on disk → write it and store the hash
+   * - If on disk and hash matches stored hash → user hasn't touched it → overwrite
+   * - If on disk and hash differs → user customized it → leave it alone
+   *
+   * Returns the updated hashes map so the caller can persist it to settings.
+   */
+  async updateDefaults(storedHashes) {
+    const root = this.getFleetRoot();
+    const updatedHashes = { ...storedHashes };
+    for (const file of DEFAULT_FILES) {
+      const fullPath = (0, import_obsidian2.normalizePath)(`${root}/${file.path}`);
+      const newHash = simpleHash(file.content);
+      const storedHash = storedHashes[file.path];
+      if (storedHash === newHash) continue;
+      const existing = this.vault.getAbstractFileByPath(fullPath);
+      if (!(existing instanceof import_obsidian2.TFile)) {
+        const parentDir = fullPath.substring(0, fullPath.lastIndexOf("/"));
+        await this.ensureFolder(parentDir);
+        await this.createFileIfMissing(fullPath, file.content);
+        updatedHashes[file.path] = newHash;
+        continue;
+      }
+      const currentContent = await this.vault.cachedRead(existing);
+      const currentHash = simpleHash(currentContent);
+      if (!storedHash || currentHash === storedHash) {
+        await this.vault.modify(existing, file.content);
+        updatedHashes[file.path] = newHash;
+      }
+    }
+    return updatedHashes;
+  }
   async loadAll() {
     this.agents.clear();
     this.skills.clear();
@@ -23054,7 +23096,7 @@ var FleetDashboardView = class extends import_obsidian12.ItemView {
         grid,
         "radio",
         "No channels configured",
-        "Create a file under _fleet/channels/ to wire an agent to Slack"
+        "Connect an agent to Slack or another chat platform"
       );
       return;
     }
@@ -26848,6 +26890,11 @@ var AgentFleetPlugin = class extends import_obsidian14.Plugin {
     if (isFirstRun) {
       await this.repository.ensureSamples();
     }
+    const updatedHashes = await this.repository.updateDefaults(this.settings.defaultFileHashes ?? {});
+    if (JSON.stringify(updatedHashes) !== JSON.stringify(this.settings.defaultFileHashes ?? {})) {
+      this.settings.defaultFileHashes = updatedHashes;
+      await this.saveData(this.settings);
+    }
     await this.runtime.initialize();
     await this.verifyClaudeCli(false);
     this.addRibbonIcon("bot", "Agent Fleet Dashboard", () => void this.activateDashboardView());

package/plugin/styles.css

@@ -2242,6 +2242,8 @@
   justify-content: center;
   padding: 60px 20px;
   color: var(--af-text-muted);
+  grid-column: 1 / -1;
+  text-align: center;
 }
 
 .af-empty-icon {