How work happens in this repo. It's written for a solo developer working with AI agents (Claude Code, Codex) that may work unattended for long stretches.
Nothing runs on GitHub Actions or any other hosted CI. Deva lost about $250 on Actions minutes. All checks,
builds and releases run on this Mac through scripts/. scripts/ci.sh fails if a .github/workflows
folder ever appears. Uploading a finished release with gh release create is fine: it's an upload, not
Actions.
| Command | When | What it runs |
|---|---|---|
scripts/ci.sh fast |
Automatically before every commit (pre-commit hook) | No-hosted-CI check, format lint, KnobsCore unit tests |
scripts/ci.sh |
Before checking a box in PLAN, and before every push (pre-push hook) | Everything in fast, integration tests, app build with warnings as errors |
scripts/ci.sh release |
Before a release | Everything above, plus a Release build, and a failure if any of the 10 tools is missing |
scripts/ci.sh linux |
After changing KnobsCore, and before a Linux build | Format lint, then every library built and KnobsCore's unit tests run on Linux in a local container (OrbStack or Docker on this Mac; swift:6.2-noble unless KNOBS_LINUX_IMAGE names another). Never a hosted runner |
scripts/linux.sh build |
After changing anything in linux/ |
Builds the Linux app with warnings as errors in the local knobs-linux-dev container. scripts/linux.sh run then shows it at http://localhost:8085 through GTK's Broadway backend, and stop ends it |
scripts/linux.sh package <version> [arm64|amd64] |
Before handing out a Linux build | Builds release binaries in the Ubuntu 26.04 and Fedora 44 containers (the other architecture runs emulated) and writes dist/linux/knobs_<version>_<arch>.deb, knobs-<version>-1.fc44.<arch>.rpm and knobs-<version>-linux-<arch>.tar.gz; amd64 also writes knobs-gui-bin-<version>-1-x86_64.pkg.tar.zst for Arch, and its AUR PKGBUILD and .SRCINFO to dist/linux/aur/. Install-test each in a clean container of its distribution and run a task through Broadway before calling it done |
Test conventions the script relies on:
- Any suite that launches a real tool must be named
...IntegrationTests(for exampleFFmpegIntegrationTests).fastskips suites matchingIntegrationTests. - Integration tests skip, with a message, when their tool isn't installed. With
KNOBS_REQUIRE_TOOLS=1(set byreleasemode) they fail instead. - The whisper test needs
.cache/models/ggml-tiny.en.bin, which is per checkout and not in git. In an agent's worktree, link the main checkout's:ln -s /Users/deva/opensource/knobs/.cache .cache(ignored like the folder).
The app build fetches Sparkle (DEC-024) into build/DerivedData/SourcePackages the first time. On 2026-10-21 that
first fetch stalled for ten minutes with no network activity; a second try finished in five. If a first build hangs
there, stop it and run
xcodebuild -project Knobs.xcodeproj -scheme Knobs -resolvePackageDependencies -derivedDataPath build/DerivedData,
then build again.
Hooks live in scripts/hooks/ and are turned on with scripts/install-hooks.sh. That script sets
core.hooksPath, so the hooks are versioned files, not copies. Never skip them with --no-verify.
- One branch:
main. A solo developer doesn't need feature branches. Use a short-lived branch only for an experiment that may be thrown away. - Small commits, one concern each. Structural changes (rename, move, reformat) and behavior changes never share a commit.
- Message format:
area: why, for examplecore: keep values with spaces as one argument. Areas:core,app,manifests,scripts,docs. - Stage named paths. Never
git add -Aorgit add .. - Agents commit to
mainand push it with a plaingit push(DEC-020). They never force-push and never create remote repos. - Releases are tags:
v0.1.0. Version numbers follow SemVer, andCHANGELOG.mdgets an entry per release.
- The behavior has tests through the public interface (KnobsCore), or a written manual check (app UI).
scripts/ci.shpasses in this session, and the output was read.- The affected docs are updated in the same commit: PLAN boxes, STATUS, MANIFEST_FORMAT, README.
- A WORKLOG entry is appended with
scripts/log.sh. - The work is committed.
An agent working alone loops through this:
- Read
docs/STATUS.md, then the last entries ofdocs/WORKLOG.md, thendocs/PLAN.md. Rungit statusandgit log -5to reconcile against reality, since a crash may have cut off the last log entry. - Take the first unchecked item in PLAN. Write the four lines from CLAUDE.md (outcome, evidence, boundaries, stop condition) into the WORKLOG entry for it.
- Build it in small steps, running
scripts/ci.sh fastafter each one. - When it's done, follow the definition of done above.
- If the same problem defeats two attempts: record it in
docs/BUGS.md, mark the item blocked in STATUS, and move on to the next item that doesn't depend on it. Don't wait for an answer. - Questions for Deva go under "Waiting on Deva" in STATUS. Work continues on everything else.
- Checkpoint the WORKLOG at least every hour, even mid-task.
Things an unattended agent never does: force-push, create or change remote repos, publish a release, change
GitHub settings, use sudo, delete files outside the repo, download anything other than Homebrew formulas
and the files listed in DECISIONS, or enter credentials.
The site is static files in website/. It goes to the Cloudflare Pages project knobs
(https://knobs.pages.dev, created 2026-10-20) by direct upload from this Mac, with no hosted CI:
npx wrangler pages deploy website --project-name knobs --branch mainWrangler 4.135 sends pages project create to Cloudflare Workers unless it gets --force: on 2026-10-20 it
deployed a Worker instead of making a Pages project, and wrote a wrangler.jsonc and .gitignore lines into
the repo. The project exists now, so never run create again; pages deploy goes to Pages. Wrangler answers its own prompts "yes" when not run interactively, and it touches
only what the command names, so name knobs and nothing else: the Cloudflare account holds Deva's other work.
Check the printed URL in a browser at desktop and phone widths after each deploy. Deva is buying a domain for
the site on Cloudflare; once it is attached, add the link-preview image tags listed in website/README.md with
that address and deploy again.
scripts/release.sh 0.2.0 does the following on this Mac. It checks first that project.yml and
CHANGELOG.md both name the version, that project.yml has Sparkle's SUPublicEDKey, and that its
CFBundleVersion is higher than every build in website/appcast.xml (Sparkle compares that number, not the
version; raise it by one each release).
-
Runs
scripts/ci.sh release, which also builds the Release app. -
Signs Sparkle's helpers, Sparkle and then the app with the Developer ID Application certificate and the hardened runtime.
-
Submits it with
xcrun notarytool submit --keychain-profile knobs-notary --wait, then staples it. -
Builds the DMG with
diskutil image create, then signs, notarizes and staples the DMG too. -
Writes
dist/Knobs-0.2.0.dmgand its SHA-256. -
Checks the website: the version in
website/index.html's#releaseblock must match, and every file it links to must be indist/. -
Adds the stapled DMG to Sparkle's feed,
website/appcast.xml, with Sparkle'sgenerate_appcast: signed with theknobskey from the login keychain (the keychain may ask to allow it), the version's CHANGELOG section as the notes, and a download address on the GitHub release. It fails if the new entry isn't signed. -
Prints the
gh release createcommand for Deva to run, with the DMG and the same version's Linux packages fromdist/linux/. It doesn't run it. -
Fills in the Homebrew cask from
scripts/homebrew/knobs.rbtodist/homebrew/knobs.rb(DEC-025).
Only after the release exists: commit website/appcast.xml and deploy website/ (see Website above), and put
dist/homebrew/knobs.rb in the deva0x/homebrew-knobs tap as Casks/knobs.rb, then check it there with
brew audit --cask --online deva0x/knobs/knobs. Before that, the feed, the download buttons and the cask would
point at files that aren't there.
Without the certificate it skips steps 2 to 4 and leaves an unsigned DMG, saying so. Without the notary profile it signs but doesn't notarize, and says so.
After the release is on GitHub, an agent or Deva pushes dist/linux/aur/PKGBUILD and .SRCINFO to the AUR's
knobs-gui-bin repository (ssh://aur@aur.archlinux.org/knobs-gui-bin.git, branch master). Not before: that
PKGBUILD downloads the release's x86_64 tarball and checks it against the checksum it carries. A change to the
PKGBUILD alone, with the same tarball, raises pkgrel instead of the version.
One-time setup only Deva can do:
- Create a Developer ID Application certificate: Xcode → Settings → Accounts → your team → Manage Certificates → + → Developer ID Application.
- Store notarization credentials:
xcrun notarytool store-credentials knobs-notary --apple-id <your Apple ID> --team-id P564YR8496It prompts for an app-specific password, which you create at account.apple.com. - Make the update signing key (DEC-024), once, after any build has fetched Sparkle:
build/DerivedData/SourcePackages/artifacts/sparkle/Sparkle/bin/generate_keys --account knobsIt keeps the private key in the login keychain and prints the public key. Put that public key inproject.yml, under the app'sinfoproperties, asSUPublicEDKey: "<key>". Back up the private key (generate_keys --account knobs -x <file>, kept somewhere safe and never in the repo): without it no copy of Knobs can be updated again.
Before checking an app milestone, launch the built app and confirm:
- the tool list shows every manifest, and missing tools show the install command
- a task runs end to end on a real file, and the output appears next to the input
- Cancel stops a running task within 2 seconds
- the window works in light mode, dark mode, and with the keyboard only
Save a screenshot to docs/screenshots/ and mention it in the WORKLOG entry.