Parallel task orchestration with Git Worktrees, Tmux Sessions, and Markdown-based versioned task tracking.

"Make it so." — Captain Picard

Engage is a "Starfleet-grade" task orchestration tool designed for developers who juggle multiple complex tasks simultaneously. It eliminates the friction of context switching by combining:

• Git Worktrees: Instantly switch contexts without stashing or cloning. Each task gets its own isolated directory, ensuring a clean state free of node_modules pollution or leftover build artifacts.
• Tmux Sessions: Persistent terminal environments for every task. Never lose your shell history or running processes, achieving zero context loss. (See Tips for a quick session switcher).
• Task Management: Markdown-based mission tracking with structured metadata. Designed for AI agents, providing clear boundaries and context for autonomous coding tasks.

Engage prioritizes Control and Memory, enabling you to work on multiple levels. Act as a Fleet Commander orchestrating high-level strategy, while retaining instant access to individual interactive, independent sessions for low-level intervention. Every action is tracked in the tasks/ directory, creating a permanent paper trail of your project's history accessible to both humans and AI.

• Git: 2.5+ (for worktree support)
• Tmux: 3.0+
• Go: 1.25+ (for building)

go install github.com/Robitx/engage/cmd/engage@latest

# Build from source
go build -o engage ./cmd/engage

# Install to your PATH
go install ./cmd/engage

This is the primary way to use Engage. You, the human, act as Starfleet Command, and an AI agent acts as your Captain (Picard).

# 1. Install Engage
go install github.com/Robitx/engage/cmd/engage@latest

# 2. Initialize in your project
engage init

# 3. Summon the Manager Agent
engage agent

Once the agent starts, it will assume the role of Manager. You can give it high-level orders like:

"Create a task to fix the Holodeck safety protocols."

"Start working on task 1701."

"Check up on task 1701."

"Assimilate task 1701."

The Manager will handle the details: creating task files, spawning worker agents in isolated worktrees, and merging changes.

If you prefer to run things yourself or need to debug, you can use the underlying commands directly:

# Create a new task (Smart branch naming: "feat/calibrate-warp-coils")
engage new "Calibrate Warp Coils"
# Output: 
# Created tasks/backlog/000001-calibrate-warp-coils.md
# Please edit this file to define the task mission and acceptance criteria.

# Edit the task definition to set requirements
vim tasks/backlog/000001-calibrate-warp-coils.md

# Start a task (spawns worktree + tmux session)
# Automatically commits the backlog task file if it's the only change.
engage start 1
# Note: If running inside tmux, this spawns in background. Use 'engage switch 1' to connect.
# (See "Tips" below for a hotkey to fuzzy-find sessions!)

# Check status of all tasks (with nice colors and alignment)
engage status

# Accept changes (squash merge + archive + cleanup)
engage assimilate 1
# If conflicts occur: resolve them, 'git add', then:
engage assimilate 1 --continue

# OR Submit for PR (archive task + cleanup backlog in branch)
# Run this inside the worktree when finished, before pushing.
engage submit

# OR Drop a task (delete branch + worktree + task file)
engage eject 1
# Use --force to skip confirmation
engage eject 1 --force

Aliases: list → status, accept → assimilate, drop → eject

Engage creates a .engage.yaml file in your project root. You can configure the agent section to define what command runs when you start a task.

Note: You can use {prompt} in args to inject the mission instructions.

project:
  name: my-project
  worktrees_dir: .worktrees
  main_branch: main
  # Maximum number of concurrently active tasks (in-progress). Default: 0 (unlimited)
  max_active_tasks: 5

# Defines the AI agent command spawned by 'engage start' and 'engage agent'
agent:
  command: opencode
  # {prompt} will be replaced by the text in the 'prompt' field below
  args: ["--agent", "build", "--prompt", "{prompt}"]
  prompt: "Run the 'engage' shell command to receive your mission instructions."

tmux:
  session_prefix: my-project

files:
  # Files/directories to symlink into new worktrees (absolute or relative to root)
  symlink:
    - node_modules
  # Files/directories to recursively copy into new worktrees
  copy:
    - .env

Tasks are Markdown files with YAML frontmatter:

---
id: 001701
title: "Optimize Warp Core Injectors"
status: "in-progress"
branch: "feat/warp-core-efficiency"
touches:
  - internal/engineering/warp.go
  - internal/propulsion/injector.go
---

## Mission

Improve antimatter flow rate regulation to increase warp efficiency by 15%.

## Acceptance Criteria

- [ ] Antimatter containment field remains stable under high load
- [ ] Dilithium reaction chamber temperature stays within nominal limits
- [ ] Warp factor 9.9 achieved in simulation

## Mission Log

- Stardate 47457.1: Started implementation
- (Agent notes and reasoning go here)

After running engage init (shown with example tasks):

your-project/
├── .engage.yaml                 # Configuration
├── .worktrees/                  # Git worktrees (gitignored)
│   └── feat-shield-modulation/  # Worktree for a task
└── tasks/                       # Task history (versioned)
    ├── template.md              # Template for new tasks
    ├── backlog/                 # Active tasks
    │   └── 001701.md
    └── archive/                 # Completed tasks
        └── 000042-calibrate-warp-coils.md

bind -n C-s display-popup -E "\
    tmux list-sessions | sed -E 's/:.*$//' |\
    fzf --reverse |\
    xargs tmux switch-client -t"

This project is primarily a personal tool ("Make it so") and is not intended to be a swiss-army knife for every workflow.

• Pull Requests: I welcome solid, pragmatic PRs that align with the core philosophy:
  • Git Worktrees (Isolation)
  • Tmux Sessions (Persistence - not windows/panes)
  • Markdown Tasks (File-based, versioned context & tracking)
• Agents: While only OpenCode is officially supported, I welcome PRs adding configuration examples for other agents (Claude, Aider, etc.) to the documentation.

MIT