Terminal Dispatch

by Josh Medeski
5
4
3
2
1
Score: 45/100

Description

Send notes to terminal commands and coding agents from Obsidian, and hear back when they finish.

Reviews

No reviews yet.

Stats

0
stars
19
downloads
0
forks
3
days
3
days
3
days
3
total PRs
1
open PRs
1
closed PRs
1
merged PRs
0
total issues
0
open issues
0
closed issues
14
commits

Latest Version

4 days ago

Changelog

What's new

  • 🏷️ Frontmatter property variables: recipes can read the active note's frontmatter with {prop:name}, so a note can point a recipe at its own repo and issue:
    sesh worktree connect {prop:gh_issue} --repo {prop:gh_repo} --switch --background --command "claude \"@{file} {input}\""
    
    Numbers come out as written, and lists join with commas. If the note is missing a property the recipe uses, a Notice lists the missing names and the recipe doesn't run.
  • 🔄 Live recipe reload: edits to the plugin's data.json, by hand or by an agent using the recipes skill, show up in the command palette right away. You no longer need to toggle the plugin.
  • 🖼️ README refresh: a banner, badges, and a feature list.

Installation

Download main.js, manifest.json, and styles.css from the assets below and place them in <your-vault>/.obsidian/plugins/terminal-dispatch/, then enable Terminal Dispatch in Settings -> Community Plugins.

See the README for BRAT and manual install instructions.

Full Changelog: https://github.com/joshmedeski/obsidian-terminal-dispatch/compare/1.1.0...1.2.0

README file from

Github

Send the note you are looking at to a terminal command or coding agent, and hear back when the agent is done, without leaving Obsidian.

  • 📜 Recipes: turn any shell command into an Obsidian command palette entry
  • 🧩 Variables: fill in the vault path, active file, its frontmatter properties, or text you type when it runs
  • 🏷️ Frontmatter properties: point a recipe at the note's own repo or issue with {prop:name}
  • 🤖 Coding agents: hand the note to Claude Code, Codex, or any CLI agent in a new terminal window
  • 🔔 Hear back: a status bar count of running Claude Code sessions, and a Notice when one finishes or needs you
  • 🪟 Focus terminal: optionally bring your terminal app to the front after dispatching
  • 🧠 Agent skill: teach your coding agent to write recipes for you
  • 🔒 Private: no network requests, and it runs only the commands you write

Terminal Dispatch turns recipes into Obsidian commands. A recipe is a name plus a shell command. The command runs in the vault folder, and these variables are filled in first:

Variable Value
{vault_path} Absolute path to the vault
{file} Absolute path to the active file, wrapped in single quotes
{file_name} Active file name, with extension
{file_basename} Active file name, without extension
{prop:name} The active file's name frontmatter property. Lists join with commas. The recipe won't run if the property is missing.
{input} Text you type into a prompt when the command runs

If the command contains {input}, Terminal Dispatch asks for it first. The recipe's Input prompt sets the prompt text.

Example

The default recipes. "Send to Claude Code" opens an interactive session:

sesh window connect --target '{vault_path}' --switch --background --command "claude \"@{file} {input}\""

"Send to Claude Code (accept edits, exit)" runs Claude headless, auto-accepts file edits, and closes its window when it finishes:

sesh window connect --target '{vault_path}' --switch --background --command "claude -p --permission-mode acceptEdits \"@{file} {input}\""

Both use sesh window connect, which opens a new window in the vault's session (starting the session if needed), so they work whether or not the session is already running.

Turn on a recipe's Focus terminal to bring your terminal to the front after the command runs. Set the app name (e.g. WezTerm) under Terminal app at the top of the settings tab. This uses open -a, so it is macOS only.

Recipes live in the plugin's settings tab, or in its data.json if you'd rather edit them by hand. The plugin picks up changes to data.json as soon as the file is saved, so a recipe added there shows up in the palette without a reload.

Hearing back from Claude Code

Terminal Dispatch can show what Claude Code sessions in your vault are doing:

  • the status bar shows Claude: N running
  • a Notice appears when a session finishes (Claude finished: <prompt>)
  • a Notice appears when a session stops to ask you something (Claude needs you: <prompt>)

Claude Code reports its state through hooks that you add to your vault. Each hook writes a small JSON file to ~/.local/state/terminal-dispatch/ (or $XDG_STATE_HOME/terminal-dispatch/), and Terminal Dispatch watches that folder. If you don't add the hooks, the folder stays empty and Terminal Dispatch shows nothing.

Save this as <your-vault>/.claude/hooks/dispatch-state.sh and make it executable (chmod +x). It needs jq.

#!/bin/bash
DIR="${XDG_STATE_HOME:-$HOME/.local/state}/terminal-dispatch"
mkdir -p "$DIR"

INPUT=$(cat)
ID=$(echo "$INPUT" | jq -r '.session_id // empty')
[ -z "$ID" ] && exit 0
FILE="$DIR/$ID.json"

if [ "$1" = "end" ]; then
  rm -f "$FILE"
  exit 0
fi

PREV=$(cat "$FILE" 2>/dev/null || echo '{}')
echo "$INPUT" | jq -c --arg state "$1" --argjson prev "$PREV" \
  '$prev + {state: $state, cwd, time: now} + (if .prompt then {prompt} else {} end)' \
  > "$FILE.tmp" && mv "$FILE.tmp" "$FILE"

Then register it in <your-vault>/.claude/settings.json. If you already have hooks for these events, add these entries next to them:

{
  "hooks": {
    "UserPromptSubmit": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/dispatch-state.sh running" }] }
    ],
    "Notification": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/dispatch-state.sh waiting" }] }
    ],
    "Stop": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/dispatch-state.sh done" }] }
    ],
    "SessionEnd": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/dispatch-state.sh end" }] }
    ]
  }
}

Hooks only load when a session starts, so sessions that were already open won't show up. If a session crashes before SessionEnd runs, its file stays and keeps counting as running. Delete it from the state folder to clear it.

Agent skill

The terminal-dispatch-recipes skill teaches a coding agent (Claude Code, Codex, and others that read SKILL.md) to write recipes for you: where data.json lives, how to quote each variable, and worked examples. Install it with:

npx skills add joshmedeski/obsidian-terminal-dispatch

Or copy skills/terminal-dispatch-recipes/ into your agent's skills folder, e.g. ~/.claude/skills/. Then ask your agent for a recipe ("make a Terminal Dispatch recipe that opens this note in Neovim").

Permissions and privacy

Terminal Dispatch runs commands on your machine, so it uses capabilities beyond the Obsidian vault API:

  • Shell execution. Recipes run through child_process in the vault folder. It only runs commands you write in your own recipes, and only when you trigger them. Focus terminal runs open -a with the app name you set.
  • Filesystem access outside the vault. It reads Claude Code session state from ~/.local/state/terminal-dispatch/ (or $XDG_STATE_HOME/terminal-dispatch/), and creates that folder if it is missing. Apart from what your recipes do, it reads and writes nothing else outside the vault.
  • Environment variables. It reads HOME and XDG_STATE_HOME to find that folder and to add common tool locations (Homebrew, ~/.local/bin, ~/.cargo/bin, ~/go/bin) to PATH, so your recipes can find installed tools.

It makes no network requests and sends no data anywhere.

Requirements

Desktop only. It shells out to your local machine.

Installation

  1. Download main.js, manifest.json, and styles.css from the latest release.
  2. Drop them in <your-vault>/.obsidian/plugins/terminal-dispatch/.
  3. Enable Terminal Dispatch in Settings → Community Plugins.

Development

See CONTRIBUTING.md for the dev loop and AGENTS.md for build and release conventions.