Conversational application building

clank compose turns an application request and an agent-proposed blueprint into a reviewable, deterministic Clank project. The agent proposes data; Clank remains the authority that validates, plans, and writes the application.

#The shortest safe loop

Ask a coding agent to create a data-only clank.app.ts, then review it without changing any application files:

clank compose ./my-app \
  --request="Build a private client portal with projects and tasks" \
  --proposal=./proposals/client-portal.clank.app.ts \
  --json

The result is a clank-compose-result/1 review containing:

• the review ID;
• a SHA-256 digest for the exact generated plan;
• every file that would be created, updated, or left unchanged;
• blueprint counts and validation warnings; and
• the exact apply command.

Run that returned command only after inspecting the plan:

clank compose /absolute/path/to/my-app \
  --review=<review-id> \
  --approve=<plan-digest> \
  --json

The target path is part of the stored review. The approval is accepted only when its digest exactly matches the reviewed plan and every destination still has the same baseline. If a person, agent, formatter, or build changes a reviewed file first, Clank rejects the review as stale.

#Interactive use

Run clank and choose Build with an agent, or call clank compose directly in a terminal. The direct command prints the proposed file changes and asks whether to apply, revise, or cancel. Revision is available when an external agent executable is configured:

clank compose ./my-app \
  --request="Build a lightweight issue tracker for a design team" \
  --agent=./tools/my-clank-agent

Clank can request up to four proposals in one conversation by default. Set --max-turns from 1 through 10 and --agent-timeout from 1 through 600 seconds. Non-interactive agents and CI should use --json and perform review and approval as separate commands.

#External agent protocol

--agent is provider-neutral. Its value must be a real executable file, not a shell command or a symbolic link. Clank starts it without a shell, writes one JSON object to standard input, and expects one JSON object on standard output.

The request is clank-compose-request/1:

{
  "protocol": "clank-compose-request/1",
  "turn": 1,
  "intent": "Build a private client portal",
  "feedback": null,
  "currentBlueprint": null,
  "history": [],
  "constraints": {
    "frameworkVersion": "0.13.0",
    "approvalRequired": true,
    "dataOnlyBlueprint": true,
    "neverIncludeSecrets": true
  }
}

The response must be exactly a clank-compose-proposal/1 proposal:

{
  "protocol": "clank-compose-proposal/1",
  "type": "proposal",
  "message": "Added private projects, task ownership, and workspace roles.",
  "blueprint": {
    "name": "Client Portal",
    "description": "A private project and task workspace.",
    "entities": {
      "projects": {
        "description": "A customer project.",
        "ownership": "user",
        "displayField": "name",
        "fields": {
          "name": { "type": "string", "min": 1, "max": 120 }
        }
      }
    },
    "routes": [
      { "path": "/", "view": "Projects", "entity": "projects" }
    ],
    "actions": {}
  }
}

The blueprint must satisfy the complete AI blueprint contract. Unknown response fields, invalid protocols, invalid blueprints, output over 1 MiB, nonzero exits, and deadlines fail closed. Diagnostic stderr is capped at 32 KiB.

Clank passes only a small process environment needed to start the executable; arbitrary CLI and application environment variables are not forwarded. For an existing app, the normalized current blueprint is sent as context but deployment.env is withheld and preserved if the next proposal omits it.

The executable still runs as the current operating-system user and therefore has that user's file and network authority. Use a program you trust, sandbox it when appropriate, and prefer --proposal when a coding agent has already prepared the blueprint through its own controlled environment.

#Mutation and rollback contract

Creating a review writes only an owner-readable file under:

.clank/compose-reviews/<review-id>.json

Application files are not written until approval. Apply uses temporary files and atomic renames. If any destination or parent becomes unsafe, including through a symbolic link, Clank restores files already touched during that apply. A successful apply retains an owner-readable audit record at:

.clank/compose-sessions/<review-id>.json

.clank/ is excluded from generated repositories. Reviews can contain product requirements and public deployment configuration, so treat the directory as private local state. Never place passwords, access tokens, private keys, or other secrets in a blueprint; provision deploy secrets with clank secrets.

#Existing applications

Point compose at a generated application to evolve it:

clank compose . \
  --request="Add customer notes and a read-only auditor role" \
  --agent=./tools/my-clank-agent \
  --json

The current normalized blueprint becomes agent context. The review reports update only for files whose generated contents change. Hand-written changes to generated destinations are visible in the baseline and are never silently overwritten after review.

After applying, verify the product contract and deploy normally:

npm install
npm test
clank doctor
clank deploy

Composition does not authenticate or deploy. It produces the same ordinary, inspectable Clank project that clank create and clank generate produce, so the existing build, migration, security, MCP, and deployment contracts remain in force.