Editing an App

An App keeps its project files in its own branch — a named list of path → contents that lives inside the runtime, not on your disk. Editing an App means changing that branch. There are two ways to do it, and both end at the same place.

• You type. Open a file, change it, save.
• You describe. Write one sentence about what you want changed, pick the files it touches, and the agent proposes new contents for each one.

The second way is the one that needs a safety net, so that is where this page starts.

Nothing applies until you accept

When you describe a change, the runtime does not write it. It runs an edit pass over each file you selected and returns a proposal: the file's current contents and the proposed contents, side by side, as a diff — one diff per file.

Describing a change needs a model to be served, because a model is what writes the proposal. Reading files, typing edits yourself, locking, and unlocking all work with no model at all.

Typing an edit yourself

In the console's Files tab, select a file to view it. Edit opens the editor in place; Save stays disabled until you have actually changed something, and Cancel drops the edit. The same file also offers the agentic review path, so you can start by hand and finish by describing, or the reverse.

From the terminal, editing is a read-then-write pair. kx app cat prints the file, and kx app edit replaces it from a local file.

kx app files apps/local/my-app
kx app cat apps/local/my-app README.md

kx app files lists the branch — every path, its content reference, and the count. kx app cat prints one file's body to your terminal, or writes it to disk:

kx app cat apps/local/my-app README.md --out ./README.md

Edit that local copy in whatever editor you like, then push it back:

kx app edit apps/local/my-app README.md --from ./README.md

kx app edit writes straight through with no review gate. The propose → diff → approve gate lives in the console and in the SDKs; use it when you want to see the change before it lands.

Reading the App's shape

Files are one half of an App. The other half is its structure — the steps the App runs and the edges between them. Print it with:

kx app structure apps/local/my-app

You get a line per step (its kind, and its model route, tools or turn budgets when it has them) and a line per edge. For the raw structure as stored, add --json:

kx app structure apps/local/my-app --json

The console shows the same thing as a diagram in the Lineage tab. Both are read-only views — they tell you what the App is, they do not change it. Structure is authored where the App is built; see Apps.

Lock it when you are done

An App that works is worth freezing. A lock is a policy switch on the App's project branch, set by you, that refuses writes:

kx app lock apps/local/my-app

Prints app apps/local/my-app locked. While the lock is on, the runtime refuses:

• file edits — any change to a file in the App's branch, whether it came from the console, the CLI, an SDK, or the agent;
• structure edits — re-saving the App's envelope, so the shape cannot be changed either;
• scaffolding — the agent cannot write a fresh project tree over it.

Refusals come back as a failed precondition carrying the code LOCKED_BRANCH, so a tool can act on the code rather than on the wording. The console checks the lock first and shows a notice in place of the editing controls, rather than offering you a control that will fail.

Running the App is unaffected. A lock stops the App from being changed, not from being used.

kx app unlock apps/local/my-app

Prints app apps/local/my-app unlocked. Both commands are idempotent — locking a locked App and unlocking an unlocked one both succeed and leave you in the state you asked for.

The same gate from code

The propose → review → approve sequence is three calls, so you can build your own review step. Read the branch first to capture each file's current reference — that reference is your rollback target.

kx app cat apps/local/my-app README.md --out ./before.md
cp ./before.md ./after.md
# edit ./after.md, then:
diff -u ./before.md ./after.md
kx app edit apps/local/my-app README.md --from ./after.md

from kortecx import KxClient

with KxClient("http://127.0.0.1:50151") as kx:
    handle = "apps/local/my-app"
    branch = kx.get_branch(handle)
    if branch is None:
        raise SystemExit("no project branch for this app")
    prior = {it.path: it.content_ref for it in branch.items}

    # PROPOSE — runs the edit pass, advances nothing.
    proposal = kx.edit_branch_propose(handle, "README.md", "add a short usage section")
    print(proposal.current_text)
    print(proposal.proposed_text)

    # APPROVE — re-point the path at the proposed contents.
    kx.advance_branch(handle, "README.md", proposal.result_ref)

    # ROLL BACK — re-point it at what it was before.
    kx.advance_branch(handle, "README.md", prior["README.md"])

import { KxClient } from "@kortecx/sdk/node";

const kx = new KxClient("http://127.0.0.1:50151");
const handle = "apps/local/my-app";

const branch = await kx.getBranch(handle);
if (branch === null) throw new Error("no project branch for this app");
const prior = new Map(branch.items.map((it) => [it.path, it.contentRef]));

// PROPOSE — one instruction, other files attached so the rewrite stays coherent.
const p = await kx.editBranchPropose(handle, "README.md", "add a short usage section", {
  contextPaths: ["README.md", "config.json"],
});
console.log(p.currentText, p.proposedText);

// APPROVE, then ROLL BACK.
await kx.advanceBranch(handle, "README.md", p.resultRef);
await kx.advanceBranch(handle, "README.md", prior.get("README.md")!);

A proposal that the model returns empty is refused rather than applied, so a model that answers with nothing cannot blank a file.

Getting a gateway up

Every command on this page talks to a running gateway. The bare serve command refuses to start without an explicit stance on authentication, which is deliberate:

kx serve --dev-allow-local

That is the local development stance, and it accepts loopback connections only. For anything else, start it with an auth token instead. See Install and Serving.

Next