Thanks for helping. Most contributions are one of three things: a new task for a tool Knobs already has, a manifest for a new tool, or a fix. None of the first two needs any Swift.
You need macOS 26 or later on Apple Silicon, Xcode 26 or later, and XcodeGen (brew install xcodegen).
scripts/install-hooks.sh # once per clone: runs the checks before every commit and push
scripts/ci.sh # lint, unit tests, integration tests and an app build
scripts/run-app.sh # build and open the appAll checks run on your own Mac. Knobs has no hosted CI, and pull requests must not add any: scripts/ci.sh
fails if .github/workflows exists.
Every tool is one JSON file in Manifests/. The full format is in docs/MANIFEST_FORMAT.md. This is the short version.
- Copy a similar manifest.
Manifests/rsync.jsonis a good small example;Manifests/ffmpeg.jsonshows most features. Give the tool a lowercaseid, its bareexecutablename (never a path), the Homebrew formula underinstall, an SF Symbol and a tint. - Write tasks people actually ask for, in plain words: "Shrink a video", not "Transcode with libx264". Three to six tasks is right. Anything rarer is still reachable through Extra arguments and All options.
- Describe the fields, such as files, folders, choices, numbers, on/off switches and text. Labels are short and plain. Give everything a sensible default so most people only drop a file and press Run.
- Write the arguments as a list. Each item becomes exactly one argument;
{field}puts a value in,{extra}marks where Extra arguments go (exactly once), and{ "if": ..., "then": [...] }adds arguments only when a switch is on or a choice matches. Knobs never uses a shell, so there is no quoting to get right. - Name the output with an
outputrule, so Knobs can show the result and never overwrite a file. - Add progress if the tool prints a percentage or a time, so the window can show a progress bar.
- Test it:
swift test --filter ManifestLoadingTestschecks that every manifest in the folder loads and validates.- Add a golden test in
Tests/KnobsCoreTests/CommandBuilderTests.swiftif the task has conditionals. - Add your tool to
Tests/KnobsCoreTests/Integration/ToolIntegrationTests.swiftso every task really runs on a tiny file. Tests skip when the tool isn't installed, unlessKNOBS_REQUIRE_TOOLS=1is set. - Run the task once in the app and check the result.
If the format can't express something your tool needs, open an issue first. Tool-specific behavior belongs in
the manifest, so the fix is usually a small, general addition to the format and to KnobsCore together.
- Read CLAUDE.md (the repo's working rules, for people and agents alike) and docs/WORKFLOW.md.
- Tools always run through
Processwith an argument list, never through/bin/sh -cor a command string. - UI changes follow docs/DESIGN.md and its review checklist. Include light and dark screenshots in the pull request.
- Keep one concern per commit, and write the message as
area: why, for examplemanifests: add a Trim task to ffmpeg. - Format with
xcrun swift-format format --in-place --recursive Sources Tests App.
Say what you did, what you expected and what happened, and include the command Knobs showed (the Copy button in the command bar copies it). Leave out personal file paths if you'd rather not share them.