Add configuration file feature

.contagent.example.yaml

@@ -0,0 +1,83 @@
+# Example contagent configuration file
+#
+# This file demonstrates all available configuration options for contagent.
+# Place this file in your project root as .contagent.yaml to customize
+# container behavior for your project.
+#
+# Configuration resolution order:
+#   1. Hardcoded defaults
+#   2. Global config (~/.config/contagent/config.yaml)
+#   3. Project config (.contagent.yaml) - this file
+#   4. CLI flags (final override)
+
+# Image name for the container
+# Default: contagent:latest
+image: contagent:latest
+
+# Working directory inside the container
+# Default: /app
+working_dir: /app
+
+# Path to Dockerfile for building the container image
+# Default: (none, must be specified via CLI or config)
+# dockerfile: ./Dockerfile
+
+# Docker network to use for the container
+# Default: default
+network: default
+
+# Container stop timeout in seconds
+# Default: 10
+stop_timeout: 10
+
+# Number of TTY resize retry attempts
+# Default: 10
+tty_retries: 10
+
+# Delay between TTY resize retries
+# Accepts duration strings like "10ms", "100ms", "1s"
+# Default: 10ms
+retry_delay: 10ms
+
+# Git configuration
+git:
+  user:
+    # Git user name for commits made in the container
+    # Default: Contagent
+    name: Contagent
+    # Git user email for commits made in the container
+    # Default: contagent@example.com
+    email: contagent@example.com
+
+# Environment variables to pass to the container
+# These are merged with CLI --env flags (CLI flags take precedence)
+# Supports variable expansion using $VAR or ${VAR} syntax
+env:
+  # Example: Set a custom variable
+  # MY_PROJECT_VAR: some_value
+
+  # Example: Reference host environment variables
+  # MY_PATH: $HOME/bin
+  # USER_DIR: ${HOME}/${USER}
+
+# Volume mounts for the container
+# Format: HOST_PATH:CONTAINER_PATH
+# These are appended to CLI --volume flags
+# Supports variable expansion using $VAR or ${VAR} syntax
+volumes:
+  # Example: Mount a local cache directory
+  # - $HOME/.cache:/root/.cache
+
+  # Example: Mount additional project directories
+  # - ./data:/data
+  # - ./config:/config
+
+# Note: The following are always automatically mounted:
+#   - /var/run/docker.sock:/var/run/docker.sock (Docker socket)
+#   - /run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock (SSH agent)
+#
+# The following environment variables are always passed through:
+#   - TERM (defaults to xterm-256color)
+#   - COLORTERM (defaults to truecolor)
+#   - ANTHROPIC_API_KEY
+#   - SSH_AUTH_SOCK (set to /run/host-services/ssh-auth.sock)

README.md

@@ -106,31 +106,180 @@ Host Machine                          Container (contagent-1234)
 
 ## Configuration
 
+`contagent` supports flexible configuration through multiple sources, allowing you to customize behavior at different levels.
+
+### Configuration Resolution Order
+
+Configuration is merged in the following order (later sources override earlier ones):
+
+1. **Hardcoded defaults**
+2. **Global config** (`~/.config/contagent/config.yaml`)
+3. **Project config** (`.contagent.yaml` in project root)
+4. **CLI flags** (final override)
+
+### Configuration Files
+
+Configuration files use YAML format and support all available settings.
+
+#### Project Configuration
+
+Create a `.contagent.yaml` file in your project root to set project-specific defaults:
+
+```yaml
+# Basic container settings
+image: contagent:latest
+working_dir: /app
+dockerfile: ./Dockerfile
+network: default
+stop_timeout: 10
+tty_retries: 10
+retry_delay: 10ms
+
+# Git configuration
+git:
+  user:
+    name: Contagent
+    email: contagent@example.com
+
+# Environment variables
+# Supports variable expansion using $VAR or ${VAR} syntax
+env:
+  MY_PROJECT_VAR: some_value
+  MY_PATH: $HOME/bin
+  USER_DIR: ${HOME}/${USER}
+
+# Volume mounts (HOST_PATH:CONTAINER_PATH)
+# Supports variable expansion
+volumes:
+  - $HOME/.cache:/root/.cache
+  - ./data:/data
+```
+
+See [.contagent.example.yaml](./.contagent.example.yaml) for a complete example with all available options.
+
+#### Global Configuration
+
+Create `~/.config/contagent/config.yaml` to set user-level defaults that apply across all projects:
+
+```yaml
+git:
+  user:
+    name: Your Name
+    email: your.email@example.com
+
+env:
+  EDITOR: vim
+```
+
 ### Command-Line Flags
 
-- `--env KEY=VALUE`: Add environment variable to container (can be used multiple times)
-- `--volume HOST:CONTAINER`: Mount host directory into container (can be used multiple times)
+CLI flags override all configuration files:
+
+#### Container Configuration
+- `--image NAME`: Container image name
+- `--dockerfile PATH`: Path to Dockerfile for building image
+- `--working-dir PATH`: Working directory inside container
+- `--network NAME`: Docker network to use
+- `--stop-timeout SECONDS`: Container stop timeout
+
+#### TTY Configuration
+- `--tty-retries COUNT`: Number of TTY resize retry attempts
+- `--retry-delay DURATION`: Delay between retries (e.g., "10ms", "100ms")
+
+#### Git Configuration
+- `--git-user-name NAME`: Git user name for commits
+- `--git-user-email EMAIL`: Git user email for commits
+
+#### Runtime Configuration
+- `--env KEY=VALUE`: Add environment variable (can be used multiple times)
+- `--volume HOST:CONTAINER`: Mount volume (can be used multiple times)
+
+Example:
+
+```bash
+contagent --env MY_VAR=value --volume /local:/remote --image custom:latest /bin/bash
+```
 
 ### Environment Variables
 
+#### Variable Expansion
+
+Both `env` and `volumes` sections in configuration files support environment variable expansion:
+
+```yaml
+env:
+  # Simple expansion
+  HOME_PATH: $HOME
+
+  # Braced expansion
+  USER_DIR: ${HOME}/${USER}
+
+  # Use in volumes
+volumes:
+  - $HOME/.ssh:/root/.ssh
+  - ${PWD}/data:/data
+```
+
+#### Automatically Passed Variables
+
 The following environment variables are automatically passed through to the container:
 
 - `TERM`: Terminal type (defaults to `xterm-256color`)
 - `COLORTERM`: Color support (defaults to `truecolor`)
-- `ANTHROPIC_API_KEY`: API key for AI agent
-- `SSH_AUTH_SOCK`: SSH agent socket (automatically configured)
+- `ANTHROPIC_API_KEY`: API key for AI agents
+- `SSH_AUTH_SOCK`: SSH agent socket (set to `/run/host-services/ssh-auth.sock`)
+
+### Volume Mounts
+
+#### Automatic Mounts
 
-### Default Volume Mounts
+These volumes are always mounted automatically:
 
 - `/var/run/docker.sock:/var/run/docker.sock`: Docker socket for Docker-in-Docker
 - `/run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock`: SSH agent access
 
-### Container Settings
+#### Custom Mounts
+
+Add custom mounts via configuration files or CLI flags:
+
+**Via config file:**
+
+```yaml
+volumes:
+  - ./data:/data
+  - $HOME/.cache:/root/.cache
+```
+
+**Via CLI:**
+
+```bash
+contagent --volume ./data:/data --volume $HOME/.cache:/root/.cache /bin/bash
+```
+
+### Default Values
+
+If no configuration is provided, these defaults are used:
+
+| Setting | Default Value |
+|---------|---------------|
+| `image` | `contagent:latest` |
+| `working_dir` | `/app` |
+| `network` | `default` |
+| `stop_timeout` | `10` seconds |
+| `tty_retries` | `10` |
+| `retry_delay` | `10ms` |
+| `git.user.name` | `Contagent` |
+| `git.user.email` | `contagent@example.com` |
+
+### Configuration Priority Example
+
+Given:
+
+1. Global config sets `git.user.name: "Alice"`
+2. Project config sets `git.user.name: "Bob"` and `image: "myimage:latest"`
+3. CLI flag `--git-user-name Charlie`
 
-- **Image Name**: `contagent:latest`
-- **Working Directory**: `/app`
-- **Stop Timeout**: 10 seconds
-- **TTY Resize Retries**: 10 attempts with exponential backoff (10ms, 20ms, 30ms, ...)
+Result: `git.user.name` will be "Charlie" and `image` will be "myimage:latest"
 
 ## Development
 

go.mod

@@ -8,6 +8,8 @@ require (
 	github.com/moby/moby/client v0.1.0
 	github.com/moby/term v0.5.2
 	github.com/stretchr/testify v1.11.1
+	golang.org/x/sync v0.18.0
+	gopkg.in/yaml.v3 v3.0.1
 )
 
 require (
@@ -33,7 +35,5 @@ require (
 	go.opentelemetry.io/otel v1.38.0 // indirect
 	go.opentelemetry.io/otel/metric v1.38.0 // indirect
 	go.opentelemetry.io/otel/trace v1.38.0 // indirect
-	golang.org/x/sync v0.18.0 // indirect
 	golang.org/x/sys v0.35.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
 )