Reference

CLI

The kalp command starts the bridge server — the local process that receives edits from the browser and runs Claude Code against your project.

The kalp command

kalp [--port <number>]

Run it from your project root — the folder that holds your source code. That folder becomes the working directory Claude Code runs in, which is how kalp knows which project to edit. If the folder has a src/ directory, Claude Code is pointed there; otherwise it searches the whole folder.

Flag	Default	Meaning
`--port <number>`	auto (42424–42443)	Bind exactly this port; kalp exits with an error if it's busy. Without the flag, kalp scans the default range and takes the first free port. A custom port outside the range needs `<Kalp port={N} />` so the component can find it.

The usual way to run it is inside your dev script, so both servers start with one command:

// package.json
"scripts": {
  "dev": "kalp & vite"       // or "kalp & next dev"
}

On startup it prints:

[kalp] bridge server running on http://localhost:42424
[kalp] project: your-app
[kalp] watching for prompts from <Kalp /> component...
[kalp] cwd: /path/to/your/project

The project line is how the server introduces itself during discovery — the name comes from your project's package.json. When several projects run kalp at once, this name is what you'll see in the browser picker.

Port discovery

Without --port, the server tries ports 42424 through 42443 and uses the first free one. (Why 42424? It echoes kalp's #242424 panel color — and more importantly it sits far away from common dev-server ports like 3000 and 5173, so kalp can never race your frontend for a port.) If it didn't get the first port, it says so:

[kalp] note: default port 42424 was occupied, using 42425
[kalp] <Kalp /> will auto-discover this port

No configuration is needed on the browser side — the <Kalp /> component probes the whole range in parallel and finds every running server (see discovery). Up to 20 projects can run kalp at the same time.

Startup warnings

On startup the server checks whether Claude Code is ready. If the CLI is missing from your PATH:

[kalp] WARNING: claude code cli not found on PATH
[kalp]   install:  npm install -g @anthropic-ai/claude-code
[kalp]   then run `claude` once and use /login to authenticate
[kalp]   kalp will keep running, but "apply to code" will fail until fixed

If the CLI exists but no credentials can be found:

[kalp] WARNING: claude code appears to have no credentials
[kalp]   run `claude` in a terminal and use /login (or set ANTHROPIC_API_KEY)
[kalp]   kalp will keep running, but "apply to code" will fail until fixed

These are warnings, not errors — the server starts anyway so you can keep previewing in the browser. Once you fix the problem there is no need to restart: the check runs again automatically (it refreshes within about ten seconds, and always re-runs before an apply).

What the logs mean while applying

When you click apply to code in the browser, the terminal running kalp shows the whole run:

[kalp] received 3 edits across 1 components
[kalp] spawning claude...
...claude code's own output streams here...
[kalp] claude exited with code 0

Exit code 0 means the edits landed. Anything else comes back to the browser as a readable error message — see Troubleshooting.