Developer project scripts

Kolleague Desktop can discover setup and run commands from a project without running repository content automatically. Commands run only after you open the Scripts surface for an isolated Developer worktree, review the exact command, and trust the current config.

Config file

Add .kolleague/project.json to the selected project directory. The file is checked in with the repository and uses the Kolleague project schema:

{
  "$schema": "https://kolleague.getkommit.ai/docs/schemas/project.schema.json",
  "schemaVersion": 1,
  "setup": {
    "description": "Install dependencies for a new worktree",
    "command": ["pnpm", "install", "--frozen-lockfile"]
  },
  "scripts": {
    "dev": {
      "description": "Start the local development server",
      "icon": "play",
      "command": ["pnpm", "dev"],
      "commandId": "project.script.dev"
    },
    "test": {
      "description": "Run focused unit tests",
      "icon": "test-tube",
      "command": ["pnpm", "test"]
    }
  },
  "preferredScript": "dev"
}

scripts is keyed by stable lowercase IDs. Each script has a description, a lowercase kebab-case icon name, and a command. preferredScript is optional. If commandId is omitted, Kolleague derives project.script.<script-id>; explicit IDs must use that same namespace and be unique.

Commands are arrays: the first item is the executable and the remaining items are arguments. Kolleague spawns that array directly in a PTY rooted at the active Developer worktree. It does not interpolate a shell command string, expand variables, or interpret pipes, redirects, &&, semicolons, or backticks. Put multi-step shell logic in a checked-in workspace-relative wrapper script and invoke that file directly. Absolute executables, traversal paths, and shell -c command strings are rejected.

The config is limited to 128 KiB and 32 named scripts. Unknown fields, duplicate command IDs, unsupported schema versions, oversized commands, invalid preferred IDs, symlink escapes, and malformed JSON produce field-specific validation messages and cannot execute.

Trust and local preferences

Repository config is untrusted executable content. The Scripts surface shows every resolved command before the first trust decision. Trust is recorded for the SHA-256 hash of the exact config in the exact Developer worktree. Editing the config changes the hash and blocks setup and scripts until the new commands are reviewed and trusted.

Trust, setup markers, and a locally selected preferred script live in Kolleague's app-data directory. Kolleague never writes those choices into .kolleague/project.json, so a user-local preference cannot rewrite or dirty checked-in configuration. The two configurable Desktop shortcut command IDs are developerOpenProjectScripts and developerRunPreferredProjectScript; they are unassigned by default and can be bound under Settings → Shortcuts → Developer. Running the preferred shortcut still requires a currently trusted config.

New-worktree setup

Setup is opt-in. Creating or adding a repository never runs it. A new Developer worktree starts in pending state; select Run setup after trusting the displayed config. Kolleague records a completion marker for that worktree only after exit code 0.

While setup runs, the surface shows running and offers cancellation. Exit code 0 records succeeded; a nonzero exit or spawn failure records failed. Cancellation records cancelled. A successful setup does not run again automatically, even after reopening the app. Select Retry setup to run it explicitly again. A setup marker is app-local and is removed only when the app data is cleared; it is not committed to Git.

Runs and output

Each run uses a main-process-owned PTY registered to the active Developer worktree and renderer session. Kolleague displays the exact command, running or terminal status, exit code, and the app-local log location. Reveal output opens that log in the operating system. Switching or hiding workbench surfaces does not transfer ownership to another session.

Archiving or permanently deleting a Developer session cancels its active project-script runs before releasing the trusted worktree registration. Closing the app cancels remaining owned runs. Existing source checkouts and unrelated dirty work are never used as the command working directory.

Troubleshooting