WIP: Python rewrite

[asmacdo]

Try it

pip install "con-yolo @ git+https://github.com/asmacdo/yolo@redesign-python"
yo demo

Why rewrite?

Every new tool was a PR to the Dockerfile and a debate about what belongs in the base image (#28, #31, #43, #39). Config was sourced bash, hard to layer, hard to test.
The architecture had no extension points: growth required modifying the core.

Now:

• Config is YAML that merges.
• Users can customize images, and keep them separate
• Extras are composable scripts, not Dockerfile edits. packages: [numpy] in your config, or drop a bash script in .yolo/image-extras/ for anything complex. apt, datalad, git-delta, jj, pip, playwright, python are already optional extras. No Dockerfile knowledge needed.
• Install is pip install, not git clone + manual setup. Editable install for quicker dev cycles.
• Install separated from image build
• Python with tests: unit tests, integration tests, pre-commit (ruff, shellcheck, yamllint), CI.

Legacy bash preserved in design/legacy/.

Closes:

• Extract a SPEC.md from current features #42
• Config and Arbitrary Development Environments #47
• Setup CI to give some basic smoke testing! #4
• Make setup-yolo.sh do basic testing #5
• Does not work "out of the box" #3

Breaking changes

• Config is YAML, not sourced bash. Migration: point Claude at your old
  config and SPEC.md, it generates the YAML.
• CLI is yo build, yo run, etc. (not a single yolo command)
• Image tags are yolo-<project>-<name>

New features

• yo demo — interactive tour inside a container
• yo clip — clipboard bridge (container → host)
• yo images — list images and build status
• Context injection — context: config key → --append-system-prompt
• Auto-build — yo run builds if image doesn't exist
• Named images with from: — podman-native layering from config
• Composable image extras: bash scripts, not Dockerfiles

Config

Declarative YAML, merged from 5 locations (package defaults → system →
user → project → local). Lists append, dicts recurse, scalars replace.
!replace tag for overrides. See SPEC.md for full reference.

Testing

• Unit tests for config, builder, launcher, CLI
• Integration tests for every extra (verify mode + idempotency)
• Pre-commit: ruff, ruff-format, yamllint, shellcheck

TODO

Resolve each before merge or file as a new issue.

• Update install instructions for primary repo/branch
• Decide: alias yolo → yo run or change entry to yolo
• Remove design/legacy/ (separate PR after cutover)
• Consider adding more e2e integration tests that dont need claude subscription
• Security audit
• Add yo config to see merged config
• Config migration script (bash → YAML)
• Docs for writing custom image-extras scripts
• Add set -eu to playwright.sh

[yarikoptic]

FWIW I would need config migration to adopt... Indeed not sure how/who would review etc

[yarikoptic]

FWIW I just used mounts config so far, so could be easy to migrate by simply sourcing and printing to populate values in yaml

[asmacdo]

@yarikoptic config is similar, format is different. claude (not yolo, so it can see all the paths) should be able to migrate

[Copilot]

Pull request overview

Python rewrite of the yolo toolchain to run Claude Code inside a rootless Podman container, shifting from a legacy bash implementation to a packaged, tested Python CLI (yo) with YAML config layering and composable “image extras”.

Changes:

• Added Python modules for config loading/merging, image building, and container launching (src/yolo/*) with a Click-based CLI (yo ...).
• Introduced Containerfiles + composable image-extras/*.sh installers, plus unit/integration tests and CI updates.
• Updated docs/specs (README/SPEC/CONTRIBUTING/CLAUDE) and preserved the legacy bash implementation under design/legacy/.

Reviewed changes

Copilot reviewed 44 out of 53 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
src/yolo/cli.py	Implements yo CLI commands (build/run/init/images/clip/demo).
src/yolo/config.py	YAML config discovery, loading, merge rules, and !replace tag support.
src/yolo/builder.py	Resolves extras, assembles build contexts, and runs podman build.
src/yolo/launcher.py	Assembles and executes podman run for Claude Code sessions.
src/yolo/defaults/config.yaml	Ships default config (env passthrough, default image + extras).
src/yolo/defaults/config.template.yaml	Template for yo init config generation.
src/yolo/demo/demo.md	Demo script/instructions for interactive tour.
src/yolo/demo/.yolo/config.yaml	Demo-specific context injection config.
src/yolo/__init__.py	Package marker.
images/Containerfile.base	Defines minimal Debian base image + Claude Code install.
images/Containerfile.extras	Layers “extras” scripts on top of a base image.
image-extras/apt.sh	Extra installer script for apt packages (+ verify mode).
image-extras/python.sh	Extra installer script for Python via uv (+ verify mode).
image-extras/pip.sh	Extra installer script for pip packages via uv tool (+ verify mode).
image-extras/git-delta.sh	Extra installer script for git-delta (+ verify mode).
image-extras/datalad.sh	Extra installer script for DataLad (+ verify mode).
image-extras/jj.sh	Extra installer script for Jujutsu (+ verify mode).
image-extras/playwright.sh	Extra installer script for Playwright/Chromium (+ verify mode).
tests/test_cli.py	Unit tests for CLI behavior (clip).
tests/test_config.py	Unit tests for config path precedence, merge rules, !replace.
tests/test_builder.py	Unit tests for extras parsing, script resolution, build context, image tags.
tests/test_launcher.py	Unit tests for launcher command assembly, volumes, context injection, auto-build.
tests/integration/conftest.py	Marks integration tests.
tests/integration/test_image_extras.py	Integration tests building/verifying each extra script via Podman.
tests/integration/test-extras-build.sh	Shell integration test for extras build/idempotency.
tests/integration/__init__.py	Integration test package marker.
tests/features_to_test.md	Test checklist for remaining integration behaviors.
.github/workflows/ci.yml	New CI workflow for lint/unit/integration tests.
.pre-commit-config.yaml	Adds ruff/yamllint/shellcheck hooks.
.yamllint.yml	Yamllint config.
pyproject.toml	Defines Python package metadata and yo entrypoint.
.gitignore	Ignores venv/build artifacts and .yolo/ (with demo exception).
.gitmodules	Updates bats submodule paths (currently inconsistent with repo layout).
README.md	Updated user-facing docs for Python rewrite and yo usage.
SPEC.md	Updated spec for Python rewrite (config/images/extras/launcher).
CONTRIBUTING.md	Contributor setup/test guidance for the Python rewrite.
CLAUDE.md	Repo guidance and key-file index.
context-injection-notes.md	Notes on context injection approach.
design/HACK_DECISIONS.md	Locked design decisions for the rewrite.
design/LEGACY_SPEC.md	Preserved spec of the legacy bash implementation.
design/legacy/*	Preserved legacy implementation, tests, and CI config for reference.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The --project option uses flag_value="project" but sets default=True, which makes target a boolean by default rather than a string. It currently falls through to the project path by accident, but it's easy to break later and makes the type inconsistent. Prefer default="project" (or default=None and treat None as project) so target is always a string.

[Copilot]

yo run always bind-mounts ~/.gitconfig as a file, but doesn't ensure it exists. If the user has no ~/.gitconfig, podman will typically create the source path as a directory, and the container will see /tmp/.gitconfig as a directory (breaking git). Consider creating an empty ~/.gitconfig when missing (or making the mount conditional).

[asmacdo]

I think we should pull this out of the launcher, and put it into default config

[Copilot]

_ensure_base() only treats from: as either an existing podman image tag or the computed tag (image_tag(name)) of a configured image. But the spec/examples use from: base to refer to another configured image by name. As-is, from: base will raise at runtime unless the user writes the full tag. Consider allowing from: to match an images: entry by name (and translate to image_tag(name)), while still supporting arbitrary external image references.

[Copilot]

_expand_volume() doesn't expand ~ for the common host:container or host:container:opts forms. This is especially problematic for YAML config values like ~/data:/data, where the shell won't expand ~ and podman will receive it literally. Expand ~ on the host-path portion for : forms as well (or call Path(...).expanduser() before assembling the final string).

[Copilot]

This trap uses an unquoted $BUILD_CONTEXT in rm -rf, which will trigger ShellCheck (and can behave unexpectedly if the temp path contains whitespace). Quote the variable in the trap command (and consider using trap 'rm -rf -- "$BUILD_CONTEXT"' EXIT).

[Copilot]

REPO_ROOT is computed relative to the installed module path, then used to locate images/ and image-extras/ outside the Python package. This will work in a source checkout but will break for wheel/PyPI installs because those directories are not part of src/yolo. Consider shipping Containerfiles + builtin extras as package resources (e.g., under src/yolo/resources/) and resolving them via importlib.resources, or adjust the build to include these directories in the wheel and update these paths accordingly.

[Copilot]

image_tag() sanitizes the project dirname but not image_name. Config examples include names like myproject:heavy, and characters like : will produce invalid/unintended image references (and may be interpreted as a tag separator). Sanitize image_name the same way (and/or validate and raise a clear error for unsupported characters).

[Copilot]

The wheel build only packages src/yolo, but the runtime expects top-level images/ and image-extras/ directories to exist (see yolo.builder paths). A pip install con-yolo wheel will therefore be missing required Containerfiles and builtin extras. Either move these assets under src/yolo/ and load via importlib.resources, or configure Hatch to include them in the wheel as package data and update the path resolution accordingly.

[Copilot]

If the image is missing, run() calls build(config.get("images", []), only=image_name) but doesn't validate that a matching image entry exists (or that any images are configured). If only doesn't match, no build happens and the subsequent podman run will fail with a less clear error. Detect this case and raise a user-facing error (e.g., ClickException) when the requested image name isn't defined or no images are configured.

[Copilot]

The final subprocess.run(cmd) result is ignored, so yo run can exit 0 even when podman run fails. Use check=True (and let Click propagate a non-zero exit), or explicitly sys.exit(result.returncode) so callers/CI can detect failures.

[yarikoptic]

for such simple deterministic migrations there should IMHO be the code not reliance on agents to do the right thing.