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 42424)  │            │ (edits src) │
└─────────────┘          └───────────────┘            └─────────────┘

How the component finds the server

When <Kalp /> mounts, it probes ports 42424 through 42443 — all twenty in parallel, with a 500 ms timeout — and collects every kalp server that answers. Each server introduces itself with the project it serves: its name (from that folder's package.json) and its folder path. The response also carries a claude field — whether the Claude Code CLI is installed and credentialed — which the panel uses to warn you before you try to apply anything.

What happens next depends on how many servers answered:

• None — the component logs a console warning reminding you to run kalp next to your dev server.
• One — it connects silently. This is the everyday case.
• Several (you have multiple projects running kalp) — it refuses to guess. A web page cannot know which folder on disk it came from, and guessing wrong would send your edits to another project's source code. Instead, a small picker appears above the paintbrush button listing each server's project name and port. You pick once; the choice is saved in the browser (per app address) and re-verified on every reload — kalp asks the remembered server "are you still serving that same folder?" before trusting it, so a stale memory clears itself instead of connecting you to the wrong project.

As a final safety net, every apply request carries the folder path the page believes it is bound to. If the server at that port now serves a different project (ports can be recycled when you restart things in a different order), it answers 409 bridge mismatch and refuses to touch any files; the component then re-discovers and asks you to try again. Two servers accidentally started in the same project are treated as one — either works, so no picker appears.

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.