Arbor

🇧🇷 Versão em Português · 📖 Detailed About

Open-source spatial desktop environment for autonomous multi-agent AI coding orchestration (Claude Code, Codex, OpenCode, Antigravity, and Pi/omp) on an infinite canvas.

Built with Tauri 2, Rust, and React 19.

---

🎯 The Problem

Running multiple CLI coding agents concurrently in modern software projects creates severe bottlenecks:

1. Workspace collisions: Multiple agents modifying the same directory overwrite each other's changes, hold file locks, and produce messy git conflicts.
2. Loss of spatial context: Switching across 10+ terminal tabs obscures task dependencies, who is waiting for whom, and what is currently executing.
3. Synthetic / Mocked agent UIs: Many visual tools emulate terminal output in Web UI components, breaking real CLI flags, interactive prompts, and ANSI TUI behaviors.
4. SaaS paywalls & platform lock-in: Existing workspace tools lock features behind monthly cloud subscriptions or restrict usage to single platforms.

Arbor solves this by running real, hardened PTY instances inside draggable 2D canvas nodes, driving visual connection cables directly from database dispatch states, isolating every agent inside dedicated Git Worktrees, and enabling direct agent-to-agent coordination over local Named Pipes via the arbor CLI.

---

🏗️ Architecture

┌────────────────────────────────────────────────────────────────────────┐
│                       Frontend (React 19 + TypeScript)                 │
│   2D Infinite Canvas  │  Home Launcher & Composer  │  WebGL xterm.js   │
│   Zustand Stores      │  i18n (EN / PT-BR)         │  Local Artifacts  │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Tauri 2 IPC (Type-Safe DTOs)
┌───────────────────────────────────▼────────────────────────────────────┐
│                       Core Engine (Rust Backend)                       │
│  ┌───────────────────┐  ┌───────────────────┐  ┌────────────────────┐  │
│  │ Hardened PTY Engine│  │ Worktree Manager  │  │ Roles & Lifecycle  │  │
│  │ (Memory Gate,     │  │ (Safe Locks,      │  │ (Atomic Persistence│  │
│  │  Output Throttle) │  │  Sparse Checkout) │  │  Mutation Ledger)  │  │
│  └───────────────────┘  └───────────────────┘  └────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │ Embedded SQLite (WAL Mode, Foreign Keys, Busy Timeout)           │  │
│  └──────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Named Pipes (`\\.\pipe\arbor-*`) / UDS
┌───────────────────────────────────▼────────────────────────────────────┐
│                       Local CLI (`arbor` tool)                         │
│   `arbor recruit`  │  `arbor ask`  │  `arbor connect`  │  `arbor list` │
│   `arbor check`    │  `arbor role` │  `arbor doctor`   │  `arbor ping` │
└────────────────────────────────────────────────────────────────────────┘

---

✨ Key Features & Technical Highlights

1. Real Terminals, Zero Simulation (Terminal Realness)

• Every canvas node embeds a genuine @xterm/xterm terminal accelerated with WebGL.
• Backed by a real native OS PTY (portable-pty) spawning a persistent interactive root shell (pwsh.exe/powershell.exe -NoExit on Windows; sh/bash/zsh -i on POSIX).
• The agent CLI is launched as a startup command inside the shell; when the CLI exits, the shell remains open and responsive to keyboard input.
• Hardened Resource Gates: 400MB free RAM gate before process spawning, 250ms throttled output streaming with UTF-8 byte split boundary preservation, and lock-free process tree termination.

2. Git Worktree Isolation

• Every teammate recruited by a Maestro receives a dedicated, isolated Git worktree branch (.arbor/worktrees/<id>).
• Prevents agents from colliding or locking working files.
• Includes sparse-checkout support and automated lock retry mechanisms.

3. Role System & Maestro Mode

• Any terminal node can be promoted to Team Maestro (kind: 'coordinator').
• Roles are stored on disk in .arbor/roles/<role-id>/ (workspace) and ~/.arbor/roles/ (global), containing role.json and dynamic AGENTS.md injected with <your_assigned_role> and <working_directory>.
• Atomic writes with mutation ledgers ensure no configuration corruption.
• Models and permissions are translated into native CLI flags at agent startup.

4. Agent Peer-to-Peer CLI (arbor)

• Agents discover and communicate with each other over local Named Pipes (\\.\pipe\arbor-<token> on Windows or Unix Domain Sockets on Linux/macOS).
• arbor recruit --name "Tester" --role "tester" --agent "claude": Creates worktree, sets up role, spawns PTY, and tracks dispatch.
• arbor ask <name> "<prompt>": Blocks synchronously until the target agent responds or times out.
• arbor connect <nodeA> <nodeB>: Links two agents in the SQLite dispatch context table.
• arbor check <name>: Non-blocking inspection of agent status and latest unread messages.
• arbor list & arbor doctor: Discovers running teammates and verifies local system readiness.

5. Fast-Start Launcher (HomeView)

• Interactive quickstart launcher with Composer, recent workspaces list, detected agent CLIs, YOLO mode toggle, and animated ASCII canvas background.

6. Native Bilingual Support

• Native internationalization support for English (en) and Brazilian Portuguese (pt-BR).

---

🚀 Getting Started

Prerequisites

• Node.js: v18+ (v20+ recommended)
• Rust: Stable toolchain (rustup default stable)
• OS Dependencies:
  • Windows: Visual Studio C++ Build Tools
  • Linux: sudo apt install libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
  • macOS: Xcode Command Line Tools

Installation & Development

# 1. Clone the repository
git clone https://github.com/bps2414/arbor.git
cd arbor

# 2. Install frontend dependencies
npm install

# 3. Typecheck TypeScript
npm run typecheck

# 4. Run Rust unit & integration tests
cargo test --all-targets --manifest-path src-tauri/Cargo.toml

# 5. Launch Arbor desktop in development mode
npm run tauri dev

---

📁 Repository Structure

.
├── .arbor-planning/              # Specifications, wave contracts, and realness reports
│   ├── WAVE1_CONTRACT.md         # Wave 1 foundation deliverables
│   ├── WAVE2_CONTRACT.md         # Wave 2 roles & Maestro mode specifications
│   └── WAVE2_REALNESS_REPORT.md  # Terminal realness verification & test suite audit
├── ABOUT.md                      # Detailed technical overview & architectural blueprint
├── ARBOR_PLANO_CONSOLIDADO.md    # Master architectural blueprint and design tokens
├── docs/                         # UI specifications (Alethe & Maestri specs) and screenshots
├── src/                          # React 19 Frontend
│   ├── components/
│   │   ├── canvas/               # 2D Canvas surface, nodes, cables, and tools
│   │   ├── home/                 # Home launcher, composer, recent workspaces
│   │   ├── shell/                # App shell, toolbar, sidebar, zoom controls
│   │   └── terminal/             # WebGL xterm.js node & overlays
│   ├── lib/                      # IPC adapters, i18n dictionaries, and skins
│   └── stores/                   # Zustand stores (canvasStore, appStore)
└── src-tauri/                    # Rust Desktop Backend (Tauri 2)
    ├── src/
    │   ├── bin/arbor.rs          # Local `arbor` CLI binary
    │   ├── cli/                  # Named Pipe / UDS server and command dispatchers
    │   ├── db/                   # Embedded SQLite, schema migrations, and atomic ledger
    │   ├── ipc/                  # Tauri IPC command handlers and DTOs
    │   ├── lifecycle/            # Agent lifecycle hook HTTP server
    │   ├── pty/                  # Hardened PTY engine (portable-pty, throttle, tree kill)
    │   ├── roles/                # Role storage, resolution, and CLI flag drivers
    │   └── worktree/             # Git worktree isolation engine
    └── Cargo.toml                # Rust dependencies and configuration

---

🗺️ Roadmap & Current Status

[x] Wave 1: PTY Engine + SQLite + Worktrees (Desktop Foundation) — DONE
    ├── SQLite orchestration schema with WAL, FKs, and busy timeout
    ├── PTY hardening (Memory gate >400MB, 250ms batching, lock-free process tree kill)
    ├── Worktree engine with sparse-checkout and index lock retry
    ├── Atomic file persistence with tempfile + OS rename and mutation ledger
    ├── Base `arbor` CLI dispatcher and specs
    └── Bilingual i18n support (PT-BR and EN)

[x] Wave 2: Roles + Maestro Mode + Terminal Realness — DONE
    ├── Role system (.arbor/roles/ with role.json and AGENTS.md per worktree)
    ├── Maestro Mode node promotion (`kind: 'coordinator'`)
    ├── Local Named Pipes server (`arbor recruit`, `arbor connect`, `arbor ask`, `arbor check`)
    ├── HTTP agent lifecycle hook server for event and heartbeat correlation
    ├── HomeView launcher with Composer, recent projects, and ASCII backdrop
    └── Terminal Realness Gate: 93 automated tests passing, 0 synthetic UI mocks

[ ] Wave 3: Dynamic Canvas + Cables + Telemetry (Next)
    ├── Live spring and catenary rope physics for cables driven by `dispatch_contexts`
    ├── Historical memory and token cost telemetry overlays per node
    └── Interactive Markdown sticky notes and task DAG overlay layer

[ ] Wave 4: IDE Mode + Diff Viewer + MCP Hub
    ├── Split-pane tabbed IDE layout (Horizontal/Vertical panes)
    ├── 2MB safety-gated CSS diff viewer
    ├── Centralized MCP configuration manager with safe atomic backups
    └── Multi-forge git integration (GitHub, GitLab)

[ ] Wave 5: Expansions & Distribution
    ├── Embedded CDP browser view & Computer Use automation
    ├── Recurring task scheduler
    └── Production installers (Windows NSIS `.exe`, macOS `.dmg`, Linux `.AppImage`)

---

📜 License

This project is licensed under the MIT License.