container-use: Instructions file for Codex

Agent Guidelines for Container-Use

Core Architecture

Container-use provides isolated, containerized development environments for AI agents by combining:

• Git branches for each environment (e.g., adjective-animal names like fluffy-lion)
• Dagger containers with code mounted at /workdir
• Git notes (container-use and container-use-state refs) for operation logging and state persistence
• Worktrees in ~/.config/container-use/worktrees/ for filesystem representation

Key Principle: All operations MUST go through environment tools - NEVER use git commands directly in environments.

Critical Agent Rules (MUST FOLLOW)

1. Use ONLY environment tools for ANY and ALL file, code, or shell operations - NO EXCEPTIONS
2. DO NOT install or use git CLI with environment_run_cmd tool - environment tools handle git integration automatically
3. ALWAYS inform user how to view your work: cu log <env-id> and cu checkout <env-id>
4. Failure to inform user makes work inaccessible to others

Build, Test, and Lint Commands

Build

# Build binary
go build -o container-use ./cmd/container-use

# Using Dagger
dagger call build --platform=current export --path ./container-use

Test

# Run all tests
go test ./...

# Unit tests only (fast, no containers)
go test -short ./...

# Integration tests
go test -count=1 -v ./environment

# Run single test
go test -run TestSpecificFunction ./path/to/package
go test -run TestSpecificFunction -v ./path/to/package

# Run tests in specific package
go test ./repository
go test ./environment

Format and Lint

# Format code (REQUIRED before committing)
go fmt ./...

# Lint
dagger call lint

Dependencies

# Install dependencies
go mod download

# Clean up dependencies
go mod tidy

Code Style Guidelines

Imports

• Order: stdlib imports first, then third-party imports
• Group blank lines between stdlib and third-party
• No unused imports (checked by linter)
• Example:

  import (
      "context"
      "fmt"
      "os"
  
      "dagger.io/dagger"
      "github.com/spf13/cobra"
  )