aircon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7a82194933fb47bffb6daacf310c4f244ab1d9a25db2f9b32ec25edd578c4a06
+  data.tar.gz: 0222cec49d295996c4066d56518ee84fff8747c8189713f4581a17e103ac8c61
+SHA512:
+  metadata.gz: 937ab4b996d225743372ed6d5c25fe319c2305dfd84bca24b95671465ae1846ab20043f2ad7e442096e09cb060840e2a2bd948b5b723932469bb99f744c85dd4
+  data.tar.gz: 7623f3fd28dd5adffbd85908447c1d5e640a952a9eb2c27d0c31f8de7f2407d76a22762f34f50b0f3f4aab3fe750b5e34e33cc69fdb29575804bee222aa02629

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Philip Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,249 @@
+# Aircon
+
+No more worktrees. Aircon gives every feature branch its own isolated Docker container pre-loaded with Claude Code, your credentials, and a running shell — so you can work on multiple branches in parallel without them stepping on each other. Dependencies like databases are isolated, so a db migration in one container does not affect the other.
+
+Each container gets:
+- Your Claude Code credentials and settings injected at startup (no Dockerfile changes needed)
+- Claude Code installed automatically if not already in the image
+- Your GitHub token set for authenticated `git` and `gh` operations
+- A git branch checked out and ready to go
+- An optional project-specific init script that runs after the container is up
+
+When you close the last shell session, the container and its volumes are automatically torn down.
+
+---
+
+## Prerequisites
+
+- Ruby >= 3.3.0
+- Docker and Docker Compose
+- Claude Code installed on your host machine (aircon copies credentials from it)
+- VS Code with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension (only needed for `aircon vscode`)
+
+---
+
+## Installation
+
+```bash
+gem install aircon
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "aircon"
+```
+
+---
+
+## Getting Started
+
+**1. Initialize aircon in your project:**
+
+```bash
+cd your-project
+aircon init
+```
+
+This creates four files under `.aircon/`:
+
+| File | Purpose |
+|------|---------|
+| `aircon.yml` | Main config (tokens, paths, user settings) |
+| `aircon_init.sh` | Script run inside the container after setup |
+| `Dockerfile` | Base image for your dev container, change it or use your own |
+| `docker-compose.yml` | Compose config wired to the Dockerfile, change it or use your own |
+
+Existing files are never overwritten, so `aircon init` is safe to re-run.
+
+**2. Configure your tokens:**
+
+Edit `.aircon/aircon.yml` and set at minimum:
+
+```yaml
+gh_token: <%= ENV['GITHUB_TOKEN'] %>
+```
+
+**3. Start a container:**
+
+```bash
+aircon up my-feature
+```
+
+This builds the image, injects your Claude credentials, checks out a branch named `my-feature`, runs your init script, and drops you into a shell inside the container. The container and dependencies set in the docker-compose file will all be running under the `my-feature` docker project, fully isolating it from other containers.
+
+---
+
+## Commands
+
+### `aircon up NAME [PORT]`
+
+Start or attach to a dev container.
+
+```bash
+aircon up my-feature               # start on default port 3001
+aircon up my-feature 3005          # start on port 3005
+aircon up my-feature -b feat/auth  # use a different git branch than NAME
+aircon up my-feature -d            # start detached (no interactive shell)
+```
+
+**What `aircon up` does, step by step:**
+
+1. Looks for an existing container named `NAME-SERVICE-1` (e.g. `my-feature-app-1`).
+   - If found → attaches a new `bash` session to it and skips to step 12.
+2. Warns if `gh_token` is not configured.
+3. Runs `docker compose up -d --build` with `HOST_PORT`, `AIRCON_APP_NAME`, `AIRCON_CONTAINER_USER`, and `AIRCON_WORKSPACE_PATH` injected as environment variables.
+4. Copies `~/.claude.json` and `~/.claude/` from your host into the container via `docker cp` (no `COPY` lines needed in your Dockerfile). Host home paths inside those files are rewritten to match the container home directory.
+5. Installs Claude Code inside the container if not already present (`curl -fsSL https://claude.ai/install.sh | bash`).
+6. Adds `~/.local/bin` to `PATH` in `/etc/bash.bashrc` so `claude` is available in all sessions.
+7. Writes `GH_TOKEN` and `GITHUB_PERSONAL_ACCESS_TOKEN` to `/etc/bash.bashrc` (if `gh_token` is set).
+8. Writes `CLAUDE_CODE_OAUTH_TOKEN` to `/etc/bash.bashrc` (if configured).
+9. Sets `git config user.email` and `git config user.name` globally inside the container.
+10. Configures `git` to authenticate GitHub URLs with your token (covers both `https://github.com/` and `git@github.com:`).
+11. Checks out the branch:
+    - If the branch exists on `origin` → fetches and checks it out.
+    - Otherwise → creates a new branch from `origin/main`.
+12. Runs the `init_script` (`.aircon/aircon_init.sh` by default) inside the container via `bash -l`, if the file exists.
+13. Attaches an interactive `bash` session.
+14. When the last `bash` session exits → runs `docker compose down -v --remove-orphans` and `docker image prune -f`.
+
+**Options:**
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--branch BRANCH` | `-b` | Git branch to check out (defaults to NAME) |
+| `--detach` | `-d` | Start without attaching an interactive session |
+
+---
+
+### `aircon down NAME`
+
+Tear down the container and volumes for a project.
+
+```bash
+aircon down my-feature
+```
+
+Runs `docker compose down -v --remove-orphans` and prunes unused images. Use this to clean up manually if you need to reset state without waiting for a session to end.
+
+---
+
+### `aircon vscode NAME`
+
+Attach VS Code to a running container.
+
+```bash
+aircon vscode my-feature
+```
+
+The container must already be running (`aircon up` first). Opens VS Code connected to the container via the Dev Containers extension, with the workspace set to `workspace_path`.
+
+---
+
+### `aircon init`
+
+Generate the `.aircon/` config files in the current directory.
+
+```bash
+aircon init
+```
+
+Creates `aircon.yml`, `aircon_init.sh`, `Dockerfile`, and `docker-compose.yml` under `.aircon/`. Safe to re-run — existing files are not overwritten.
+
+---
+
+### `aircon version`
+
+Print the installed version.
+
+```bash
+aircon version
+```
+
+---
+
+## Configuration
+
+Config is loaded from `.aircon/aircon.yml` in your project root. All keys are optional. ERB is supported, so you can pull in environment variables.
+
+```yaml
+# Docker Compose file to use
+compose_file: .aircon/docker-compose.yml
+
+# Application name — used for DB credentials in the default Compose template
+# Defaults to the basename of the current directory
+app_name: my-app
+
+# GitHub personal access token — authenticates git and gh inside the container
+gh_token: <%= ENV['GITHUB_TOKEN'] %>
+
+# Claude Code OAuth token — set as CLAUDE_CODE_OAUTH_TOKEN inside the container
+claude_code_oauth_token: <%= ENV['CLAUDE_CODE_OAUTH_TOKEN'] %>
+
+# Workspace folder path inside the container
+workspace_path: /my-app
+
+# Path to your Claude config file on the host
+claude_config_path: ~/.claude.json
+
+# Path to your Claude directory on the host
+claude_dir_path: ~/.claude
+
+# Docker Compose service name
+service: app
+
+# Git identity inside the container
+git_email: claude_docker@localhost.com
+git_name: Claude Docker
+
+# Non-root user inside the container (determines home directory)
+container_user: appuser
+
+# Script to run inside the container after setup (path relative to this file)
+init_script: .aircon/aircon_init.sh
+```
+
+### Configuration Reference
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `compose_file` | `.aircon/docker-compose.yml` | Docker Compose file to use |
+| `app_name` | basename of cwd | App name passed to Compose as `AIRCON_APP_NAME` |
+| `gh_token` | `nil` | GitHub token; sets `GH_TOKEN` and `GITHUB_PERSONAL_ACCESS_TOKEN` in the container |
+| `claude_code_oauth_token` | `nil` | Claude Code OAuth token; sets `CLAUDE_CODE_OAUTH_TOKEN` in the container |
+| `workspace_path` | `/workspace` | Workspace folder path inside the container |
+| `claude_config_path` | `~/.claude.json` | Host path to `claude.json` |
+| `claude_dir_path` | `~/.claude` | Host path to `.claude/` directory |
+| `service` | `app` | Docker Compose service name for the main container |
+| `git_email` | `claude_docker@localhost.com` | Git author email inside the container |
+| `git_name` | `Claude Docker` | Git author name inside the container |
+| `container_user` | `appuser` | Non-root user inside the container |
+| `init_script` | `.aircon/aircon_init.sh` | Script run after setup; has access to `GH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, etc. |
+
+---
+
+## Notes
+
+- SSH keys are not managed by aircon — handle them in your `init_script` if needed.
+- Your `Dockerfile` does not need `COPY` instructions for Claude settings; aircon injects them at runtime via `docker cp`.
+- The Docker Compose project name is set to `NAME` (the argument to `aircon up`), so the container will be named `NAME-SERVICE-1` (e.g. `my-feature-app-1`). This is how aircon identifies containers across commands.
+
+---
+
+## Releasing to RubyGems
+
+1. Bump the version in `lib/aircon/version.rb`.
+2. Build and push:
+
+```bash
+gem build aircon.gemspec
+gem push aircon-<version>.gem
+```
+
+You'll be prompted for your RubyGems credentials on first push. Subsequent pushes use the stored API key at `~/.gem/credentials`.
+
+---
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/exe/aircon

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "aircon"
+
+Aircon::CLI.start(ARGV)

data/lib/aircon/cli.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "thor"
+
+module Aircon
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "up NAME [PORT]", "Start or attach to a dev container for the given project"
+    method_option :detach, type: :boolean, default: false, aliases: "-d",
+                           desc: "Start container without attaching an interactive session"
+    method_option :branch, type: :string, aliases: "-b",
+                           desc: "Git branch to check out (defaults to NAME)"
+    def up(name, port = "3001")
+      config = Configuration.new
+      branch = options[:branch] || name
+      Commands::Up.new(config: config).call(name, branch: branch, port: port, detach: options[:detach])
+    end
+
+    desc "down NAME", "Tear down the container and volumes for the given project"
+    def down(name)
+      config = Configuration.new
+      Commands::Down.new(config: config).call(name)
+    end
+
+    desc "vscode NAME", "Attach VS Code to a running container for the given project"
+    def vscode(name)
+      config = Configuration.new
+      Commands::Vscode.new(config: config).call(name)
+    end
+
+    desc "init", "Create a sample .aircon/aircon.yml, Dockerfile, and docker-compose.yml in the current directory"
+    def init
+      FileUtils.mkdir_p(File.join(Dir.pwd, ".aircon"))
+
+      {
+        "aircon.yml" => SAMPLE_CONFIG,
+        "aircon_init.sh" => INIT_SCRIPT_TEMPLATE,
+        "Dockerfile" => DOCKERFILE_TEMPLATE,
+        "docker-compose.yml" => COMPOSE_TEMPLATE
+      }.each do |filename, content|
+        path = File.join(Dir.pwd, ".aircon", filename)
+        if File.exist?(path)
+          puts "Skipped .aircon/#{filename} (already exists)"
+        else
+          File.write(path, content)
+          puts "Created .aircon/#{filename}"
+        end
+      end
+    end
+
+    desc "version", "Show aircon version"
+    def version
+      puts "aircon #{VERSION}"
+    end
+
+    SAMPLE_CONFIG = <<~'YAML'
+      # Aircon configuration — ERB is supported (e.g. <%= ENV['GITHUB_TOKEN'] %>)
+      # See: https://github.com/creativesorcery/aircon
+
+      # Docker Compose file to use (default: .aircon/docker-compose.yml)
+      # compose_file: .aircon/docker-compose.yml
+
+      # Application name used for database credentials etc. (default: directory basename)
+      # app_name: myapp
+
+      # GitHub personal access token (supports ERB)
+      # gh_token: <%= ENV['GITHUB_TOKEN'] %>
+
+      # Claude Code OAuth token (supports ERB)
+      # claude_code_oauth_token: <%= ENV['CLAUDE_CODE_OAUTH_TOKEN'] %>
+
+      # Workspace folder path inside the container
+      # workspace_path: /myproject
+
+      # Path to host's Claude config file
+      # claude_config_path: ~/.claude.json
+
+      # Path to host's Claude directory
+      # claude_dir_path: ~/.claude
+
+      # Docker Compose service name for the main container
+      # service: app
+
+      # Git author identity inside the container
+      # git_email: claude_docker@localhost.com
+      # git_name: Claude Docker
+
+      # Non-root user inside the container
+      # container_user: appuser
+
+      # Script to run inside the container after setup (path relative to project root)
+      # Defaults to .aircon/aircon_init.sh — edit that file to add your setup steps.
+      # init_script: .aircon/aircon_init.sh
+    YAML
+
+    INIT_SCRIPT_TEMPLATE = <<~'BASH'
+      #!/bin/bash
+      # .aircon/aircon_init.sh
+      #
+      # This script runs inside the container after aircon completes its setup.
+      # It is invoked as a login shell (bash -l), so environment variables
+      # configured by aircon are available:
+      #
+      #   GH_TOKEN / GITHUB_PERSONAL_ACCESS_TOKEN  — GitHub personal access token
+      #   CLAUDE_CODE_OAUTH_TOKEN                  — Claude Code OAuth token
+      #   PATH                                     — includes ~/.local/bin (claude, gh, etc.)
+      #
+      # The working directory is the repository root inside the container.
+      #
+      # Examples:
+      #   npm install
+      #   bundle install
+      #   cp .env.example .env
+    BASH
+
+    DOCKERFILE_TEMPLATE = <<~'DOCKERFILE'
+      FROM ruby:4.0.1
+
+      RUN curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
+
+      # Add GitHub CLI repository
+      RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+          && chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
+          && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null
+
+      # Install dependencies
+      RUN apt-get update -qq && \
+          apt-get install -y --no-install-recommends \
+          bash \
+          build-essential \
+          git \
+          libpq-dev \
+          postgresql-client \
+          curl \
+          libvips \
+          bubblewrap \
+          socat \
+          nodejs \
+          gh \
+          && rm -rf /var/lib/apt/lists/*
+
+      # Make /bin/sh point to bash instead of dash (required for devcontainer features)
+      RUN ln -sf /bin/bash /bin/sh
+
+      # Ensure bash is the default shell for RUN commands
+      SHELL ["/bin/bash", "-c"]
+
+      # Create a non-root user
+      ARG USERNAME=appuser
+      ARG USER_UID=1000
+      ARG USER_GID=$USER_UID
+      ARG WORKSPACE_PATH=/workspace
+
+      RUN groupadd --gid $USER_GID $USERNAME \
+      && useradd --uid $USER_UID --gid $USER_GID -m $USERNAME \
+      && apt-get update \
+      && apt-get install -y sudo \
+      && echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME \
+      && chmod 0440 /etc/sudoers.d/$USERNAME \
+      && rm -rf /var/lib/apt/lists/*
+
+      # Give the container user write access to the gem directory
+      RUN chown -R $USER_UID:$USER_GID /usr/local/bundle
+
+      RUN npm install -g @anthropic-ai/sandbox-runtime
+      RUN npm install -g yarn
+      RUN npm install -g playwright@1.58.1
+      RUN playwright install --with-deps chromium
+
+      COPY --chown=$USERNAME:$USERNAME . $WORKSPACE_PATH
+
+      USER $USERNAME
+
+      RUN playwright install chromium
+
+      WORKDIR $WORKSPACE_PATH
+
+      RUN bundle install
+    DOCKERFILE
+
+    COMPOSE_TEMPLATE = <<~'YAML'
+      services:
+        app:
+          build:
+            context: ..
+            dockerfile: .aircon/Dockerfile
+            args:
+              USERNAME: ${AIRCON_CONTAINER_USER:-appuser}
+              WORKSPACE_PATH: ${AIRCON_WORKSPACE_PATH:-/workspace}
+          ports:
+            - "${HOST_PORT:-3001}:3000"
+          command: sleep infinity
+          environment:
+            DATABASE_HOST: db
+            DATABASE_USER: ${AIRCON_APP_NAME:-app}
+            RAILS_ENV: development
+            RAILS_BIND: 0.0.0.0
+          depends_on:
+            db:
+              condition: service_started
+
+        db:
+          image: postgres:18
+          restart: unless-stopped
+          environment:
+            POSTGRES_USER: ${AIRCON_APP_NAME:-app}
+            POSTGRES_HOST_AUTH_METHOD: trust
+            POSTGRES_DB: ${AIRCON_APP_NAME:-app}_development
+    YAML
+  end
+end

data/lib/aircon/commands/down.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Aircon
+  module Commands
+    class Down
+      def initialize(config:)
+        @config = config
+      end
+
+      def call(name)
+        puts "Tearing down containers for '#{name}'..."
+        system("docker", "compose", "-p", name, "down", "-v", "--remove-orphans")
+        system("docker", "image", "prune", "-f")
+      end
+    end
+  end
+end

data/lib/aircon/commands/up.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "tmpdir"
+
+module Aircon
+  module Commands
+    class Up
+      def initialize(config:)
+        @config = config
+      end
+
+      def call(name, branch:, port: "3001", detach: false)
+        container = Docker.find_container(project: name, service: @config.service)
+
+        if container
+          attach_existing(container, name, detach: detach)
+        else
+          start_new(name, branch, port, detach: detach)
+        end
+      end
+
+      private
+
+      def attach_existing(container, name, detach: false)
+        if detach
+          puts "Container for '#{name}' is already running: #{container}"
+          return
+        end
+
+        puts "Attaching to existing container for '#{name}'..."
+        system("docker", "exec", "-it", container, "bash")
+        cleanup_if_last(container, name)
+      end
+
+      def start_new(name, branch, port, detach: false)
+        if @config.gh_token.nil? || @config.gh_token.to_s.empty?
+          warn "Warning: gh_token not configured. GitHub CLI (gh) will not be authenticated."
+          warn "  Set gh_token in .aircon.yml if you want to use 'gh' commands."
+        end
+
+        env = {
+          "HOST_PORT" => port.to_s,
+          "AIRCON_APP_NAME" => @config.app_name,
+          "AIRCON_CONTAINER_USER" => @config.container_user,
+          "AIRCON_WORKSPACE_PATH" => @config.workspace_path
+        }
+        system(env, "docker", "compose",
+               "-f", @config.compose_file,
+               "-p", name,
+               "up", "-d", "--build")
+
+        container = Docker.find_container(project: name, service: @config.service)
+        abort "Error: Could not find container after starting services." unless container
+
+        inject_claude_settings(container)
+        setup_container(container, branch)
+        run_init_script(container)
+
+        if detach
+          puts "Container started: #{container}"
+          return
+        end
+
+        system("docker", "exec", "-it", container, "bash")
+        cleanup_if_last(container, name)
+      end
+
+      def inject_claude_settings(container)
+        Dir.mktmpdir("aircon_claude_settings") do |staging|
+          claude_config = File.expand_path(@config.claude_config_path)
+          claude_dir = File.expand_path(@config.claude_dir_path)
+
+          FileUtils.cp(claude_config, File.join(staging, ".claude.json")) if File.exist?(claude_config)
+
+          if File.directory?(claude_dir)
+            FileUtils.cp_r(claude_dir, File.join(staging, ".claude"))
+          else
+            FileUtils.mkdir_p(File.join(staging, ".claude"))
+          end
+
+          home = @config.container_home
+          rewrite_paths(staging, home)
+          user = @config.container_user
+          system("docker", "cp", "#{File.join(staging, '.claude')}/.", "#{container}:#{home}/.claude")
+          system("docker", "cp", File.join(staging, ".claude.json"), "#{container}:#{home}/.claude.json")
+          system("docker", "exec", "-u", "root", container,
+                 "bash", "-c", "chmod -R u+rwX #{home}/.claude #{home}/.claude.json && " \
+                               "chown -R #{user}:#{user} #{home}/.claude #{home}/.claude.json")
+        end
+      end
+
+      def rewrite_paths(staging, container_home)
+        host_home = File.expand_path("~")
+
+        Dir.glob(File.join(staging, "**", "*"), File::FNM_DOTMATCH).each do |path|
+          next unless File.file?(path)
+          next unless File.readable?(path)
+
+          content = File.binread(path)
+          next unless content.valid_encoding?
+          next unless content.include?(host_home)
+
+          File.write(path, content.gsub(host_home, container_home))
+        end
+      end
+
+      def setup_container(container, branch)
+        home = @config.container_home
+
+        # Install Claude Code if not already present, and ensure it's on PATH for all shells
+        system("docker", "exec", container, "bash", "-c",
+               "command -v claude >/dev/null 2>&1 || curl -fsSL https://claude.ai/install.sh | bash")
+        system("docker", "exec", "-u", "root", container, "bash", "-c",
+               "grep -qF '#{home}/.local/bin' /etc/bash.bashrc 2>/dev/null || " \
+               "echo 'export PATH=\"#{home}/.local/bin:$PATH\"' >> /etc/bash.bashrc")
+
+        if @config.gh_token && !@config.gh_token.to_s.empty?
+          system("docker", "exec", "-u", "root", container, "bash", "-c",
+                 "grep -qF 'export GH_TOKEN=' /etc/bash.bashrc 2>/dev/null || " \
+                 "echo 'export GH_TOKEN=\"#{@config.gh_token}\"' >> /etc/bash.bashrc")
+          system("docker", "exec", "-u", "root", container, "bash", "-c",
+                 "grep -qF 'export GITHUB_PERSONAL_ACCESS_TOKEN=' /etc/bash.bashrc 2>/dev/null || " \
+                 "echo 'export GITHUB_PERSONAL_ACCESS_TOKEN=\"#{@config.gh_token}\"' >> /etc/bash.bashrc")
+        end
+
+        if @config.claude_code_oauth_token && !@config.claude_code_oauth_token.to_s.empty?
+          system("docker", "exec", "-u", "root", container, "bash", "-c",
+                 "grep -qF 'export CLAUDE_CODE_OAUTH_TOKEN=' /etc/bash.bashrc 2>/dev/null || " \
+                 "echo 'export CLAUDE_CODE_OAUTH_TOKEN=\"#{@config.claude_code_oauth_token}\"' >> /etc/bash.bashrc")
+        end
+
+        # Configure git and create branch
+        system("docker", "exec", container, "git", "config", "--global", "user.email", @config.git_email)
+        system("docker", "exec", container, "git", "config", "--global", "user.name", @config.git_name)
+        # Configure git authentication for GitHub using the personal access token
+        if @config.gh_token && !@config.gh_token.to_s.empty?
+          authed = "https://x-access-token:#{@config.gh_token}@github.com/"
+          system("docker", "exec", container, "git", "config", "--global",
+                 "url.#{authed}.insteadOf", "https://github.com/")
+          system("docker", "exec", container, "git", "config", "--global",
+                 "url.#{authed}.insteadOf", "git@github.com:")
+        end
+        # Check if branch exists on remote; if so, check it out, otherwise create new
+        _, status = Open3.capture2("docker", "exec", container, "git", "ls-remote", "--heads", "origin", branch)
+        if status.success? && !_.strip.empty?
+          system("docker", "exec", container, "git", "fetch", "origin", branch)
+          system("docker", "exec", container, "git", "checkout", "-b", branch, "origin/#{branch}")
+        else
+          system("docker", "exec", container, "git", "fetch", "origin", "main")
+          system("docker", "exec", container, "git", "checkout", "-b", branch, "origin/main")
+        end
+
+        # If you have the official anthropic marketplace plugin installed, it will always make a call to the anthropic github repo on claude startup. It uses SSH, but it should be https for universal compatibility since its a public repository.
+        system("docker", "exec", container, "git", "config", "--global", "url.\"https://github.com/anthropics/\".insteadOf", "ssh://git@github.com/anthropics/")
+      end
+
+      def run_init_script(container)
+        return unless @config.init_script && !@config.init_script.to_s.empty?
+
+        script_path = File.expand_path(@config.init_script)
+        unless File.exist?(script_path)
+          warn "Warning: init_script '#{@config.init_script}' not found, skipping."
+          return
+        end
+
+        home = @config.container_home
+        remote_script = "#{home}/.aircon_init.sh"
+        system("docker", "cp", script_path, "#{container}:#{remote_script}")
+        system("docker", "exec", container, "bash", "-l", remote_script)
+      end
+
+      def cleanup_if_last(container, name)
+        out, = Open3.capture2("docker", "exec", container, "pgrep", "-x", "bash")
+        remaining = out.strip.lines.size
+
+        return unless remaining == 0
+
+        puts "Last session ended. Cleaning up..."
+        system("docker", "compose", "-p", name, "down", "-v", "--remove-orphans")
+        system("docker", "image", "prune", "-f")
+      end
+    end
+  end
+end

data/lib/aircon/commands/vscode.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Aircon
+  module Commands
+    class Vscode
+      def initialize(config:)
+        @config = config
+      end
+
+      def call(name)
+        container = Docker.find_container(project: name, service: @config.service)
+
+        unless container
+          abort "Error: No running container found for project '#{name}'.\n" \
+                "Start one first with: aircon up #{name}"
+        end
+
+        hex_id = Docker.hex_encode_id(container)
+        folder_uri = "vscode-remote://attached-container+#{hex_id}#{@config.workspace_path}"
+
+        puts "Attaching VS Code to container #{container} for project '#{name}'..."
+        system("code", "--folder-uri", folder_uri)
+      end
+    end
+  end
+end

data/lib/aircon/configuration.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "erb"
+
+module Aircon
+  class Configuration
+    CONFIG_FILE = ".aircon/aircon.yml"
+
+    DEFAULTS = {
+      "compose_file" => ".aircon/docker-compose.yml",
+      "app_name" => nil,
+      "gh_token" => nil,
+      "claude_code_oauth_token" => nil,
+      "workspace_path" => nil,
+      "claude_config_path" => "~/.claude.json",
+      "claude_dir_path" => "~/.claude",
+      "service" => "app",
+      "git_email" => "claude_docker@localhost.com",
+      "git_name" => "Claude Docker",
+      "container_user" => "appuser",
+      "init_script" => ".aircon/aircon_init.sh"
+    }.freeze
+
+    attr_reader :compose_file, :app_name, :gh_token, :claude_code_oauth_token, :workspace_path,
+                :claude_config_path, :claude_dir_path, :service, :git_email, :git_name,
+                :container_user, :init_script
+
+    def initialize(dir: Dir.pwd)
+      attrs = DEFAULTS.dup
+      config_path = File.join(dir, CONFIG_FILE)
+
+      if File.exist?(config_path)
+        raw = File.read(config_path)
+        rendered = ERB.new(raw).result
+        user_attrs = YAML.safe_load(rendered) || {}
+        attrs.merge!(user_attrs)
+      end
+
+      @compose_file = attrs["compose_file"]
+      @app_name = attrs["app_name"] || File.basename(dir)
+      @gh_token = attrs["gh_token"]
+      @claude_code_oauth_token = attrs["claude_code_oauth_token"]
+      @workspace_path = attrs["workspace_path"] || "/workspace"
+      @claude_config_path = attrs["claude_config_path"]
+      @claude_dir_path = attrs["claude_dir_path"]
+      @service = attrs["service"]
+      @git_email = attrs["git_email"]
+      @git_name = attrs["git_name"]
+      @container_user = attrs["container_user"]
+      @init_script = attrs["init_script"]
+    end
+
+    def container_home
+      @container_user == "root" ? "/root" : "/home/#{@container_user}"
+    end
+  end
+end

data/lib/aircon/docker.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Aircon
+  module Docker
+    module_function
+
+    def find_container(project:, service:)
+      out, _, status = Open3.capture3(
+        "docker", "ps", "-q",
+        "--filter", "label=com.docker.compose.project=#{project}",
+        "--filter", "label=com.docker.compose.service=#{service}"
+      )
+      return nil unless status.success?
+
+      id = out.strip.lines.first&.strip
+      id.nil? || id.empty? ? nil : id
+    end
+
+    def hex_encode_id(container_id)
+      container_id.each_byte.map { |b| format("%02x", b) }.join
+    end
+  end
+end

data/lib/aircon/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Aircon
+  VERSION = "0.1.0"
+end

data/lib/aircon.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "aircon/version"
+require "aircon/configuration"
+require "aircon/docker"
+require "aircon/commands/up"
+require "aircon/commands/down"
+require "aircon/commands/vscode"
+require "aircon/cli"

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: aircon
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Nguyen
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: fakefs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Aircon spins up one Docker Compose environment per git branch, injects
+  Claude Code credentials, and attaches an interactive shell or VS Code.
+email:
+- 5519675+philipqnguyen@users.noreply.github.com
+executables:
+- aircon
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/aircon
+- lib/aircon.rb
+- lib/aircon/cli.rb
+- lib/aircon/commands/down.rb
+- lib/aircon/commands/up.rb
+- lib/aircon/commands/vscode.rb
+- lib/aircon/configuration.rb
+- lib/aircon/docker.rb
+- lib/aircon/version.rb
+homepage: https://github.com/creativesorcery/aircon
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.5
+specification_version: 4
+summary: Manage Docker-based isolated Claude Code development containers
+test_files: []