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](AGENT_TASKS.md)),
> 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](https://github.com/bitsofchris/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:

```yaml
---
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:

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