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.

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:3001
[kalp] watching for prompts from <Kalp /> component...
[kalp] cwd: /path/to/your/project

Port discovery and the .kalp-port file

The server tries ports 3001 through 3010 and uses the first free one. If it didn't get the default, it says so:

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

No configuration is needed on the browser side — the <Kalp /> component probes the same range and finds the server (see discovery).

While running, the server writes the chosen port to a .kalp-port file in your project root and removes it on shutdown (Ctrl + C). It's a scratch file — add it to your .gitignore:

# .gitignore
.kalp-port

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.