ccodolo: Instructions file for Codex

CLAUDE.md - Guide for AI Coding Assistants

This document provides development guidelines for AI-powered coding tools working on the CCoDoLo project itself.

For project features, usage, and architecture: See README.md

Note: AGENTS.md is a symlink to this file so non-Claude assistants discover it too — edit CLAUDE.md, not the symlink.

What This Project Is

CCoDoLo is a meta-project - it provides sandboxed Docker containers for running AI coding assistants (including you). When modifying this codebase, you're improving the infrastructure that runs AI agents safely.

Repository Structure

ccodolo/
├── .github/
│   ├── dependabot.yml               # Weekly updates for github-actions and gomod
│   ├── zizmor.yml                   # zizmor security scanner config
│   └── workflows/
│       ├── release.yml              # goreleaser (triggered by v* tags)
│       ├── updates.yml              # daily agent + tool version bumps (opens PRs)
│       ├── validate.yml             # go vet, go test, golangci-lint, cross-platform build, docker image smoke test
│       └── zizmor.yml               # GitHub Actions security scanning
├── .golangci.yml                    # Default linters + gofmt as a formatter check
├── .goreleaser.yml                  # Cross-platform binaries + checksums + build attestation
├── go.mod / go.sum
├── main.go                          # Entrypoint → cmd.Execute()
├── cmd/
│   ├── root.go                      # cobra root command, flags, main run() logic, TUI
│   ├── repair.go                    # repair-worktrees subcommand (host-side git worktree repair)
│   └── version.go                   # version subcommand
├── internal/
│   ├── agent/
│   │   ├── agent.go                 # Agent enum, metadata registry
│   │   └── agent_test.go
│   ├── config/
│   │   ├── config.go                # TOML struct, Load/Save, merge, validate
│   │   ├── config_test.go
│   │   ├── migrate.go               # ccodolo.config → ccodolo.toml migration
│   │   └── migrate_test.go
│   ├── docker/
│   │   ├── build.go                 # Image build orchestration, build-context staging
│   │   ├── build_test.go
│   │   ├── dockerfile.go            # Dockerfile template rendering
│   │   ├── dockerfile_test.go
│   │   ├── exec_unix.go             # execCLI: replace the process via execve (see Architecture Notes)
│   │   ├── exec_windows.go          # execCLI: child process with inherited console (no execve on Windows)
│   │   ├── hash.go                  # SHA-256 image tag computation
│   │   ├── hash_test.go
│   │   ├── hooks.go                 # Host-side startup-hook pre-flight warning
│   │   ├── hooks_test.go
│   │   ├── run.go                   # docker run / docker exec argv (--mount binds, env, TERM defaults)
│   │   ├── run_test.go
│   │   ├── runtime.go               # Runtime enum (docker/apple), host checks
│   │   └── runtime_test.go
│   ├── fsutil/
│   │   ├── copy.go                  # CopyDir/CopyFile, mode-preserving
│   │   └── copy_test.go
│   ├── project/
│   │   ├── project.go               # Dir creation, template copying
│   │   ├── project_test.go
│   │   ├── setup.go                 # Agent-specific JSON config (copilot/kiro)
│   │   └── setup_test.go
│   ├── tool/
│   │   ├── custom_tools_test.go
│   │   ├── readme_test.go           # Fails when the README Dev Tools table drifts from the catalog
│   │   ├── tool.go                  # Tool catalog, dependency resolution
│   │   └── tool_test.go
│   └── updater/                     # Automated tool-version bumper (not in released binary)
│       ├── main.go                  # Flags: -check, -json, -write, -only, -timeout, -allow-unverified
│       ├── version.go               # Numeric-tuple version parse/compare
│       ├── plan.go                  # Candidate selection, bump classification
│       ├── source.go                # Fetcher interface + registry dispatch
│       ├── fetch_docker.go          # Docker Hub API
│       ├── fetch_github.go          # GitHub Releases API
│       ├── fetch_npm.go             # npm registry API
│       ├── fetch_pypi.go            # PyPI JSON API
│       ├── fetch_quay.go            # quay.io API
│       ├── rewrite.go               # Anchored-regex file rewriters
│       ├── git.go                   # exec-based git helpers
│       ├── version_test.go
│       └── rewrite_test.go
├── embedded/
│   ├── embed.go                     # go:embed directives
│   ├── Dockerfile.tmpl              # Templatized Dockerfile
│   ├── dotfiles/                    # Shell configurations (.bashrc, .zshrc.local, .inputrc)
│   └── scripts/                     # Container startup scripts (git worktree hygiene)
├── docs/
│   └── custom-tools.md              # Custom tool catalog reference (custom-tools.json)
└── template.example/                # Example project templates