engage

Engage

Task orchestration with Git Worktrees and Tmux Sessions.

"Make it so." — Captain Picard

🛸 Overview

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.
• Tmux Sessions: Persistent terminal environments for every task. Never lose your shell history or running processes.
• Task Management: Markdown-based mission tracking with structured metadata, versioned directly in your git project.

Why Engage?

1. Zero Context Loss: Switching tasks means switching directories and terminals. Your previous work stays exactly as you left it.
2. Clean State: Every feature branch gets a fresh environment. No more node_modules pollution or leftover build artifacts.
3. Agent-Ready: Designed with AI agents in mind, providing structured context and clear boundaries for autonomous coding tasks.

🛠️ Requirements

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

📦 Installation

From GitHub

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

From Source (Local)

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

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

🚀 Quick Start

1. The Captain's Workflow (Recommended)

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.

2. Manual Commands (The Mechanics)

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)
engage start 1
# Note: If running inside tmux, this spawns in background. Use 'engage switch 1' to connect.

# 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 Drop a task (delete branch + worktree + task file)
engage eject 1
# Use --force to skip confirmation
engage eject 1 --force

💻 Commands

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

⚙️ Configuration

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

# 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

📝 Task File Format

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)

📂 Directory Structure

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

🤝 Contributing

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.

📄 License

MIT