Skip to content
OpenWaggle

Project actions reference

Every project action option and its default, script suggestions, run states, and the fields of .openwaggle/actions.json.

This page lists the exact values for project actions. To save, run, or share an action, or set up worktrees, start with the Project actions guide.

Optional settings

The questions under Optional settings in the action panel, with their answers and defaults.

QuestionAnswersDefault
Does it stop on its own?Yes, it finishes by itself (Stops when done), No, it keeps running until I stop it (Keeps running)Finishes by itself. Keeps running for a long-running script.
If you click it while it is still runningShow me the run that is already going, Start another copyShow the run already going. Only for an action that finishes by itself.
Open it in the browser preview?Yes, open the preview when the server is ready, No, I will open it myself, and an optional preview URLYes for a long-running script, otherwise no. Only for an action that keeps running.
Who should have this action?Just me, Everyone working on this projectJust me
Who should get these changes?Only me, Everyone on the projectAsked instead of the question above when you edit a shared action.
Which folder should it run in?A folder inside the workspaceThe project folder, or a script’s package folder
Keyboard shortcutOne key combination, or More shortcut optionsNone
Icon in Project Actionsplay, test, lint, configure, build, debugFrom the script name, otherwise play

Setup and cleanup ask Who should have this setup? or Who should have this cleanup?, with Just me as the default, and a folder.

Script suggestions

When you pick a script, OpenWaggle fills in a name, an icon, and whether it keeps running.

ScriptSuggested name
devStart dev server
startStart
serveStart server
previewPreview build
testRun tests
buildBuild
lintLint
typecheckCheck types
checkRun checks
formatFormat code

Another script gets its own name with :, _, and - turned into spaces and the first letter capitalized. A script in a package folder adds the folder’s name, as in Start dev server (website).

A script is long-running, so it gets Keeps running and opens the preview, when its name is dev, start, serve, watch or preview, or starts with one of them followed by a character other than a letter, digit or _ (such as dev:web or start-prod), or ends in :dev, :watch or :serve.

The icon comes from the first rule that matches the script name:

Name containsIcon
test, spec, e2e, vitest, jesttest
lint, check, format, typecheck, biomelint
build, bundle, compile, packagebuild
debug, inspectdebug
prepare, setup, install, configure, generate, bootstrapconfigure
Anything elseplay

Run states

The state of an action’s latest run, shown in the Project Actions panel.

StateMeaning
StartingThe command is starting.
RunningThe command is running.
ReadyAn action that keeps running is running, and its server answers.
StoppingStop or Restart is ending the run.
CompletedThe command exited successfully.
FailedThe command exited with an error, or could not start.
StoppedYou stopped it.
InterruptedThe background Session Host stopped while the run was going, for example when the computer restarted. Choose Restart to run it again.

The actions.json file

.openwaggle/actions.json holds the actions, setup, and cleanup shared with everyone on the project. The Project actions guide has an example file. Its JSON Schema is project-actions-v1.schema.json.

FieldMeaning
versionAlways 1.
actionsUp to 100 actions. Each id must be different.
actions[].idUp to 128 letters, digits, ., _, and -, starting with a letter or digit. Settings generates it.
actions[].nameThe name in the Project Actions panel, up to 120 characters.
actions[].iconplay, test, lint, configure, build, or debug.
actions[].invocationWhat runs: a command or a project script. See Invocations.
actions[].kindtask for Stops when done, service for Keeps running.
actions[].allowConcurrenttrue for Start another copy. Must be false for a service.
actions[].autoOpenPreviewtrue opens the browser preview when the server is ready.
actions[].previewUrlOptional. The http or https address to preview instead of the one found in the output, without a user name or password.
actions[].shortcutRulesOptional. Keyboard shortcuts, recorded in the panel or in Settings > Shortcuts. At most 256 in a project.
profilesUp to 20 extra setup profiles, each { "id", "name" }. The default profile needs no entry.
preparationSetup and cleanup commands.
preparation[].idAn identifier, with the same rules as an action’s.
preparation[].profileIddefault, or the id of an entry in profiles.
preparation[].phasesetup, which runs when a managed worktree is created and before the agent’s first turn, or cleanup, which runs before the worktree is removed. A profile has at most one of each.
preparation[].invocationWhat runs, as for an action.

Every key is required except previewUrl, shortcutRules, and a task’s environment. A missing or unknown key, "$schema" included, makes the whole file invalid: Settings > Project actions shows the error, and none of the project’s actions work, your own included, until you fix it.

Invocations

FieldMeaning
typecommand for a command you typed, task for a project script.
commandWith command: the command line, run by your shell, up to 8,192 characters.
directoryWith command: the folder it runs in.
task.providerWith task: package-script for a package.json script, hatch-script for a Hatch environment script, or cargo-alias for a Cargo alias.
task.sourceThe file that defines the script, such as packages/web/package.json.
task.taskThe script’s name, such as test, up to 120 characters.
task.directoryThe folder the script runs in. For a package script, the folder of its package.json.
task.environmentOptional. The Hatch environment of a hatch-script.

Folders and files are relative to the workspace root, with forward slashes, up to 4,096 characters. . is the root, and .. is not allowed.

Shortcut rules

FieldMeaning
shortcut.keyThe key.
shortcut.mod, ctrl, shift, alt, metaOptional. true for each modifier the shortcut uses.
whenOptional. A condition, using context names with !, &&, ||, and parentheses, up to 256 characters.
orderOptional. Precedence among project action shortcuts. A later order wins.

Recovery files

Each time OpenWaggle saves .openwaggle/actions.json, it keeps recovery files from that save in .openwaggle/action-recovery/, which Git ignores.

FileContents
previous.jsonThe file as it was before the save. An external editor may still have it open.
next.jsonThe save OpenWaggle prepared.

If a save clashes with an edit made outside OpenWaggle, Settings keeps both drafts and shows the recovery folder under Inspect pending drafts. OpenWaggle does not delete these files, because an editor can finish writing after the save. Close other editors, finish any pending save, and compare the files with .openwaggle/actions.json before you delete old recovery folders yourself.