Agent Fleet

Agent Fleet for Obsidian

Turn Obsidian into an AI-powered command center. Create autonomous agents on Claude Code or OpenAI Codex, schedule tasks, chat in real-time, connect via Slack or Telegram, and hook into any MCP service — all from your vault.

---

What is Agent Fleet?

Agent Fleet is an Obsidian plugin that lets you build, configure, and run AI agents directly from your vault. Agents run on the CLI backend of your choice — Claude Code (Claude Max/Pro subscription or Anthropic API key) or OpenAI Codex — selectable per agent. Every agent, skill, task, and run log is a markdown file. If the plugin disappears, your knowledge stays.

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.

🔀 Dual CLI backends — Run each agent on Claude Code or OpenAI Codex, set per agent. Models, chat, tasks, heartbeat, channels, and permission rules all work the same on either backend — pick the engine, keep the workflow.

📚 Wiki Keeper — Turn any folder in your vault into a self-maintaining wiki in the spirit of Karpathy's "LLM wiki" pattern. Drop sources into an inbox, point at existing note folders as passive watched sources, and a scoped keeper agent ingests them into an interlinked _topics/ tree with cross-references, citations, and a log. Each topic page carries a refreshable ## Summary block synthesized from its claims history, so query-time reads stay cheap as the wiki grows. Substantive Q&A answers compound back into the wiki — both as filed synthesis pages and as dated bullets on every cited topic. Weekly lint surfaces orphans, contradictions, dedup candidates, and stale summaries; the dashboard's Wiki Keepers tab renders the review queue. Scales from one whole-vault keeper to many project-scoped instances; any other agent (e.g. a PM agent) can reference a keeper's scope and query or contribute. See the Wiki Keeper Guide.

💬 Interactive Chat — Dock a chat panel anywhere in Obsidian. Switch between agents. Attach documents and images. Send follow-up messages while the agent works. Inline threads under any assistant reply let you tangent without polluting the main thread — each thread has its own backend session, its own context, its own stats.

📊 Live chat stats — Compact terminal-style strip under the composer shows the model and a context-usage bar so you always know where you stand on context.

📡 Slack & Telegram — Chat with your agents from Slack or Telegram. Multi-agent routing via @agent-name prefix or interactive buttons. Slack Assistants API with native "is thinking..." indicator. Telegram with inline keyboard agent picker and typing dots. Session persistence across restarts.

💓 Heartbeat — Autonomous periodic agent runs. Define what an agent does when no one is asking — monitoring, reports, health checks — with results posted to Slack.

📋 Task Board — Kanban view with scheduling, priority, real-time progress tracking, and abort. Tasks run on cron schedules or on-demand. Per-task model override lets you route a simple nightly summary to Haiku while keeping the agent on Opus.

🎛️ Model picker — Choose between aliases (opus / sonnet / haiku / opusplan — backend-agnostic), pinned IDs, or Bedrock/Vertex/Foundry formats. One place to configure: settings default, per-agent, or per-task override. Runs log both the requested alias and the concrete resolved model.

🔌 MCP Integration — Register an MCP server once and it's available to any agent on either adapter (Claude Code or Codex). Servers live in a fleet-owned registry (_fleet/mcp/) and are projected into each run; your native ~/.claude.json and ~/.codex/config.toml are never modified. One-click OAuth 2.1 (or a static bearer token), stored in your OS keychain and projected to both backends.

🧠 Agent Memory — A two-tier, self-curating memory (curated working set + append-only ground truth) that agents write via a remember tool or [REMEMBER] tags, on both Claude and Codex. An optional nightly reflection consolidates it and can propose new skills from recurring patterns (approval-gated).

📊 Dashboard — Overview with run charts, success rates, token/cost tracking, activity timeline, fleet status, streaming output from active agents, and focused run-detail panels that lead with the final result and hide the full reasoning transcript behind a toggle.

---

Quick Start

Install

Via npm (recommended):

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
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
2. Create <vault>/.obsidian/plugins/agent-fleet/
3. Copy the 3 files into that folder
4. Restart Obsidian → Enable Agent Fleet

Requirements

• Obsidian 1.11.4+ (desktop — macOS, Windows, Linux)

• At least one CLI backend — install whichever engine(s) your agents will use:

  • Claude Code CLI (default):

    npm install -g @anthropic-ai/claude-code
    claude  # authenticate on first run
    

    Works with a Claude Max or Pro subscription or an Anthropic API key — no separate API costs if you already subscribe.
  • OpenAI Codex CLI (optional, for codex agents):

    npm install -g @openai/codex
    codex login  # authenticate on first run
    

    Works with a ChatGPT Plus/Pro plan or an OpenAI API key.

  You only need the backend(s) your agents are configured to use — Claude-only users never pay the Codex probe, and vice versa.

First Launch

On first launch, Agent Fleet creates a _fleet/ folder in your vault:

_fleet/
├── agents/
│   └── fleet-orchestrator/    ← default agent (manages the fleet)
├── skills/                    ← 22 built-in skills
├── tasks/
├── channels/
├── mcp/                        ← registered MCP servers (one file each)
├── runs/
└── memory/

The Fleet Orchestrator agent is ready — click Chat to ask it to create new agents, tasks, skills, or channels.

Update

npm update -g obsidian-agent-fleet

Or via BRAT: settings → check for updates.

---

Features

Agents

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:

Permission Modes:

---

Backends

Each agent runs on one of two CLI backends, selected by the Adapter field in the agent editor:

Everything else — chat, tasks, heartbeat, Slack/Telegram channels, memory, run logs, model picker — works identically on both. The picker switches its alias list based on the selected adapter; free-text remains the escape hatch for any model ID.

How Codex permission rules work. Your Bash(...) allow/deny rules are translated into Codex execpolicy rules and injected through a per-agent CODEX_HOME overlay (the agent's ~/.codex with auth/config/sessions symlinked through, but its own rules directory). This enforcement is lossy by design and degrades safely:

• Only command-prefix patterns translate — Bash(git push *) → deny git push …. Tool-name rules (Read/Write/Edit) and mid-pattern wildcards (Bash(* --force)) are dropped; file/network access is governed by the Permission Mode sandbox instead.
• There's no closed allow-list — Codex allow rules are additive, so "only the allow-list runs" (Claude's dontAsk) is not reproducible; the sandbox is the real boundary.
• Requires a Codex build with execpolicy support. If it's missing (or ~/.codex isn't set up, or symlinks are unavailable), the agent falls back to sandbox-only enforcement with a one-time console warning — the run never breaks.

Codex reports no per-run dollar cost, so cost_usd is blank on Codex runs. Compact/rate-limit telemetry is Claude-only.

---

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.

Setup: Create a HEARTBEAT.md file in the agent's folder, or configure it in the dashboard's agent edit page:

---
enabled: true
schedule: "0 */6 * * *"     # every 6 hours
notify: true                 # Obsidian notice on completion
channel: my-slack            # post results to Slack (optional)
---

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".

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

---

Slack Channels

Chat with your agents from Slack — every message flows through the same chat-session pipeline as the in-app panel (Claude Code or Codex), with full tool use, session persistence, and agent memory.

📖 Step-by-step Slack setup guide → — complete walkthrough from creating the Slack app to sending your first message.

Quick overview:

1. Create a Slack app at api.slack.com 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

---
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.
---

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 the backend's resume (Claude --resume / Codex exec 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

Important: Obsidian must be running for channels to work. When Obsidian is closed, the bot goes offline.

---

Telegram

Chat with your agents from Telegram — simpler setup than Slack, no @mention required in DMs.

Setup:

1. Create a bot via @BotFather — /newbot, pick a name and username, copy the token
2. Add the token in Settings → Agent Fleet → Channel Credentials (type: Telegram)
3. Create a channel via the dashboard or as _fleet/channels/my-telegram.md
4. Message the bot in Telegram

Features:

• Zero dependencies — long-poll via HTTPS, no WebSocket, no SDK
• Typing indicator — typing... dots while the agent works (auto-refreshed every 4.5s)
• Inline keyboard agent picker — /agents command shows interactive buttons to switch agents
• Slash command autocomplete — commands registered automatically via setMyCommands
• Agent name prefix — replies show [agent-name] when multiple agents are configured
• Group chat support — add the bot to groups (disable privacy mode via BotFather for full access)
• Forum topics — enable Threaded Mode in BotFather for topic-based conversations
• Session persistence — conversations survive Obsidian restarts via the backend's resume (Claude --resume / Codex exec resume)
• 4096-char message splitting — long replies automatically chunked at paragraph boundaries

---

Interactive Chat

The chat panel is a first-class Obsidian view — dock it in the sidebar, center, or any split.

Features:

• Agent Switcher — dropdown to switch between agents instantly. Each agent has its own conversation.
• Session Persistence — conversations survive Obsidian restarts via the backend's resume (Claude --resume / Codex exec 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 the agent.
• 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

---

Task Board

A kanban view for managing agent tasks with five columns:

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

Register an MCP server once and it works for any agent on either adapter (Claude Code or Codex). Servers are a fleet-owned registry — one markdown file per server under _fleet/mcp/<name>.md — and are projected into each run at spawn time (Claude via --mcp-config, Codex via -c mcp_servers.*). Your native ~/.claude.json and ~/.codex/config.toml are read-only; Agent Fleet never modifies them.

One-time import. On first load, your existing Claude and Codex MCP servers are imported into the registry (a server configured in both becomes one entry, marked imported), and any bearer tokens found are moved into your OS keychain. Idempotent.

Add Server UI:

• Click "Add Server" on the MCP page to open the form
• stdio — command, arguments, environment variables
• HTTP / SSE — URL, custom headers, and authentication: none, a static bearer token (stored in the keychain), or OAuth (authenticate after saving)
• Servers are written to _fleet/mcp/; secrets never touch the vault

Server Management:

• Enable/disable toggle per server (writes the registry file's frontmatter)
• Per-server "Probe tools" action — stdio servers are spawned and probed via JSON-RPC; HTTP/SSE servers are probed with the stored token
• Detail slideover with transport, auth state, and the discovered tool list
• Remove Server trashes the registry file and clears any stored token
• Grant servers to specific agents in the agent editor — leave an agent's list empty to grant every enabled server

OAuth 2.1 Authentication:

One-click browser-based auth, projected to both backends:

1. Click "Authenticate" on any HTTP/SSE server card
2. Plugin discovers OAuth endpoints automatically and registers via Dynamic Client Registration (PKCE flow)
3. Opens browser for approval
4. Tokens stored securely in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
5. The token is projected into each run — to Claude as an Authorization header, to Codex via bearer_token_env_var (passed through the spawn environment, never written to argv or any config file)
6. Background token refresh — expiring tokens are refreshed automatically, and the next run picks up the fresh token

---

Skills

Reusable instruction sets that agents share. Each skill is a folder:

skills/my-skill/
├── skill.md          ← Core instructions
├── tools.md          ← CLI/API tool documentation
├── references.md     ← Background docs
└── examples.md       ← Few-shot examples

22 Built-in Skills:

---

Dashboard

The main overview with:

• 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

Sidebar navigation:

• Dashboard / Agents / Tasks Board / Run History / Approvals / Skills / MCP Servers / Channels

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

A two-tier, self-curating memory that works on task, heartbeat, and chat runs and on both Claude Code and Codex backends. Per agent, under _fleet/memory/<agent>/:

• working.md — curated, token-budgeted memory (memory_token_budget, default 1500) injected into every run, organized into Preferences (pinned) / Procedures / Observations / Recent.
• raw/<date>.md — append-only ground-truth log of everything captured (never injected), so summaries can always be re-derived.

How an agent records something (two channels, same sink):

1. The remember tool — remember(fact, pin?, section?), auto-enabled for memory agents (preferred, structured).
2. The [REMEMBER] … [/REMEMBER] text tag as a fallback ([REMEMBER:pin] for standing preferences).

Captures land in working.md immediately, so the next run/turn sees them. Memory is agent-scoped (shared across all conversations, including channels).

Reflection ("dreaming") — enable reflection_enabled and a nightly run (reflection_schedule, default 0 3 * * *) consolidates memory from the raw log: dedups, resolves contradictions, summarizes from ground truth to fit the budget, and keeps pinned preferences. With reflection_propose_skills, recurring friction becomes an approval-gated skill proposal in the Inbox. A failed reflection never wipes memory. Trigger manually with Reflect now on the agent.

Legacy single-file memory (_fleet/memory/<agent>.md) is migrated automatically. memory_max_entries is superseded by memory_token_budget.

---

Run History

Every execution is logged in _fleet/runs/YYYY-MM-DD/:

---
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-8
tags: [heartbeat]
---

## Prompt
...

## Output
...

## Tools Used
...

Click any run in the dashboard to see full details in a slideover panel.

---

Configuration

Plugin Settings

Security

All secrets — MCP OAuth/bearer tokens and channel credentials (Slack/Telegram) — are stored in your OS keychain via Obsidian's SecretStorage API, never in the vault or in your native ~/.claude.json / ~/.codex/config.toml. Existing plaintext credentials are migrated from data.json to the keychain automatically on first load and the plaintext copies are cleared.

Keychain storage uses Obsidian's SecretStorage API (Obsidian 1.11.4+, the minimum supported version).

Channel Settings

File Structure

All data lives in _fleet/ as plain markdown:

_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, Telegram)
├── mcp/              Registered MCP servers (one markdown file each)
├── runs/             Execution logs by date
│   └── YYYY-MM-DD/
├── memory/           Per-agent memory (working.md + raw/ archive)
└── chat-images/      Images pasted into chat

Everything is searchable, version-controllable, and fully yours.

---

FAQ

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.

Q: Can I use OpenAI Codex instead of Claude? Yes. Set an agent's Adapter to OpenAI Codex and it runs on the @openai/codex CLI (ChatGPT plan or OpenAI API key) instead of Claude Code. You can mix freely — some agents on Claude, others on Codex — in the same fleet. Chat, tasks, heartbeat, channels, and memory all work the same. See Backends for the per-backend differences (notably how command permission rules are enforced and that Codex runs report no dollar cost).

Q: Does it work without internet? No — agents need their CLI backend (Claude Code or OpenAI Codex) to reach its API. But all your data (agents, tasks, skills, memory) is local markdown.

Q: Can I use different models per agent or per task? Yes. Each agent has its own model setting, and you can override it per task (e.g. keep the agent on Opus but run a simple nightly summary task on Haiku to cut cost). Supports Anthropic direct, AWS Bedrock, Google Vertex, Foundry, and Mantle. Claude aliases opus / sonnet / haiku / opusplan cover the Claude backend; Codex agents use Codex slugs (a Claude-shaped default is ignored on Codex and vice-versa). Resolution order: task → agent → settings → the backend's own CLI default.

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.

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 the backend's session resume (Claude --resume / Codex exec 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.

Q: Can I use multiple agents in Slack or Telegram? Yes. Type @agent-name: message to switch agents, or use /agents to get interactive buttons. Each agent maintains its own session. Works in both Slack and Telegram.

Q: Which is easier to set up — Slack or Telegram? Telegram. Create a bot via @BotFather (30 seconds), paste the token, create a channel. Slack requires creating an app with Socket Mode, scopes, events, and reinstalls after scope changes.

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 Slack or Telegram automatically.

---

Links

• Slack Setup Guide
• Releases
• npm package
• Report Issues

---

MIT License — © 2026 Denis Berekchiyan