Important
Use daemonless/porting-toolkit instead. This repo is the original, Claude Code only version and is no longer maintained. The daemonless copy works with any agent, has a larger cookbook (39 entries against 27 here), a BSD 2-Clause licence, and follows the current daemonless AI policy. It was merged on 5 November 2026 (PR #1).
Claude Code skills, subagents, hooks and shell scripts that drive the port of an upstream app to a native FreeBSD OCI image for daemonless. It stays up as the record of how the workflow started.
People who want to add an image to daemonless and are willing to let an AI agent do the build loop under fixed rules. You need a FreeBSD host with dbuild and podman, gh, and Claude Code. Read the daemonless AI contribution policy first. It applies to every repo in the organisation.
It is an AI-assisted workflow. Claude does the research, the scaffold, the build loop and the first draft of the notes. The toolkit exists to stop it guessing. Every build error is looked up in a cookbook before anything else. Every non-boilerplate line in the image must trace to a written brief, a cookbook entry or a logged error. A build that exits 0 is not trusted until its log is clean, and a clean build is not trusted until the container test passes.
A person stays responsible for the result. The skill never merges. It stops for human review, and the review starts from BUILD-NOTES.md, which lists every FreeBSD-specific change and why it is there. The PR template ends with three "viva" questions: why this base and runtime, what the riskiest dependency is, and what breaks first on the next upstream release. In this version the agent drafts those answers and the person checks them. The daemonless copy goes further and leaves the answers and the whole PR description to the person.
Skills (run as slash commands in Claude Code):
| Path | What it does |
|---|---|
.claude/skills/port-package/ |
The full port in seven phases, numbered 0 to 6: intake, research, scaffold, build loop, container test, harden, then audit and stop |
.claude/skills/bump-upstream/ |
Move an existing image to the latest upstream release and re-test it |
Subagents (each runs in its own context and returns a short report):
| Path | What it does |
|---|---|
upstream-researcher.md |
Reads the upstream repo and returns a port plan: release tag, runtime, build steps, native modules and their FreeBSD status. Writes no files |
freebsd-port-solver.md |
Takes one error that survived two fix attempts and returns one fix, plus a new cookbook entry |
port-auditor.md |
Pre-PR gate. Walks every line for provenance, checks BUILD-NOTES.md against the files, and says what breaks first on the next bump |
Hooks (in .claude/settings.json, run by Claude Code itself rather than left to the model):
| Hook | What it does |
|---|---|
block-containerfile-edit.sh |
Refuses edits to the generated Containerfile. Only Containerfile.j2 is edited |
enforce-background-build.sh |
Refuses a foreground build. A cold build outlives the tool timeout and gets killed |
enforce-cit-on-pr.sh |
Refuses git push and gh pr create until the container test has passed |
journal.sh |
Appends every shell command to JOURNAL.log, so a dead session leaves a record |
warn-readme-rewrite.sh |
Warns when dbuild generate has rewritten README.md with fork URLs |
remind-cit.sh |
Reminds the agent at the end of a turn that a green build is not a working image |
Scripts (plain sh, they work without Claude):
| Path | What it does |
|---|---|
scripts/build.sh |
The one way to build. Refuses a stale Containerfile, logs to build.log, and greps the log for failures that dbuild reports as exit 0 |
scripts/cit-with-logs.sh |
Runs dbuild test, captures the full container log that dbuild truncates, runs the smoke test, and writes .cit-passed only if both pass |
scripts/lint-compose.sh |
Checks compose.yaml metadata against the Containerfile labels. Also flags an unpinned upstream ref, patches without --fuzz=0 or a guard, and compilers in the runtime stage |
scripts/pre-push.git-hook |
Git hook that refuses a push without .cit-passed. It holds for any agent or person |
Reference and templates:
| Path | What it is |
|---|---|
.claude/reference/freebsd-porting-cookbook.md |
27 fixes keyed by error text, each as signature, cause, fix, why |
.claude/reference/cit-and-logs.md |
What the container test checks, and how to catch the logs it drops |
templates/ |
PORT-BRIEF.md, BUILD-NOTES.md, PROCESS-LOG.md, PR-BODY.md, smoke-test.sh and a per-image CLAUDE.md |
install.sh |
Copies the above into an image repo and installs the git hook |
TESTING.md |
The test of the toolkit itself: can a mid-tier model finish a port on these files alone? |
This is what /port-package <upstream-url> does, in order. The full text is in SKILL.md.
- Intake. Look for a
WIP.mdleft by a failed session and resume from it. Find the nearest existing daemonless image to copy. Pin the latest upstream release tag. It never buildsmain. - Research. The
upstream-researchersubagent writes a port plan. The deciding question is native modules: which dependencies ship prebuilt binaries, and does each one build on FreeBSD? If aPORT-BRIEF.mdexists, a stronger model has already done this step and the skill skips it. - Scaffold. Copy the nearest image, write
Containerfile.j2, rundbuild generate, runlint-compose.sh. Check every package name withpkg rquerybefore the first build, because a wrong name costs a full build cycle. - Build loop. Build in the background with
scripts/build.sh. On any error, the first action is a literalgrep -Fof the cookbook for the error line. One fix per rebuild. An error that survives two attempts goes tofreebsd-port-solver. If that fails too, the agent writesWIP.mdand stops. - Container test.
scripts/cit-with-logs.shruns the daemonless container test and a smoke test that exercises what the app is for, not just that a port answers. - Harden. Guard every patched file so a moved upstream file fails the build loudly. Pin injected native dependencies. Keep compilers out of the runtime image.
- Audit, then stop.
port-auditormust return CLEAN. Claude Code's built-in/code-reviewruns on the diff. Then the branch and PR go up for a person to review, and the session ends.
Each new fix found along the way is appended to the local cookbook, then sent back to this repo, so the next port starts with it.
One cookbook entry, verbatim:
### A patch silently does nothing / unpatched code ships
**Cause:** `COPY patches/x dest/x` **creates** `dest/x` if upstream moved/renamed it — unpatched source then ships and crashes.
**Fix:** guard before COPY:
```dockerfile
RUN for f in dest/a dest/b ; do test -f "$f" || { echo "PATCH DRIFT: $f gone upstream"; exit 1; }; done
```Six images I added to daemonless, all reviewed and merged by a daemonless maintainer:
| Image | Upstream app | PR | Merged | Notes |
|---|---|---|---|---|
| papra | Papra, document manager | daemonless/papra#1 | 2026-06-12 | Before this repo's first commit |
| sparkyfitness | SparkyFitness, fitness tracker | daemonless/sparkyfitness#1 | 2026-06-12 | Before this repo's first commit |
| immich-cli | Immich command-line client | daemonless/immich-cli#1 | 2026-06-19 | A run-and-exit tool, tested with the command mode added in dbuild#9 |
| immich-public-proxy | Immich Public Proxy | daemonless/immich-public-proxy#1 | 2026-07-04 | Test run 1 in TESTING.md. The cold run failed and a stronger model finished it |
| ffmpeg | FFmpeg | daemonless/ffmpeg#1 | 2026-07-08 | Rung 2 in TESTING.md. The run's outcome is not recorded there |
| actual | Actual Budget sync server | daemonless/actual#1 | 2026-10-05 | First cold run to pass unaided (log) |
In all, 34 of my PRs have been merged across 14 daemonless repos (gh search prs --author jtrotsky --owner daemonless --merged, 14 November 2026). Besides the six above, they include fixes and version bumps to these images and to immich-server, immich-ml, stump and filebrowser-quantum, that command test mode in dbuild, fixes to the fjord orchestrator, and a guide to porting with AI on the daemonless site.
From the root of an image repo, cloned into a directory named exactly after the image (dbuild takes the image name from the directory):
/path/to/daemonless-porting-toolkit/install.sh
claude
> /port-package https://github.com/<owner>/<repo>To move an existing image to a new upstream release:
claude
> /bump-upstreaminstall.sh --refresh overwrites .claude/ with the current toolkit and keeps .claude/settings.local.json. After install, check the hooks landed (ls .claude/hooks/*.sh). An older install.sh dropped them silently on GNU cp.
- Claude Code only. The hooks and slash commands need it. The scripts and git hook work alone. The daemonless copy splits the two.
- Behind the AI policy. Here the skill pushes the branch and opens the PR with a templated body. The daemonless policy asks for a PR description written by a person. The daemonless copy stops before the PR and leaves the description to the submitter.
- Lightly tested on weaker models. In this repo
TESTING.mdrecords one run, and it failed when the harness killed a foreground build. The daemonless copy records one later pass onactual. Python apps and other agents are untested. - Thin outside Node. The cookbook has 27 entries: 10 for Node, 5 for Python, 12 general
dbuildones, and an empty Go section. - Needs FreeBSD.
dbuildand the container test run on a FreeBSD host with podman.
This repo has no licence file yet. The daemonless copy is BSD 2-Clause.
