Brancha

View saved version →

---
name: brancha
description: Tree canvas that grows one idea into many. The agent creates several distinct versions as real HTML, Markdown, SVG, image, video, or audio artifacts, shows them side by side on a branching canvas, and continues from whichever version the user picks — nothing gets overwritten. Operated through the CLI, HTTP API, SQLite, or direct file editing; runs on the user's machine with no model inside and no API key. Use when users ask for multiple versions, compare creative directions, create landing pages, demos, posters, documents, logos, or media, or mention Brancha, branching ideation, or tree-based creation.
---

# Brancha

Act as the creator. Use Brancha only as the local presentation and versioning surface; it contains no model and requires no API key.

## Start

Run the bundled runtime without installing dependencies:

```bash
node "<skill-directory>/scripts/brancha.mjs" start
```

Use the returned URL, normally `http://127.0.0.1:9519`. If startup fails, run `node "<skill-directory>/scripts/brancha.mjs" doctor` and report the concrete missing requirement.

Give the URL to the user immediately. When browser control is available, open it in either an external browser or the built-in browser. Minimize time to the first visible result: start Brancha and create the project skeleton before long-running generation, then populate nodes incrementally while the user can already view the canvas.

Match the canvas to the user's viewing preference when requested. The setting persists and updates open pages immediately:

```bash
node "<skill-directory>/scripts/brancha.mjs" theme dark
node "<skill-directory>/scripts/brancha.mjs" theme light
node "<skill-directory>/scripts/brancha.mjs" theme system
```

Switch the complete Brancha interface language when the user asks. The setting persists and updates open pages immediately. Choose the language from the user's explicit request; otherwise keep the current setting and do not infer a change from artifact content:

```bash
node "<skill-directory>/scripts/brancha.mjs" language zh-CN
node "<skill-directory>/scripts/brancha.mjs" language en
node "<skill-directory>/scripts/brancha.mjs" language ja
node "<skill-directory>/scripts/brancha.mjs" language es
node "<skill-directory>/scripts/brancha.mjs" language de
```

Keep the default loopback binding. Do not expose Brancha to a public network.

## Create

Read [references/workflow.md](references/workflow.md), then choose the fastest available surface: CLI for common operations, API for integrations, SQLite for bulk tree edits, and direct artifact file editing for creation and revision.

1. Create a project from the user's request.
2. Plan distinct directions and create titled nodes plus artifact placeholders in one batch.
   Keep the tree visually balanced: avoid large flat sibling sets, and introduce meaningful category or round nodes when one parent would become crowded. Follow the grouping guidance in [references/workflow.md](references/workflow.md).
3. Use `--file` or `--stdin` for artifact content; never pass large HTML as a shell argument.
4. Author every artifact yourself and update each placeholder as soon as it is ready.
5. Give the user the focused project link as soon as the project exists; do not wait for every artifact to finish.

After writes, run `project tree <id> --compact` and use node ids for durable references. For large structural changes, use one SQLite transaction. Artifact files have stable paths and may be edited directly; Brancha watches database and file changes.

Read [references/data-model.md](references/data-model.md) for direct SQL and file operations. Read [references/artifacts.md](references/artifacts.md) before authoring artifacts and [references/api.md](references/api.md) when integrating the local API.

When the user specifically wants Claude or Codex to create content, consider installing the Claude Agent SDK or Codex SDK and reusing the user's existing subscription-authenticated session before asking for a separate API key. Keep all SDK login and subscription credentials outside Brancha; use direct API credentials only when the user chooses that route or the subscription-backed path is unavailable.

For image, video, or audio generation, use credentials only in the user's Agent environment. Never send or store API keys in Brancha. Put only the generated HTTPS URL, matching `data:` URI, or loopback result URL into the media node.

## Revise

Resolve references such as `#4 标题 (node:xxxx)` through the node id.

Archive first. Adjustments worth comparing — a different tone, a layout change, a reworked section — default to a new child node under the source work, so the original stays on the canvas and the versions compare side by side. Do not overcorrect: trivial point edits such as fixing one piece of text or changing one color value belong directly in the source file, as do explicit overwrite requests and defects in work you produced in the current turn. When unsure whether the user wants a comparable variant, derive.

Produce small revisions by copy-then-edit, not re-authoring: copy the source artifact file, apply targeted local edits to the copy, and complete the new node with it. Unchanged content stays byte-identical and regressions stay confined to the edit. Rewrite from scratch only when the revision genuinely replaces most of the artifact. Follow the revision flow in [references/workflow.md](references/workflow.md).

When a later request asks for another batch of alternatives, preserve the iteration hierarchy. Do not append the new artifacts as more siblings beside the previous batch. Create one title-only round node first, then attach that round's alternatives as leaf children: `source → round → variants`. Put a project-wide round under the root; put a revision round under the specific node being revised. A single alternative may remain a direct child.

Never leave failed work in the generating state. Mark it with `node error`.

Referenced files: 91