A CLI tool for launching isolated Claude Code development environments inside Docker containers.

• Isolated Containers: Each Claude session runs in its own Docker container
• AWS SSO Integration: Automatic credential injection with SSO login support
• Web Terminal: Browser-based terminal access via ttyd
• Desktop Notifications: Get notified when Claude is waiting for input
• Git Worktrees: Parallel development with automatic worktree management
• Multi-Runtime Support: Works with Docker, Podman, and OrbStack

• Go 1.22 or later
• Docker, Podman, or OrbStack
• AWS CLI v2 (for AWS SSO features)

# Clone the repository
git clone https://github.com/barff/frank.git
cd frank

# Build the CLI
make build

# Or install directly
make install

frank rebuild

1. Set up Claude authentication:

   export CLAUDE_ACCESS_TOKEN="your-token-here"

2. Start a development container:

   frank start --profile dev --repo https://github.com/your/project

3. Open the terminal at http://localhost:8080

4. Stop the container:

   frank stop frank-dev-1

Launch a new development container.

# Basic usage
frank start --profile dev

# With a git repository
frank start --profile dev --repo https://github.com/user/project --branch main

# Mount all AWS profiles
frank start --profile all

# Custom port
frank start --profile dev --port 9000

# Disable notifications
frank start --profile dev --no-notifications

Flags:

• -p, --profile: AWS profile name or "all" for full ~/.aws mount
• -r, --repo: Git repository URL to clone
• -b, --branch: Branch to checkout (default: main)
• -n, --name: Custom container name suffix
• --port: Override starting port
• --no-notifications: Disable notifications
• -d, --detach: Run in background

Show running containers.

frank list              # Running containers
frank list -a           # Include stopped containers
frank list -q           # Only container IDs
frank list --format json  # JSON output

View container logs.

frank logs frank-dev-1        # Last 100 lines
frank logs frank-dev-1 -f     # Follow logs
frank logs frank-dev-1 --tail 50  # Last 50 lines

Execute a command in a container.

frank exec frank-dev-1 bash
frank exec frank-dev-1 git status
frank exec -it frank-dev-1 /bin/bash

Stop containers.

frank stop frank-dev-1         # Stop one container
frank stop --profile dev       # Stop all dev profile containers
frank stop --all               # Stop all frank containers
frank stop --force             # Force stop
frank stop --no-snapshot       # Skip state persistence

Rebuild the container image.

frank rebuild                  # Build with cache
frank rebuild --no-cache       # Build without cache
frank rebuild --tag my-image   # Custom image tag

Configuration file location:

• Linux/macOS: ~/.config/frank/config.yaml
• Windows: %APPDATA%\frank\config.yaml

Example configuration:

version: "1.0"

runtime:
  preferred: auto  # auto, docker, podman, orbstack

container:
  image: frank-dev:latest
  basePort: 8080
  maxPort: 8180

aws:
  autoLogin: true

notifications:
  enabled: true
  cooldown: 30s
  sound: true

mcp:
  servers:
    - name: context7
      enabled: true
    - name: sequential-thinking
      enabled: true
    - name: aws-documentation
      enabled: true

See configs/frank.yaml.example for full configuration options.

# Uses temporary credentials from SSO
frank start --profile dev

If credentials are expired, frank will automatically run aws sso login.

# Mounts entire ~/.aws directory (read-only)
frank start --profile all

Set the CLAUDE_ACCESS_TOKEN environment variable to skip browser authentication:

export CLAUDE_ACCESS_TOKEN="your-token-here"

Frank sends desktop notifications when Claude is waiting for input:

• Questions (lines ending with ?)
• Keywords: continue, approve, proceed, waiting, input, response
• Prompts: [Y/n], (yes/no), "Do you want", etc.

Notifications have a 30-second cooldown to prevent spam.

The container includes pre-configured MCP servers for enhanced Claude capabilities:

The base image includes:

• Claude Code CLI
• ttyd (web terminal)
• git, gh, curl, jq
• AWS CLI v2
• uv (Python package manager)
• Node.js 20 LTS

frank/
├── cmd/                  # CLI commands
├── internal/
│   ├── config/          # Configuration management
│   ├── container/       # Container runtime abstraction
│   ├── aws/             # AWS SSO credential management
│   ├── claude/          # Claude auth & MCP config
│   ├── notification/    # Desktop notifications
│   ├── terminal/        # Port allocation
│   └── git/             # Worktree management
├── build/
│   ├── Dockerfile       # Container image
│   └── entrypoint.sh    # Container entry script
└── configs/             # Configuration examples

Containers are named: frank-<profile>-<index>

Examples:

• frank-dev-1
• frank-prod-2
• frank-all-1

When stopping a container:

1. Git worktrees are cleaned up (unless --no-cleanup)
2. Container state is saved to a timestamped image (unless --no-snapshot)
3. Container is stopped

MIT License