Scripts

Scripts lists everything your project can run — its package.json scripts, Makefile targets and justfile recipes, plus the commands you save — and runs any of them in one click. Scripts run locally on your Mac and are available on Free.

Run a script

1. Open Scripts from the right sidebar’s panel list or with ⌘⇧9.
2. Hover a script and click ▶, double-click it, or select it and press Return.

Its output opens in a dock under the list, or beside it when the panel is wide: the script’s status and how long it took, Stop while it runs and Run again once it has finished, the exact command and the folder it ran in, then the output itself. Drag the dock’s top edge to resize it; press Space to fold it away. Asking for a script that is already running shows it rather than starting a second copy, and Restart stops it and runs it again.

Use ↑ and ↓ to move through the list. The search field appears once a project has more than a dozen scripts, or with ⌘F.

What Scripts finds

Common scripts — test, lint, typecheck, build — come first in each group, and long groups show eight with Show all. Lifecycle scripts such as prebuild run along with their script, so they are hidden; ⋯ › Show Lifecycle Scripts lists them. Packages other than the root start closed; search reaches into closed groups and names the package each result comes from.

Codz reads these files and never runs anything to list them. Development servers and iOS or Android app runs live in Run; Scripts shows one row that opens it.

A script whose name says it deploys, publishes, releases or deletes something asks before every run.

The Run button and pinned scripts

The chat header’s run button runs one script in a click: the one you chose last in this project, or else the one you ran most recently. It shows that script’s own icon and name. Its menu lists your pinned scripts, recent ones and a few common scripts from your project; choosing one runs it and makes it the button’s script. ⌥⌘R runs or stops it from anywhere in the chat.

Pin a script with the pin on its row, from its ⋯ menu, or by dragging it onto the header. Pinned scripts appear as buttons after the run button, in the order you drag them to, and ⌃⌥1 to ⌃⌥9 run or stop them in that order; the Scripts panel shows each pin’s key. A pinned script has its own button and key, so running or choosing it leaves the run button as it is. When the header is narrow their labels go first, then the buttons themselves, which stay in the run button’s menu. Pins are private and follow the project into its worktrees.

Launching from the header leaves your panels as they are. The button shows a spinner while its script runs and a warning dot after it fails, and the Scripts tab shows a dot when a run finished while you were somewhere else.

Give a script a keyboard shortcut

Choose ⋯ › Keyboard Shortcut… on a script and press the keys you want. The shortcut runs the script, or stops it while it runs, in this project and its worktrees — in every project for a script saved for all projects. A shortcut belongs to one script, so giving it to another moves it, and the recorder says so. Press ⌫ in the recorder to remove a shortcut.

A shortcut needs ⌘ or ⌃, unless it is a function key. Codz turns down keys that would type, a shell’s control keys such as ⌃C, keys macOS keeps such as ⌘Space, and keys a menu already uses, and names what has them. Your shortcuts appear in the Scripts list, the header, ⌘K and Workspace › Script Shortcuts.

Save your own scripts

Click + in the Scripts toolbar, or choose Customize… on a found script to save your own copy. Give it a name and a command, then choose where it runs — Output panel for commands that print, Terminal for commands that ask questions — its folder, and who sees it:

Save & Run (⌘↩) saves the script and runs it. Your scripts, pins, review decisions and recent run results are saved on this Mac; they are not synced to your Codz account.

A shared script asks you to review its exact command, output mode and folder in the dock before its first run, and again after its command, folder or mode changes. Each checkout has its own review decisions. Codz reads definitions from the current worktree, so changing branches can change the available shared scripts.

You can create the shared file yourself. The minimum definition is:

{
  "version": 1,
  "scripts": [
    { "id": "test", "name": "Run tests", "command": "npm test" }
  ]
}

Optional fields are icon (code, terminal, play, app, globe, bolt, check, bug, wrench, folder, branch or cloud; defaults to code), description, directory, mode (console or terminal) and revision (defaults to 1). IDs are stable and unique within the file, and contain letters, digits, periods, underscores or hyphens. Directory paths must resolve inside the workspace.

If the shared file changes while you are editing, Codz asks you to reload before overwriting it. An invalid shared file shows an error; personal scripts remain available.

When a script fails

The dock says how — Failed · exit 1 · 12s — and Ask agent to fix puts the script’s name, command, folder, exit code and the end of its output into the composer. ⋯ › Add Output to Chat does the same for any run. Sending the draft to an agent is a separate step.

Codz keeps the last 64 KB of each run’s output on this Mac, redacted the way environment command output is, so it is still there after Codz restarts. ⋯ › History opens a script’s earlier runs.

If a script’s package manager isn’t installed where Codz can find it, the dock says so before anything runs, with the command that fixes it.

Runs keep going

Different scripts can run together; the same script runs once per workspace. A run keeps the definition it started with; editing a saved command affects the next run.

Switching chats, closing the Scripts panel or hiding Codz leaves scripts running. Stopping the Codz host ends them. After a host restart, unfinished runs appear as Interrupted and are not restarted automatically.

A service should keep its main process in the foreground: use npm run dev, for example, rather than launching it with & and exiting.

Commands and context

Scripts use zsh without loading your personal shell startup files. Codz supplies normal executable paths, project-local Node tools and its own codz command. Environment files are not loaded automatically; a command can explicitly load one when needed.

For example, inspect the current chat with:

codz sessions show --session "$CODZ_SESSION_ID"

Provider approval rules continue to apply. Scripts has no automatic schedules or lifecycle triggers.

Use the CLI

codz scripts list --folder /path/to/project --json
codz scripts run --script 'detected:pkg:.#test' --folder /path/to/project --json
codz scripts run --script "Run tests" --session CHAT_ID --json
codz scripts status --run RUN_ID --json
codz scripts stop --run RUN_ID --json

list returns every script with its ID: personal scripts start private:, shared ones repository:, and found ones detected: followed by where they came from — quote those in your shell. run takes an ID, or a name when exactly one script has it; a name several scripts share is refused with their IDs. list and run accept either --folder or --session; with neither, they use your terminal’s current folder.

The CLI can run a script read from your project’s files only after you have run that same command from Codz; until then, and after the file changes it, run answers trust_required. That keeps an agent from adding a script to package.json and running it outside its own permissions. Shared scripts are reviewed in Codz, and terminal scripts need an attached Codz window showing the same workspace.

run returns the run record and ID after launch; it does not wait for completion. Use status to read the final outcome and exit status. See CLI commands.