bitsofchris_openaugi-obsidian-plugin/docs/TASK_DISPATCH.md

Task Dispatch

⚠️ Deprecated. Task Dispatch launches tmux sessions directly from the plugin — a parallel execution path that bypasses the OpenAugi task watcher and will drift from it (different session names, duplicate repo settings). It still works, but it will be removed over a release or two. New workflows should use the Augi commands (Agent Tasks), which write task files to OpenAugi/Tasks/ for the task watcher to execute — no tmux or macOS dependency in the plugin, and they work on mobile. If you rely on Task Dispatch without the Python watcher, nothing breaks today; plan to install OpenAugi and run openaugi up before it is removed.

Task Dispatch lets you launch AI coding agents directly from Obsidian task notes. Each task gets its own tmux session with full context from your vault — the task note body, all linked notes, and access to the OpenAugi MCP server for searching your vault.

Prerequisites

• tmux — Install with brew install tmux. The plugin auto-detects the binary, or you can set the path manually in settings.
• An agent CLI — Claude Code (claude) is the default. Any CLI agent that accepts a system prompt flag works.
• macOS — Terminal opening uses AppleScript (iTerm2 or Terminal.app).

Quick Start

1. Create a task note with task_id in frontmatter:

---
task_id: fix-auth-bug
working_dir: my-repo
---

## Objective

Fix the authentication bug where sessions expire after 5 minutes.

## Context

The auth middleware is in `src/middleware/auth.ts`. The JWT expiry is hardcoded.

2. Run the command Task dispatch: Launch or attach (from the command palette).
3. A terminal window opens with the agent already running, pre-loaded with context from your note and all linked notes.

How It Works

When you launch a task:

1. Context assembly — The plugin reads the task note body (stripped of frontmatter), then gathers all linked notes via the same link traversal used by Distill. Everything is concatenated into a single context bundle.
2. Temp file — The context is written to a temp file (default: /tmp/openaugi/task-{id}-context.md).
3. tmux session — A new tmux session named task-{id} is created in the configured working directory.
4. Agent launch — The agent CLI is invoked with the context file, e.g.:

   cd '/path/to/repo' && claude --append-system-prompt-file '/tmp/openaugi/task-fix-auth-bug-context.md' "..."
   

5. Terminal opens — iTerm2 or Terminal.app opens attached to the session.

If the session already exists, the plugin just attaches to it (no duplicate sessions).

Task Note Frontmatter

Field	Required	Description
task_id	Yes	Unique identifier for the task. Also accepts task-id.
working_dir	No	Where the agent starts. Can be a repo name (mapped in settings), an absolute path, or a vault-relative path. Falls back to the default working directory setting.

Working Directory Resolution

The working_dir value is resolved in this order:

1. Named repo — If it matches a name in your configured Repository Paths, the mapped absolute path is used. Case-insensitive.
2. Absolute path — If it starts with /, used as-is.
3. Vault-relative path — Otherwise, resolved against the vault root.
4. Default — If working_dir is absent, the Default Working Directory setting is used.
5. Fallback — If nothing is configured, falls back to $HOME.

The directory is created automatically if it doesn't exist.

Example: Using Repo Names

After configuring repository paths in settings:

Name	Path
my-app	/Users/chris/repos/my-app
api-server	/Users/chris/repos/api-server
infra	/Users/chris/repos/infrastructure

Your frontmatter just needs the short name:

---
task_id: add-caching
working_dir: api-server
---

Commands

Command	What it does
Task dispatch: Launch or attach	Creates a new session or attaches to an existing one for the current task note.
Task dispatch: Kill session	Kills the tmux session for the current task note and cleans up the temp context file.
Task dispatch: List active sessions	Opens a modal showing all active task-* tmux sessions with options to attach or kill each.

Settings

All settings are under Settings > OpenAugi > Task Dispatch.

Terminal Application

Which app opens when attaching to a session.

• iTerm2 (default)
• Terminal.app

tmux Path

Absolute path to the tmux binary. Leave blank to auto-detect (checks /opt/homebrew/bin/tmux, /usr/local/bin/tmux, /usr/bin/tmux, then which tmux). Use the Detect button to find it automatically.

Default Working Directory

The directory the agent starts in when a task note doesn't specify working_dir. Can be vault-relative (e.g., OpenAugi/Tasks) or absolute. Default: OpenAugi/Tasks.

Repository Paths

Map short names to absolute folder paths. Each entry has:

• Name — The short name you'll use in frontmatter working_dir (e.g., my-repo).
• Path — The absolute filesystem path (e.g., /Users/chris/repos/my-repo).
• Browse — Opens the native folder picker to select a directory. Auto-fills the name from the folder basename if empty.

Default Agent

Which agent CLI to use. Default: Claude Code (claude).

Max Context Characters

Upper limit on the context bundle size. Content beyond this is truncated. Default: 200,000.

Context Temp Directory

Where temporary context files are written. Default: /tmp/openaugi. Files are cleaned up when sessions are killed.

Agent Configuration

The default agent is Claude Code with --append-system-prompt as the context flag. The agent config has four fields:

Field	Default	Description
id	claude-code	Internal identifier.
name	Claude Code	Display name in settings.
command	claude	The CLI command to run.
contextFlag	--append-system-prompt	The CLI flag for injecting context. If the flag ends with -file (e.g., --append-system-prompt-file), the temp file path is passed directly. Otherwise, the file content is expanded inline via $(cat ...).

Tips

• Link related context — Any notes linked from your task note ([[Design Doc]], [[API Spec]]) are automatically included in the context bundle. Structure your task notes with relevant links.
• Keep task IDs unique — The tmux session name is derived from task_id. Duplicates will collide.
• Session persistence — tmux sessions survive Obsidian restarts. Use "List active sessions" to find and reattach to running agents.
• MCP access — The agent's context includes a note that the OpenAugi MCP server is available for vault searches, so agents can look up additional information beyond what's in the initial context.