A command-line tool that enables safe execution of AI coding agents in isolated Docker containers. The tool manages the agent's entire lifecycle, from environment setup to the creation of a GitHub Pull Request containing the agent's work.

• Agent agnostic: Runs any command-line based AI agent with preset templates for popular agents
• Isolated execution: Safe Docker container execution with project copying
• "Copy & Push" workflow: Copies your local project to container, agent works on it, and creates PR
• Session management: List, connect, stop, and monitor agent sessions
• Automated PR creation: GitHub integration through GitHub CLI
• Web interface: Full-featured web UI with real-time terminal access via WebSockets
• Agent presets: Built-in templates for popular agents (Qwen, Claude) with environment validation
• Enhanced tmux integration: Proper output handling and connection capabilities
• Container labeling: Track agent details, modes, and project metadata

• Python 3.9+
• Docker
• Git
• GitHub CLI (gh)
• A GitHub token with appropriate permissions
• For web interface: Flask, Flask-SocketIO, and gevent dependencies (installed automatically)

uv tool install agent-ctl

Or for development:

# Install using uv (recommended)
uv tool install -e .

Alternatively, you can use pip:

# Create virtual environment
python -m venv venv
source venv/bin/activate
pip install -e .

agent-ctl includes built-in presets for popular AI agents with templates for both batch and interactive modes:

• Qwen: Supports batch and interactive modes with task templating
• Claude: Full integration with environment validation

You can extend or customize agent presets by creating:

• agent-ctl.yaml in your project directory
• ~/.config/agent-ctl/agents.yaml for user-wide presets

Preset configuration supports:

• Installation commands
• Environment variable requirements
• Mode-specific command templates
• Task templating with {task} placeholder

# Build the default agent Docker image
agent-ctl build-image
# Or manually:
docker build -t default-agent-image:latest .

Launch the web interface for a full-featured GUI experience:

# Start the web server
agent-ctl server --host 127.0.0.1 --port 5000

# Or with custom settings
agent-ctl server --host 0.0.0.0 --port 8080 --debug

The web interface provides:

• Real-time session monitoring
• Interactive terminal connections via WebSockets
• Agent launch interface with preset support
• Session management (connect, stop, logs)

# Set your GitHub token
export GITHUB_TOKEN=your_github_token_here

# Launch Qwen with task templating (uses preset)
agent-ctl launch --agent "qwen" --task "implement authentication module"

# Launch Claude with task templating (uses preset)
agent-ctl launch --agent "claude" --task "fix security vulnerabilities"

# Interactive mode with presets
agent-ctl launch --agent "qwen" --task "analyze codebase" --interactive

# Install agent automatically using preset
agent-ctl launch --agent "qwen" --task "add unit tests" --agent-install "npm install -g @qwen-code/qwen-code@latest"

# Launch with a full agent command (using current directory)
agent-ctl launch --agent "python script.py --do-something"

# Launch with a full agent command (using specific project path)
agent-ctl launch /path/to/your/project --agent "python script.py --do-something"

# Launch with an agent that needs to be installed first
agent-ctl launch /path/to/your/project --agent "claude 'implement feature X'" --agent-install "pip install claude-code"
agent-ctl launch /path/to/your/project --agent "gemini 'fix bug in main.py'" --agent-install "npm install -g @google/gemini-cli"

# Launch with wait/no-wait options (default is --no-wait)
agent-ctl launch /path/to/your/project --agent "qwen -y --prompt 'implement feature X'" --agent-install "npm install -g @qwen-code/qwen-code@latest" --wait      # Wait for completion
agent-ctl launch /path/to/your/project --agent "qwen -y --prompt 'implement feature X'" --agent-install "npm install -g @qwen-code/qwen-code@latest" --no-wait   # Don't wait, run in background (default)

# Launch qwen for read-only analysis (no GitHub token required for read-only operations)
agent-ctl launch /path/to/your/project --agent "qwen --prompt-interactive 'understand the project and give a summary'" --agent-install "npm install -g @qwen-code/qwen-code@latest" --interactive

The web interface provides the best interactive experience with real-time terminal access:

# Start web server
agent-ctl server

# Open browser to http://localhost:5000
# Connect to sessions directly from the web UI

# Launch in interactive mode to manually connect and work with the container
agent-ctl launch /path/to/your/project --agent "bash" --interactive

# Then connect to the session
agent-ctl connect agent-session-20231016-123456

# Connect using session index (auto-detects single active session)
agent-ctl connect

# Connect using index number
agent-ctl connect 1

The web interface provides the most comprehensive session management:

• Real-time session list with status updates
• One-click connection to terminal sessions
• Session details including agent commands and project paths
• Integrated session monitoring and control

# List active sessions with enhanced details
agent-ctl list

# Connect to an active session
agent-ctl connect agent-session-20231016-123456  # Connect using session ID
agent-ctl connect 1                              # Connect using index (1st session in the list)
agent-ctl connect                                # Auto-connect to the only active session (if just one exists)

# Stop a session
agent-ctl stop agent-session-20231016-123456     # Stop using session ID
agent-ctl stop 1                                 # Stop using index (1st session in the list)
agent-ctl stop                                   # Auto-stop the only active session (if just one exists)

# Stop all active sessions
agent-ctl stop-all

# View logs of a session
agent-ctl logs agent-session-20231016-123456    # View logs using session ID
agent-ctl logs 1                                  # View logs using index (1st session in the list)
agent-ctl logs                                    # Auto-view logs of the only active session (if just one exists)

Sessions now include enhanced metadata:

• Agent command and installation details
• Mode (batch/interactive)
• Project path and remote URL
• Creation timestamp
• Agent name (for preset-based agents)
• Task description (for templated agents)

Sessions are ordered consistently by creation time, ensuring that index numbers remain stable across command invocations. The list command shows sessions with index numbers that correspond to the indices you can use with the connect and stop commands.

1. Validation: agent-ctl validates the project directory is a Git repository
2. Preset Resolution: If using a preset agent (e.g., "qwen", "claude"), resolve templates and environment requirements
3. Container Setup: Build a Docker container from the default image containing necessary tools (git, tmux, gh, etc.)
4. Project Copy: Your project directory is copied to the container's workspace
5. Agent Installation: Install the agent in the container if an installation command is provided
6. Session Management: Start a tmux session with enhanced output handling and metadata labeling
7. Agent Execution: Run your agent command in both batch and interactive modes
8. Result Handling: When the agent finishes (in batch mode), changes are committed to a new branch and a PR is created
9. Cleanup: Container is automatically cleaned up (in batch mode)

1. Web Server: Start the Flask-based web server with WebSocket support
2. Real-time Communication: Full-duplex communication for terminal access and session monitoring
3. Interactive Terminal: WebSocket-based terminal emulation for direct container access
4. Session Management: Real-time session list updates and management through the web interface

• Container Labeling: All sessions include comprehensive metadata labels for better tracking
• Environment Handling: Automatic loading of .env files and environment variable validation
• Preset System: Built-in templates for popular agents with environment requirement checking
• WebSocket Integration: Real-time terminal access and session monitoring
• Enhanced Output Handling: Improved tmux integration with proper output redirection

The tool ensures complete isolation between the AI agent and the developer's system while providing the agent with a full copy of the project context. All agent commands run inside tmux, which allows for consistent behavior, output capture, and connection capabilities in both batch and interactive modes.

The following agents have built-in presets:

agents:
  qwen:
    install: "npm install -g @qwen-code/qwen-code@latest"
    required_env: []
    templates:
      batch: "qwen -y --prompt '{task}'"
      interactive: "qwen --prompt-interactive '{task}'"

agents:
  claude:
    install: "pip install claude-code"
    required_env: ["ANTHROPIC_API_KEY"]
    templates:
      batch: "claude -y --prompt '{task}'"
      interactive: "claude --prompt-interactive '{task}'"

Create custom agent configurations in:

1. Project-level: agent-ctl.yaml in your project directory
2. User-level: ~/.config/agent-ctl/agents.yaml for global presets

# agent-ctl.yaml
agents:
  custom-agent:
    install: "npm install -g custom-agent-cli"
    required_env: ["CUSTOM_API_KEY", "CUSTOM_CONFIG"]
    templates:
      batch: "custom-agent --batch --task '{task}' --output-format json"
      interactive: "custom-agent --interactive"

• Required Environment: Presets can specify required environment variables that are validated before launch
• .env File Support: Automatically loads environment variables from .env files in your project
• Environment Merging: Combines system environment, .env file, and preset requirements
• Validation Warnings: Shows warnings for missing required environment variables

Run the test suite to verify the web server functionality:

# Test the web server module
python test_server.py

This tests:

• Server module imports correctly
• API routes are accessible
• Session management endpoints work properly

On macOS with Docker Desktop, agent-ctl may have trouble connecting to the Docker daemon. If you encounter connection errors, you may need to create a symbolic link for the Docker socket.

Run the following command in your terminal:

sudo ln -s /Users/$USER/.docker/run/docker.sock /var/run/docker.sock