README.md

<p align="center">
  <strong>English</strong> · <a href="./README.zh-CN.md">简体中文</a>
</p>

# Brancha

[![CI](https://github.com/Sider-ai/brancha/actions/workflows/ci.yml/badge.svg)](https://github.com/Sider-ai/brancha/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

![Brancha hand-drawn flora: red flower, succulent, sunflower, pine, and bamboo](media/brancha-flora.png)

Brancha is a local creative canvas where your own AI Agent grows ideas into a visual tree. Each node has a title, may contain text, and may carry an HTML, Markdown, SVG, image, video, or audio artifact.

- Use Codex, Claude Code, or another Agent you already have—no built-in model or extra model API key
- Keep prompts, nodes, and artifacts on your machine
- Run the bundled release without installing frontend or backend dependencies

## Contents

- [🌱 Install for your Agent](#-install-for-your-agent)
- [🌿 Start creating](#-start-creating)
- [🌳 How Brancha works](#-how-brancha-works)
- [🍃 Local data and security](#-local-data-and-security)
- [🪴 Development](#-development)
- [License](#license)

## 🌱 Install

After public release, find **Brancha** in the Plugins directory in ChatGPT Work mode or Codex.

In **Claude Code**:

```
/plugin marketplace add Sider-ai/brancha
/plugin install brancha@brancha
```

For local development, install the repository root as the plugin root. The skill entry point is
[`skills/brancha/SKILL.md`](skills/brancha/SKILL.md). The Agent handles setup, startup, and the
appropriate interface for each task.

## 🌿 Start creating

After installation, tell your Agent:

> Use the Brancha Skill to create a new design project. Requirement: ...

To open Brancha manually, use Node.js 22.5 or newer:

```bash
git clone https://github.com/Sider-ai/brancha.git
cd brancha
node skills/brancha/scripts/brancha.mjs setup
node skills/brancha/scripts/brancha.mjs start
```

`start` prints the canvas URL, normally [http://127.0.0.1:9519](http://127.0.0.1:9519). Normal Skill users do not need `npm install`.

Ask your Agent to use light mode, dark mode, or the system theme whenever needed. Open canvas pages update immediately.

The interface supports Simplified Chinese, English, Japanese, Spanish, and German. Ask your Agent to switch languages at any time; the setting persists and open pages update immediately.

## 🌳 How Brancha works

Every item on the canvas is the same kind of node:

- **Title** — the basic mind-map branch
- **Content** — optional plain-text detail
- **Artifact** — optional HTML, Markdown, SVG, image, video, or audio creation

The tree stays simple while the Agent can choose the fastest route underneath: SQLite for structure, files for artifacts, CLI for common actions, or HTTP API for integrations. Those implementation details live in [`skills/brancha/SKILL.md`](skills/brancha/SKILL.md) and [`skills/brancha/references/`](skills/brancha/references/) so users do not have to learn Agent-facing commands.

## 🍃 Local data and security

Brancha stores user data outside the repository:

- macOS: `~/Library/Application Support/Brancha/`
- Windows: `%APPDATA%\Brancha\`
- Linux: `${XDG_DATA_HOME:-~/.local/share}/brancha/`

Back up the complete data directory to preserve both the tree and its artifact files.

Brancha listens on the local machine by default. Generated artifacts are treated as untrusted content and rendered in sandboxed previews. Provider API keys remain in the user's Agent environment and must never be stored in Brancha. See [`SECURITY.md`](SECURITY.md).

## 🪴 Development

```bash
cd skills/brancha/app
npm ci
npm run dev
```

Before committing, run `npm run check`. See [`CONTRIBUTING.md`](CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), and [`CHANGELOG.md`](CHANGELOG.md).

## License

[MIT](LICENSE) © 2026 Sider AI. Bundled dependency licenses are listed in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).