Testing
Setup and run scripts, environment detection, and running tests in a workspace.
Each workspace has a console panel with Setup, Run, and Terminal tabs. Setup and Run are scripted commands with live output and a status badge; Terminal is a full interactive shell in the worktree.
Environment detection
When you add a project, Kalauz inspects the repo root and pre-fills sensible setup and run commands. First match wins:
| Marker in repo root | Setup | Run |
|---|---|---|
pnpm-lock.yaml | pnpm install | pnpm dev |
yarn.lock | yarn install | yarn dev |
package.json | npm install | npm run dev |
*.sln / *.csproj | dotnet restore | dotnet run |
pyproject.toml | uv sync | — |
requirements.txt | pip install -r requirements.txt | — |
go.mod | go mod download | go run . |
Cargo.toml | cargo fetch | cargo run |
Gemfile | bundle install | — |
You can override any of these in the project's settings.
Setup script
The Setup script runs once, automatically, right after a workspace's worktree is created — installing dependencies so the agent starts on a working tree. You can re-run it any time from the Setup tab.
Run script
The Run script is yours to define — usually the dev server or a test command. Run it from the Run tab whenever you want to exercise the agent's changes.
# A Run script can be anything — your test suite, for instance:
pnpm test
Concurrency
By default every workspace can run its Run script at the same time. If that causes collisions — two workspaces fighting over the same port — set the project's run-script mode to nonconcurrent. Kalauz then allows only one Run at a time per project; others wait until you stop the active one.
Configuring scripts
Scripts resolve in this order, first non-empty wins:
- The value in the project's settings.
- A
kalauz.jsonchecked into the repo (scripts.setup,scripts.run,scripts.archive,runScriptMode). - The auto-detected command from the table above.
A kalauz.json lets a repo carry its own setup so every teammate's workspaces
behave the same.
The interactive terminal
The Terminal tab is a real shell rooted in the worktree — run ad-hoc commands, inspect git state, or drive your tests by hand.
What's next?
- Review and merge a workspace — once tests pass, ship it.