Agent Deck（智能体甲板）

Track every agent. Delegate from the line you are already looking at.

中文 ｜ GitHub Releases

Agent Deck gathers the AI agent sessions scattered across separate clients onto one deck inside Obsidian: which agent is working, which one is waiting for you, and how far each has got, at a glance. To hand off work, delegate from the line you are writing; progress and the result come back to that same line. What you planned and what the agents did end up in the same journal.

25-second demo (Chinese captions) · click for the 4K60 version with sound

Agent Deck is an Obsidian plugin that reads the local session logs of Claude Code, Codex, WorkBuddy, DeepSeek Harness and Antigravity, shows what each agent is doing now, and tracks delegated tasks from the editor. Notes and the panel talk by drag and drop: drop a session card on a list item to bind it, drop a list item on an agent to delegate it. Only the line under the cursor gets a small paper-plane grip: click it to send the item with its children to your primary agent after a confirm, double-click or ⌘-click to pick the agent. Once a line is bound to a session, the line-end pill becomes the progress surface: the fill moves with the session, the label changes to Delegating, and a cancel control appears next to it.

It is the AI/agent tracking half of Nautilus Spiral, extracted into a standalone plugin and extended with a second primary agent, DeepSeek Harness, model/effort/mode selection, and a layered model picker.

Contents

• How to use it
• Recommended: use it with Nautilus Spiral
• What it does
• macOS menu bar
• Human–AI journal
• Delegate targets
• Deep links
• The status pill
• Installation
• Settings
• Compatibility with Nautilus Spiral
• Privacy
• Release provenance
• Feedback and updates
• Credits
• License

How to use it

The plugin keeps explanatory text out of its UI; this section is the manual, and the switches live in the settings.

The panel

Where a click opens a session. Claude Code desktop sessions use claude://resume, Codex desktop codex://threads/<id>, WorkBuddy workbuddy://chat/<id>; DeepSeek Harness can only be focused, so the session id goes to the clipboard. Claude Code / Codex sessions running in a terminal switch to the terminal tab that runs them (Terminal, iTerm2, Tern and Herdr select the tab; Warp has no scripting interface, so it is only brought forward); only when the process has exited is a new tab opened to resume. The terminal is Auto by default, chosen per machine: the terminal most of your running claude / codex CLI sessions live in (remembered in ~/.agent-deck/terminal.json), else the last one recognised, else one that is open, else one that is installed, in the order Herdr → Tern → iTerm2 → Warp → Terminal. Settings → Tracking → Claude desktop lets you pin one, or send them to the desktop app instead.

Drag: bind and delegate

Pin Agent Deck to a sidebar and drag between the note and the panel:

• One-to-one. A session is bound in one place. Dropping it elsewhere moves the binding; an auto-logged 🤖 … line written for that session earlier is removed, so a task you already wrote and the agent's run of it merge into one line.
• The grip ⠿. The list item under the cursor shows a small grip at its end. Click it, confirm, and the item with its children goes to the default delegate (your primary agent) as one message; the item then turns DELEGATED. Double-click or ⌘-click to pick the agent (Claude Code, Codex, WorkBuddy, DeepSeek Harness), which works the same as dropping on that card; drag it onto an agent card in the sidebar, or drag a text selection. Agent cards turn dashed while you drag, and the hovered one says what dropping will do.
• Dropping into a note highlights the target line and labels it (bind / new item); headings, code blocks and tables don't accept drops.
• ⚠️ Terminal delegation is only verified on Tern and Herdr. Opening claude / codex in a terminal works end to end on Tern and Herdr for both Claude Code and the Codex CLI: the session is bound back to the item, and clicking it switches to its tab. Terminal, iTerm2 and Warp are not tested yet. Like Claude Code, Codex starts in an already-trusted directory when the vault is not trusted, with the vault added through --add-dir, so it never stops at the trust prompt. Background delegation (a plain drop on Claude Code / DeepSeek Harness) is not affected.
• Confirm before acting. Every delegated message ends with one extra line (not written into the note): ask first if anything is unclear, otherwise state the plan and wait for your go-ahead before changing anything. Turn it off under Settings → prompt prefix/suffix.
• Items that are not delegated: agent-written ones (🤖), items already bound to a session, and items with a ⏱ record. Dropping them only says why.
• With Nautilus Spiral: when Nautilus draws its session progress line under a task, Agent Deck draws no pill there and the 🔗 link is dimmed and not clickable; click Nautilus's progress line to open the session. This can be turned off in the settings.

Recommended: use it with Nautilus Spiral

The two plugins are two halves of one setup:

To hand over: open Settings → 追踪 → 停用螺旋日程里的 AI 写入 in Agent Deck, then reload Nautilus Spiral. Nautilus stops writing but keeps its schedule and tracking display; Agent Deck owns the note writes. Agent Deck also works on its own — you just lose Nautilus's planner and display.

What it does

• A dashboard for the agents on this Mac. Running, waiting and quiet sessions for Claude Code, Codex, WorkBuddy and DeepSeek Harness, with project, last step, elapsed time and tokens. Click a row to open that session in its client.
• Claude desktop side chats. In the Claude desktop app a session can spawn another session that looks like a sibling in the sidebar. Agent Deck reads spawnedFrom from claude-code-sessions/**/local_*.json, indents the child under its parent, and labels the relationship; a session with an open side chat gets a badge, and the menu bar adds side chat ×N. Archived sessions drop out of 现在 and the recent list for every client: Claude desktop (isArchived), Codex (threads.archived in state_*.sqlite, plus the older archived_sessions/), WorkBuddy (sessions.status in workbuddy.db) and DeepSeek Harness (archivedSessionIds in storages/workspace.json).
• Human–AI journal, moved in. The AI half of Nautilus Spiral's journal flow now lives here: sessions are recorded into today's note (the selected local Claude / Codex CLI names them and matches existing task lines), status and elapsed time are written back, 💬 carries the last reply, child sessions / side chats / Claude Code subagents become nested blocks, and archiving a session marks its line DONE. Nautilus keeps the tracking display.
• Write-back on bound lines. A bound 🔗 session gets 💬, its keyword follows the session (DOING / TOREVIEW / NEEDOK / ERRORED / HITLIMIT), and archiving writes DONE + ⏱ and retires the 🔗 line. While Nautilus's own AI tracking is still enabled Agent Deck stays out of the note, so the two never fight over the same lines.
• Two primary agents, full history. Pick up to two agents as primaries. They are read in full (all history, cross-day catch-up); every other enabled agent is only read for sessions that moved today.
• Two ways to delegate, no more. Drop a list item you wrote onto an agent card in the panel, or use 块去向 → 委派给 Claude (⌥⌘D). Anything between existing note items, agent-written items (🤖) and session cards is a binding, never a new session. There is no Delegate button on list items and no delegate command in the palette. Model, effort, permission mode and working directory come from the settings; when a delegation fails, Retry on its status pill opens the options sheet.
• Progress only on bound lines. A line with a 🔗 session or a running delegation gets a line-end pill. While the job runs the pill fills and shows the elapsed clock; the × cancels it. When the agent answers, the pill becomes Done and the result is written under the task as one 💬 line. Lines with no session stay clean.
• Note-native records. Delegation writes a 🔗 line under the task and changes the status to DELEGATED; the line is the source of truth. Delete the 🔗 line to unbind.
• Layered model settings. A global default model, a default effort slider, capability tags, search/filter, enable switches, pinned order and a per-row menu. Changes sit in an Unsaved changes bar until you save them.
• Local only. Everything is read from ~/.claude, ~/.codex, ~/.workbuddy, ~/.dsh and the Claude desktop session list under ~/Library/Application Support/Claude/claude-code-sessions. Nothing is uploaded. The plugin stores its own aggregate in usage.json next to the plugin, so history survives log rotation.
• Official app icons. Claude, Codex, WorkBuddy and DeepSeek Harness use the icons of their own apps in the dashboard, session rows, pills, settings and menu bar; status, tool and window icons stay Lucide, and running states use a CSS spinner.
• The agent summary lives in the macOS menu bar. Obsidian's bottom-right status bar no longer carries the agent session summary. The status item is just an icon; click it for a solid, opaque panel of task cards you can jump from.

macOS menu bar

The menu bar item is a tiny SwiftUI helper app compiled on first use; in the bar itself it is just an icon. It is not a second copy of the dashboard: it is the quick "what is running / what needs me" surface.

• Solid, not glassy. The panel is a borderless window with opaque surfaces. There is no NSPopover, no vibrancy and no frosted material, so text keeps its contrast on macOS 26. The light background is a near-white tint of the current Obsidian theme, and dark mode has its own solid palette.
• Rows speak TODOseq. Each card is tagged with a TODOseq keyword — DOING, WAITING, NEEDOK?, HITLIMIT!, PAUSED, ERRORED, DONE, LATER, TODO — with the same SVG icon and task-state colour TODOseq uses. DOING keeps its loader-circle spinning while the panel is open. The right side of the header counts DOING / WAITING, and any NEEDOK? session gets an orange reminder.
• The header is today's numbers. Four figures on the left: collaboration time, output tokens, session count, and how today compares with the average of the previous seven days (hidden when fewer than three of those days have usage). There is no icon or product name: the panel already hangs from the menu bar icon.
• Cards are card-like. White surface, 1px border, a soft shadow, a state-coloured rail, the agent's glyph badge, the project and the current step. Hovering lifts the card.
• Five at a time. The first five sessions are visible; the rest are a scroll away. The footer tells you how many sessions are in the list.
• Right side, plus a shortcut. The status item stays in the right side of the menu bar. If macOS hides it because the bar is full, press ⌃⌥⌘D (Control + Option + Command + D) to open the panel from any app; press it again to close it. Escape or a click outside also closes it. The shortcut can be changed in Settings → 追踪 → 菜单栏快捷键; no Accessibility permission is needed.
• Primary agents (up to two) contribute more rows: all live sessions plus recent sessions from the last six hours, up to six per primary by default.
• Other agents contribute only sessions that are currently running, up to three per agent by default. WorkBuddy is the exception: its waiting sessions are listed too, because they are part of the daily loop.
• The header shows all enabled agents as chips, with today's time and running and waiting counts, including agents that have no row at the moment.
• Clicking a row opens the same deeplink as the dashboard. DeepSeek Harness focuses the client and copies the session id; Codex opens codex://threads/<id> and copies codex resume <id>.
• 打开面板 opens the Obsidian dashboard via obsidian://agent-deck; 重新扫描 triggers a scan; 隐藏 disables the menu bar from inside the panel.

The menu bar panel shares the dashboard's low-saturation palette: warm neutral surfaces, the muted violet-grey accent (--ad-accent), the same agent colours, and neutral footer buttons. Task-state colours follow TODOseq.

The first start needs swiftc (Xcode Command Line Tools). The plugin compiles ~/.agent-deck/AgentDeckMenuBar.app, then launches it. It exits when Obsidian exits. The source is included in the plugin bundle, so no separate download is needed. If the menu bar does not appear, open 追踪 → 重启菜单栏 or install the command line tools with xcode-select --install.

If the menu bar is full (or a menu-bar manager such as Ice has the item in its hidden section), press ⌃⌥⌘D to open or focus the panel (a second press leaves it open; Escape or a click outside closes it). You can also run Agent Deck: 打开 macOS 菜单栏面板 from the command palette.

Human–AI journal

Your task lines are the plan; the agent session logs are the record of what actually happened. With Auto-log into today's note enabled, Agent Deck periodically reads today's sessions and writes the record back:

• Active → the matching line becomes DOING; if there is no line it writes - DOING 00:45 🤖 …. A local claude -p names the session and picks an existing task line when one fits.
• Idle for a while (40 minutes by default) → PAUSED, with - ⏱ 00:45–01:20 · 共 52m · Claude underneath.
• Archived in the desktop app / Codex → DONE 19:20 …, including lines still open from previous days.
• It never guesses DONE. The machine only moves between DOING, PAUSED and the waiting keywords (TOREVIEW, NEEDOK, ERRORED); finishing is you marking it done or archiving the session.
• Bound lines get 💬 when the session answers, their keyword follows the session, and archiving writes DONE + ⏱. Auto-logged 🤖 lines follow the session's keyword too (DOING ↔ TOREVIEW / NEEDOK / ERRORED), so a session waiting for you shows up as waiting before it is paused.
• Nested blocks: desktop child sessions (from spawnedFrom), open side chats, and Claude Code subagents (<session>/subagents/agent-*.jsonl) become indented blocks with their own status.
• Tunable in Settings → 追踪 → 自动记日记: how often it runs and how soon after startup the first run happens (1 minute by default, no longer a full interval), how many active minutes a new session needs before it gets a line (3), the idle time before PAUSED (40), which agents are logged, how many sessions are asked per round (8), the model and timeout used for naming (haiku, 120 s), whether background runs fall back to the session title when the model can't be reached (on), the CLI provider (Claude / Codex), its path, Codex reasoning effort, and the per-round 💬 polish (on / model / timeout).

Writes are line-level, stay out of undo history, skip while an IME composition is active, and abort if the note changed in the meantime. These writes used to live in Nautilus Spiral; now Agent Deck owns them, and Nautilus keeps the tracking display. While Nautilus's write flags are still on, Agent Deck stays out of the note — use 停用螺旋日程里的 AI 写入 and reload Nautilus to complete the handoff.

Agents lets you select the default model and delegation target for Claude, Codex and DSH; primary stars separately control history tracking. Models supports adding and editing model names, CLI identifiers, DSH provider routes, context and tags, plus independent defaults and reasoning effort per agent. WorkBuddy and Antigravity model selection remains in their clients. Model availability depends on the signed-in account.

Journal settings are stored explicitly as autoLogEvery (20 min), autoLogStartDelay (1 min), autoLogMinMinutes (3 min; 0 disables the threshold), autoLogIdle (40 min), autoLogBatch (8), autoLogAgents, autoLogProvider (claude / codex), autoLogModel, autoLogEffort (low), autoLogTimeout (120 s), autoLogFallback (true), autoLogPath, autoLogKw, autoLogArchiveDone, autoLogNotify, roundPolish, roundPolishModel (empty reuses the naming model), and roundPolishTimeout (30 s). The journal must already exist. The first run still applies the activity threshold; ineligible sessions wait until a later run. Live write-back follows pollSeconds (20 s by default).

Delegate targets

Claude Code

Agent Deck starts a headless Claude Code session with:

• --model (Opus 5.5 by default; Opus 5, Sonnet 5, Haiku 5.5, Fable, or a custom alias)
• --effort (low, medium, high, xhigh, max)
• --permission-mode (plan, auto, acceptEdits, manual)
• -n for the session name, --add-dir for the vault

The task starts right away; there is no input box to confirm. When the first turn finishes, the session opens in the Claude desktop app through claude://resume?session=<id> (the app imports the CLI session) and you carry on there. 委派 → 完成后自动在桌面版打开 turns that off; the line's pill still opens it.

Every delegated message, to any agent, ends with one extra line that is not written into the note: if anything is unclear, ask first; otherwise restate the plan and wait for your go-ahead before changing files or running commands. Turn it off with 提示词前后缀 → 动手前先确认.

If Claude Code has never trusted the vault, the plugin reads ~/.claude.json and starts in a directory that Claude already trusts, adding the vault with --add-dir. This behaviour can be turned off in 委派 → 库没被信任时自动换个目录.

DeepSeek Harness

Agent Deck speaks ACP (Agent Client Protocol) to dsh acp. It creates a real Harness session, selects the model and reasoning_effort, sends the prompt, and follows the session/update stream. The task starts right away and the answer is written back as 💬. The session is persisted in ~/.dsh/sessions, so it also appears in the dashboard afterwards. The Harness client itself only lists its default workspace, so a session started from the vault does not show up in the client's sidebar, and dsh://open can only bring the client forward.

ACP does not expose Claude-style plan/auto permission modes. Instead the plugin can auto-approve one-shot tool permissions, or reject them and notify you.

Codex and WorkBuddy

Codex can be the default delegation target, opening a terminal with your selected model, reasoning effort and sandbox. Plain drops still default to desktop handoff; ⌘-drop (or the terminal-default setting) uses the CLI. WorkBuddy uses client handoff: drop an item on their card, the task text (with your delegation prefix/suffix) goes to the clipboard and the client comes to the front; start a chat, paste, send. On each scan Agent Deck looks for a new session of that agent whose opening matches, writes 🔗 under the item, marks it DELEGATED, and flies the card into 现在. While it waits, the agent card shows a "waiting for you to send" row with an ×; it gives up after 30 minutes.

Codex sessions open in the desktop app with codex://threads/<id> (and codex resume <id> is copied too). WorkBuddy opens with workbuddy://chat/<id>.

Deep links

The status pill

The pill is a CodeMirror widget. It only lives on lines that already have a session or delegation, not on every list item, and it has four states:

1. Starting, while the session is being created.
2. Delegating, with a liquid fill, elapsed time and ×.
3. Waiting / needs approval, with a slow glow.
4. Done or Error, with an open/retry control.

When a delegation fails, Retry on its status pill opens the options sheet:

Installation

This plugin is not in the community store yet. Install it manually:

1. Download or clone this repository.
2. Copy main.js, manifest.json and styles.css into <vault>/.obsidian/plugins/agent-deck/.
3. Enable Agent Deck in Settings → Community plugins.

To build from source:

git clone https://github.com/MatsuriMW/obsidian-agent-deck.git
cd obsidian-agent-deck
npm install
npm run build

npm run build writes main.js with esbuild. The only runtime dependency is fzstd, used to read DeepSeek Harness's zstd-compressed session logs.

Settings

• Agents: enable each agent, pick up to two primaries, scan now, import Nautilus Spiral history.
• 委派: default target, models, effort, permission mode, working directory, prompt prefix/suffix, write-back rules, trust fallback.
• Models: the layered picker shown above.
• 追踪: day cutoff, polling interval, idle threshold, history depth, Claude desktop side chats, automatic journal logging and write-back toggles, macOS menu bar toggle and row limits, UI switches, rebuild, import, and a one-click pause Nautilus Spiral's AI writes action.
• 关于: version, license and debug info.

Compatibility with Nautilus Spiral

Agent Deck understands the same 🔗 line as Nautilus Spiral. If both plugins are on, Nautilus will also see the Claude sessions and may rewrite DELEGATED to TOREVIEW.

Agent Deck hides Nautilus's 🤖 agent status item automatically (the planner's own status bar and timer stay). The AI writes of the journal flow (automatic logging, status keywords, 💬, child blocks) now live in Agent Deck; while Nautilus's write flags are still on, Agent Deck keeps its hands off the note. Use 追踪 → 停用螺旋日程里的 AI 写入 to turn off only those writes — Nautilus keeps its tracking display. Its settings are backed up first. After using it, reload Nautilus Spiral from Obsidian's plugin settings (or restart Obsidian); Agent Deck never disables or enables another plugin.

If you use done-to-top and journal-tidy, update to done-to-top 1.17.3+ and journal-tidy 1.9.1+. Those versions keep a DELEGATED block that mentions 明天 / 后天 / 大后天 in today's DOING area instead of moving it to the next day, and do not fold DOING/TODO blocks before the first separator.

Privacy

• Session logs are read locally with Node's fs.
• No network requests are made by the tracking code.
• Delegation and AI journaling start local claude, codex or dsh processes. Journaling passes selected session titles, opening/final excerpts and unfinished daily tasks to the chosen CLI, which uses its signed-in service. Tracking alone makes no model calls.
• usage.json stores only aggregate per-day numbers and session summaries, not full conversations.
• The menu bar helper reads ~/.agent-deck/menubar.json and makes no network requests.

Release provenance

Releases are built by GitHub Actions from the tagged commit. main.js, manifest.json and styles.css carry build provenance attestations:

gh attestation verify main.js --repo MatsuriMW/obsidian-agent-deck

Feedback and updates

To follow new features, send feedback or keep up with progress, follow me on Twitter: @Matsurimywaifu.

Credits

• Extracted from Nautilus Spiral, which remains the planner.
• The progress-in-trigger-button interaction is inspired by @ZZ.X's note “AI 任务进度，长在触发按钮里”.
• The layered model settings page is inspired by @ZZ.X's note “AI 产品模型设置”.

License

MIT. See LICENSE.