Shot - Parallel AI Agent Runner 🚀

A powerful TypeScript CLI tool built with Bun for running AI agents in parallel with advanced features:

🤖 Run multiple AI coding agents in parallel
🌳 Use Jujutsu with Git collocated - Automatic Jujutsu workspaces management for isolated development
🖥️ Tmux session management for each agent
🚀 Automatic development server setup with port management
📊 Real-time monitoring of agent status and code changes
🔄 Automatic handling of agent prompts and confirmations
🎯 Easy checkpoint and merge of agent changes
⏱️ Precise timing measurement for each agent execution

Features

• 🤖 Support for multiple AI agents (Claude Code, Cursor CLI, Codex, AmpCode, Warp)
• 🔍 Auto-detection of installed agents with version display
• 🎯 Model selection for each agent
• 🔌 MCP (Model Context Protocol) server integration
• ⚡ Fast execution with Bun runtime
• 🛠️ Easy configuration and setup
• 🚀 Automatic agent selection when not specified

Installation

# Install dependencies
bun install

# Install required tools
brew install jj        # Jujutsu VCS (required for parallel mode)
brew install tmux      # Tmux (optional but recommended)

# Make scripts globally available
bun link

# Or run directly
bun run shot.ts [options] <prompt>           # Single agent
bun run shot-parallel.ts [options] <prompt>  # Parallel agents

Usage

Basic Usage

# Simple prompt (auto-detects first installed agent)
shot "explain this code"

# Detect installed agents with versions
shot --detect

# Use specific agent
shot -a codex "refactor this function"

# Use Cursor CLI
shot -a cursor "implement authentication"

# Use specific model
shot -a claude -m claude-3-5-haiku-20241022 "optimize this algorithm"

Model Selection

Each agent supports different models:

Claude Code:

• claude-3-5-sonnet-20241022 (default)
• claude-3-5-haiku-20241022
• claude-3-opus-20240229

Cursor CLI:

• claude-3-5-sonnet-20241022 (default)
• claude-3-5-haiku-20241022
• gpt-4o
• gpt-4-turbo
• o1-preview
• o1-mini

Codex:

• claude-3-5-sonnet-20241022 (default)
• gpt-4o
• gpt-4-turbo
• o1-preview
• o1-mini

AmpCode:

• claude-3-5-sonnet-20241022 (default)
• claude-3-5-haiku-20241022
• gpt-4o
• gpt-4-turbo

Warp:

• gpt-4o (default)
• claude-3-5-sonnet-20241022
• gpt-4-turbo

List available models for an agent:

shot -a codex --list-models

MCP Integration

Enable MCP servers for supported agents (Claude Code, Codex):

# Use with MCP servers
shot -a claude -c filesystem -c github "analyze the repository"

# Setup MCP configuration for an agent
shot -a claude --setup-mcp

# Setup specific MCP servers
shot -a codex -c postgres -c brave --setup-mcp

Available MCP servers:

• filesystem - File system access
• github - GitHub integration (requires GITHUB_TOKEN env var)
• gitmcp - Git operations MCP server
• context7 - Context7 documentation server (requires CONTEXT7_API_KEY)
• rtfmbro - RTFM Bro documentation server
• postgres - PostgreSQL database (requires POSTGRES_URL env var)
• brave - Brave Search (requires BRAVE_API_KEY env var)

Advanced Options

# Inline edit mode (if supported by agent)
shot -a claude -i "fix the bug in this function"

# Verbose output
shot -v "generate unit tests"

# Combine options
shot -a codex -m gpt-4o -c filesystem -v "analyze and improve performance"

Command Line Options

Option	Short	Description
--agent <name>	-a	Agent to use (auto-detects if not specified)
--model <name>	-m	Model to use (agent-specific)
--mcp <server>	-c	Enable MCP server(s)
--inline	-i	Use inline edit mode (if supported)
--list-models	-l	List available models for the agent
--detect	-d	Detect installed agents with versions
--setup-mcp		Setup MCP configuration for the agent
--verbose	-v	Verbose output (shows agent version)
--help	-h	Show help message

Environment Variables

For MCP server integration, set these environment variables:

export GITHUB_TOKEN="your-github-token"
export POSTGRES_URL="postgresql://user:pass@host:port/db"
export BRAVE_API_KEY="your-brave-api-key"

Examples

Code Review

shot -a claude "review this code for security vulnerabilities"

Refactoring

shot -a codex -m gpt-4o "refactor this class to use composition instead of inheritance"

Documentation

shot -a ampcode "generate JSDoc comments for all functions"

Database Query

shot -a codex -c postgres "write a query to find top 10 customers by revenue"

Repository Analysis

shot -a claude -c filesystem -c github "analyze the architecture of this repository"

Requirements

• Bun >= 1.0.0
• TypeScript >= 5.0.0
• Respective AI agent CLI tools installed (claude, codex, ampcode, warp)

Parallel Execution Mode

The parallel mode (shot-parallel.ts) provides advanced features for running multiple agents simultaneously:

Features

• Parallel agent execution with configurable concurrency limits
• Jujutsu workspace isolation for each agent session
• Tmux session management for process isolation
• Automatic MCP combinations testing
• Real-time monitoring dashboard
• Execution timing with detailed performance metrics
• Automatic branch naming based on agent/model/MCP/prompt
• Port management for development servers
• Detailed execution reports in Markdown format

Usage

# Run multiple agents with different models
shot-parallel -a claude -a codex -m claude-3-5-sonnet -m gpt-4o "build authentication"

# Test MCP server combinations
shot-parallel -a claude -c gitmcp -c context7 -c rtfmbro "analyze codebase"

# Full parallel execution with all features
shot-parallel -a claude -a codex -a ampcode \
  -c gitmcp -c context7 \
  -j -d -M -v \
  "implement REST API with authentication"

MCP Combination Testing

When MCP servers are specified, the tool automatically tests:

1. No MCP servers (baseline)
2. All specified MCP servers together
3. Each MCP server individually

This helps identify the optimal MCP configuration for your task.

Branch Management with Jujutsu

Each agent session creates an isolated Jujutsu workspace with automatic branch naming:

<agent>-<model>-<mcp>-<prompt-words>

Example: claude-sonnet-gitmcp-context7-build-rest-api

Execution Reports

After parallel execution, a detailed Markdown report is generated containing:

• Execution times for each agent
• Success/failure status
• Branch names for code review
• MCP configurations used
• Port assignments for dev servers
• Error messages if any

Performance & Timing

All agent executions are timed with precision:

• Start and end timestamps
• Duration in seconds
• Real-time monitoring updates every 2 seconds
• Performance comparison across agents and configurations

Prerequisites

• Bun >= 1.0.0 (runtime and package manager)
• Jujutsu (jj) - For branch management in parallel mode
• Tmux - For session isolation (optional but recommended)
• AI agent CLIs - The respective agents you want to use must be installed

License

MIT