Skip to content

AGENTS.md

Latest commit

 

History

History
25 lines (21 loc) · 6.6 KB

AGENTS.md

File metadata and controls

25 lines (21 loc) · 6.6 KB

Agent Rules

  • When changing this repo's architecture or how Pi is built, launched, containerized, configured, or persisted, update the repo-memory notes in this AGENTS.md.
  • Do not edit anything under pi/agent/git/.
  • Do not commit files matched by .gitignore.
  • You are Pi, running inside the Pi coding-agent harness. Do not start another Pi session or run pi unless explicitly asked for testing.
  • Pi documentation:
    • Main: /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/README.md
    • Docs: /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/docs
    • Examples: /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples

Repo memory: how Dockerized Pi works

This repository is a Docker wrapper around @earendil-works/pi-coding-agent plus a persisted, preconfigured Pi home under pi/.

  • Build flow: ./build.sh [version] builds image pi-coding-agent from Dockerfile.release, passing host UID, GID, and Pi npm package VERSION (default latest). ./build.sh --installed-version runs ./pi.sh --version and extracts the installed semver. Dockerfile.git is an alternate development Dockerfile that clones earendil-works/pi-mono, builds packages, packs packages/coding-agent, and installs that tarball instead of npm release. GitHub Actions workflow .github/workflows/publish-dockerhub.yml publishes multi-arch Dockerfile.release images to DockerHub on main, v* tags, or manual dispatch using DOCKERHUB_USERNAME/DOCKERHUB_TOKEN secrets.
  • Release image: based on node:current-trixie-slim; creates user pi matching host UID/GID; installs zsh, git, gh, glab, sentry-cli, curl/wget/jq/rg/tree/file, sudo/gosu, tmux/qemu plus QEMU firmware/ROM packages needed by Gondolin (ovmf/ipxe-qemu on amd64, qemu-efi-aarch64/ipxe-qemu on arm64), Java 21, uv-managed Python, autopep8, pytest, mitmproxy, and debugging CLIs (xh, grpcurl, websocat). It updates npm globally to latest, installs Pi globally with npm install -g @earendil-works/pi-coding-agent@$VERSION @earendil-works/gondolin, sets WORKDIR /workspace and HOME=/home/pi, and uses entrypoint.sh as the container entrypoint.
  • Runtime entrypoint: entrypoint.sh starts as root, sets the pi user's sudo password from PI_SUDO_PASSWORD or generates/prints a random one, configures global git identity from BOT_GIT_NAME/BOT_GIT_EMAIL, logs gh in with BOT_GH_TOKEN, writes Sentry auth from BOT_SENTRY_TOKEN, then executes gosu pi pi "$@". In other words: the image entrypoint always ends by calling the actual pi binary as the non-root pi user.
  • Host launcher: ./pi.sh [launcher-options] [pi args...] is how Pi is normally called. It creates/sources .env, parses wrapper flags, discovers the project root by walking upward from $PWD until .git, .project, or .projectile, computes the relative working directory, and starts Docker. Normal Pi CLI args are passed through to the container after wrapper-added args. --entrypoint PATH|NAME selects the host entrypoint script mounted over /usr/local/bin/entrypoint.sh; bare names resolve to bundled shortcuts such as zsh -> entrypoint-zsh.sh.
  • Docker invocation in pi.sh: docker run --rm plus -it only for interactive terminals; optional wrapper flags can add Docker -p port publishing, --network/--docker-network to attach the started container to an existing Docker network, --volume/--docker-volume to pass additional Docker -v mounts, --env/--docker-env for extra environment variables, and --env-file/--docker-env-file for extra env-files (relative env-file paths resolve from the invocation cwd and are passed after this repo's .env); mounts detected project root to /workspace as rw or ro; mounts this repo's pi directory to /home/pi/.pi:rw; mounts .cache/checkouts and .cache/gondolin; sets -w /workspace/$REL_PATH; passes PI_PROJECT_ROOT, PI_MOUNT_MODE, PI_HOST_HOSTNAME, selected provider/API env vars, and --env-file .env; image is pi-coding-agent; final command is pi-coding-agent $TOOLS --session-dir ... [extra args] [user pi args], which the entrypoint converts to gosu pi pi ....
  • Session/config persistence: Pi config and state live outside target projects in this repo's pi/agent/ because it is mounted as /home/pi/.pi. Sessions are forced to /home/pi/.pi/agent/sessions/--<canonical-host-project-root>-- so each host project gets stable saved sessions. Runtime/secrets paths such as pi/agent/auth.json, pi/agent/sessions/*, pi/agent/git/, and .cache/ are gitignored.
  • Important pi.sh modes: --ro/--readonly mounts /workspace read-only and limits tools to read/search/list; a .pi_ro file in the current directory also forces ro. --port/--publish accepts Docker-style port mappings such as 8080:8080 and forwards them into docker run -p; short -p is left for Pi CLI args. --network/--docker-network accepts an existing Docker network name or mode and forwards it into docker run --network. --volume/--docker-volume accepts Docker-style volume mappings such as /host/path:/workspace/sharepoint:ro and forwards them into docker run -v. --env/--docker-env and --env-file/--docker-env-file pass per-run Docker environment values/files. --install writes shell aliases pi, pic, and picommit. --update checks npm latest, rebuilds if a newer Pi release exists, and always runs ./pi.sh update for Pi packages even when the image is already current. --sessions lists persisted session files. --commit rewrites args to run /commit --force --user ... --email ..., optionally with PI_FAST_PROVIDER/PI_FAST_MODEL.
  • Package-management passthrough: if the first Pi arg is install, remove, update, list, or config, pi.sh suppresses wrapper tool/session args so Pi package commands operate normally.
  • Optional project notes: if .volumes.yml exists in this repo and maps the original host cwd to another directory, pi.sh mounts that directory read-only at /workspace-notes and appends a system prompt telling Pi about it.
  • Bundled Pi customization lives under pi/agent: settings.json chooses theme/defaults/enabled models/packages and disables older quota extensions; models.json defines local Ollama/LM Studio OpenAI-compatible providers at host.docker.internal; modes.json stores named modes; extensions/ includes /files-changed + get_files_changed, /quota + quota tools, Kilo Code provider commands, switch_model, /codex-account + /codex-switch for Pi-only OpenAI Codex account snapshots, and a footer showing host project/root/mount mode; prompts/commit.md defines /commit; skills/git-autopep8 formats only changed Python lines.