Docs

How It Works

There is no magic in kalp — just three small pieces passing simple messages. Knowing how they fit together makes the tool predictable and easy to debug.

The three pieces

1. The <Kalp /> component runs in your browser. It draws the editor UI, records your edits, and previews them live on the page.
2. The bridge server (the kalp command) runs on your machine, in your project folder. It is the only piece that can touch your files.
3. Claude Code is the CLI that actually edits source code. The bridge hands it a precise instruction; Claude Code finds the right file and makes the change.

browser                      your machine
┌─────────────┐   HTTP   ┌───────────────┐   spawns   ┌─────────────┐
│  <Kalp />   │ ───────► │ bridge server │ ─────────► │ claude code │
│  (edit log) │          │  (port 3001)  │            │ (edits src) │
└─────────────┘          └───────────────┘            └─────────────┘

How the component finds the server

When <Kalp /> mounts, it probes http://localhost:3001/kalp/port, then 3002, and so on up to 3010, each with a 300 ms timeout. The first port that answers { ok: true } becomes the bridge URL for the session. This is why the bridge needs no configuration: whichever free port it picked, the component finds it within a second.

The same response also carries a claude field — whether the Claude Code CLI is installed and whether credentials were found. The panel uses this to warn you before you try to apply anything. If no port answers, the component logs a console warning reminding you to run kalp next to your dev server.

How edits are recorded and previewed

When you select an element, kalp reads the element's computed styles and fills the panel with the current values. It also walks React's internal fiber tree to learn which component rendered that element — that name is what appears in the panel header, and it's how the source file is found later.

Every change you make does two things at once:

• Live preview. The new value is applied as an inline style on the element (and on other on-screen instances of the same component), so you see it immediately.
• Edit log. kalp records one entry per CSS property: the component name, the element's position inside that component, the property, the value before, and the value after. Change the same property five times and the log still holds one entry — first "before", latest "after". Undo a property back to its original value and its entry is removed entirely.

Nothing has touched your files yet. Reload the page and the preview is gone. The log only leaves the browser when you click apply to code.

How edits reach your source code

Clicking apply to code sends the edit log (plus your optional free-form prompt) to the bridge at POST /kalp/edits. The bridge then:

1. Builds an instruction. The edits are grouped by component and element, with before → after values, plus rules: find each component's source file (inside your project's src/ folder if one exists), detect the styling approach it uses, and express the change in that same idiom. If your project uses Tailwind, a 16px corner radius becomes rounded-2xl, not an inline style. The "before" values help Claude locate the right existing declaration.
2. Spawns Claude Code. It runs claude -p "<instruction>" --permission-mode acceptEdits with your project root as the working directory. Claude Code reads the files, makes the edits, and exits. Its output streams to the same terminal where kalp is running, so you can watch it work.
3. Reports back. Exit code 0 means success — the browser removes the inline preview styles, and your dev server's hot reload shows the same change now coming from real source code. Any failure returns a plain-language error that the panel shows in red.

Credential checks

Because everything depends on Claude Code, kalp checks it at three moments:

• At server startup — if the claude binary is not on your PATH, or no credentials can be found, the terminal prints a warning with the exact commands to fix it. The server still starts; previewing works without Claude Code.
• At discovery — the component learns the same status from /kalp/port and shows a warning in the panel before you waste a click.
• Before every apply — the server re-checks fresh. If Claude Code is missing or logged out it answers with a clear error instead of spawning. And if a run still fails (for example the login expired mid-session), the server captures Claude's real output and forwards the actual message — never just an exit code.

The check itself is free and instant: it looks for the binary on your PATH and for any of Claude Code's credential sources (environment variables like ANTHROPIC_API_KEY, or the login files under ~/.claude/). It never makes an API call and never opens your keychain. On macOS, if no source is visible, kalp assumes the login may live in the keychain and simply lets the run proceed — a real failure is still caught and explained.

What kalp can and cannot do

• It runs only in development — the bridge is a local server you start by hand, and the component is meant to be rendered behind a NODE_ENV check.
• It edits only the project where you started kalp — that folder is the working directory Claude Code runs in.
• It never edits without you clicking apply. Hovering, selecting, and previewing are browser-only.