Documentação Orquestra

Sobre o Orquestra

Orquestra é uma IDE que substitui o modelo tradicional de abas e janelas empilhadas por um canvas infinito com zoom e pan. Você posiciona editores, terminais, navegadores e agentes de IA livremente pelo espaço — igual Figma ou Miro, mas feito para programação.

Os painéis podem flutuar livres no canvas, ser dockados em abas e splits (quatro zonas de dock), ou destacados para janelas próprias do sistema operacional. Todo o layout é persistido automaticamente e restaurado quando você reabre o projeto.

Construído com Electron + React + TypeScript. Versão atual: 1.3.2 (MIT).

Instalação

Baixe a versão pré-compilada para seu sistema. Não compile da fonte para uso diário.

Primeiros Passos

1. Abra uma pasta — ela se torna seu workspace.
2. Adicione painéis — clique com botão direito no canvas ou use Cmd+K para a paleta de comandos.
3. Organize — arraste painéis para dockar em abas e splits, ou destaque para janelas próprias.
4. Navegue — Cmd+= para zoom in, Shift+setas para pan.
5. Já está pronto — sem arquivos de configuração pra começar.

Canvas

O canvas é um espaço infinito onde você posiciona seus painéis. Dois sistemas de coordenadas:

• Canvas-space — coordenadas do mundo real onde os painéis vivem
• View-space — o que você vê na tela, derivado do zoom + viewport

Navegação

Configurações do Canvas

Velocidade do zoom, snap to grid, minimap, estilo do grid (dots/lines/none), auto-focus no maior nó visível, imagem de wallpaper. Acessível em Configurações.

Painéis

Cada tipo de painel tem uma cor de marca e tamanho padrão:

Docking

Quatro zonas de dock por janela (esquerda, direita, inferior, central), cada uma com suporte a abas e splits. O layout de dock é gerenciado por janela via DockStore.

Para destacar um painel: arraste-o para fora da janela principal. Para dockar de volta: arraste a janela destacada sobre a zona de dock desejada.

Editor

Baseado no Monaco Editor (o mesmo do VS Code). Recursos:

• Syntax highlighting para dezenas de linguagens
• Multi-cursor e seleção em bloco
• Diff mode (comparação de arquivos)
• Preview de Markdown embutido
• Detecção de conflitos de arquivo (EditorConflictBanner)
• Múltiplas abas por editor

Terminal

Terminal nativo usando xterm.js com WebGL renderer e node-pty como backend. Recursos:

• Renderização acelerada (WebGL + canvas fallback)
• Busca no scrollback
• Serialização de sessão (scrollback preservado entre sessões)
• Web links clicáveis
• Modo Maestro (agente controla o terminal via CLI orquestra)
• Pipe entre terminais (pipeCreate, pipeDestroy)

Git

Integração completa com git via runtime VcsHost. Status, staging, branches, diffs, push/pull, stashes — tudo sem sair do canvas.

Worktrees são recursos de destaque: cada worktree pode ter seus próprios terminais e agentes, com isolamento total. Visualização por território no canvas.

Navegador

Navegador Chromium embutido via <webview> com suporte a:

• Múltiplas abas com sidebar vertical (estilo Arc/Edge)
• Barra de favoritos
• Histórico global compartilhado entre workspaces
• Proxy por painel: HTTP, HTTPS, SOCKS5, PAC
• Proxy com autenticação (user:pass@host)
• Homepage, buscador e novo comportamento configuráveis
• Sessão global compartilhada vs sessão isolada por proxy

Pi Agent

O Pi é o agente de IA integrado do Orquestra. Uma thread de chat com o modelo que você escolher, com memória por sessão.

O agente é executado como um processo filho (piRpcClient.ts) e se comunica via JSON-RPC. O estado inclui: mensagens, modelo ativo, flag de execução, estatísticas da sessão e suporte a fork de conversas.

Fluxo típico: o agente recebe um prompt, processa com o modelo configurado, pode modificar arquivos (com diffs exibidos no ChatDiffView), executar comandos no terminal, e reportar resultados.

Provedores Suportados

Via OAuth (abre navegador para autenticação) ou API key (configurada nas configurações do agente):

As credenciais são armazenadas criptografadas via safeStorage do Electron.

Subagentes

O sistema de subagentes delega tarefas especializadas com contextos isolados:

Modos de execução: único, paralelo (até 8, 4 concorrentes) ou encadeado. Workflow típico: scout-and-plan → implement → implement-and-review.

Modo Maestro

Um modo especial de terminal (maestro: true) que expõe comandos orquestra CLI, permitindo que o agente manipule o canvas:

Atalhos de Teclado

No Windows/Linux use Ctrl no lugar de Cmd. Todos os atalhos são rebindáveis em Configurações → Shortcuts.

Painéis e Arquivos

Navegação e View

Canvas

Desenvolvimento Remoto

O runtime do Orquestra pode rodar localmente ou em máquinas remotas via SSH ou WSL.

Tipos de Conexão

• Local — runtime roda na mesma máquina
• SSH — runtime em servidor remoto com chave Ed25519 e known_hosts
• WSL — runtime dentro de uma distro WSL2

Ciclo de Vida do Runtime

installing → connecting → connected → disconnected → unreachable → missing

O daemon é um processo Node.js autônomo (empacotado como tarball por plataforma) que expõe operações de terminal, sistema de arquivos, git e shell via JSON-RPC sobre stdio.

Chaves SSH são gerenciadas com criptografia via safeStorage do Electron, com suporte a ssh-agent forwarding.

Arquitetura

Orquestra segue o modelo de processos do Electron:

src/
├── main/    // Processo principal Electron
│   ├── ipc/       // Handlers IPC por domínio
│   ├── runtime/   // Daemon remoto (SSH, WSL)
│   └── lifecycle/ // Shutdown, openPath, telemetry
├── preload/  // Ponte IPC isolada (contextBridge)
├── renderer/ // App React + Zustand + Tailwind
│   ├── canvas/    // Canvas infinito
│   ├── docking/   // Sistema de abas e splits
│   ├── panels/    // Componentes de painel
│   ├── stores/    // ~20 stores Zustand
│   └── sidebar/   // Explorador, git, busca
├── agent/    // Sistema de agente Pi
│   ├── main/      // RPC client, auth manager
│   └── renderer/  // Painel do agente, chat, diff
└── shared/   // Tipos, IPC channels, temas
    └── themes/    // 17 temas embutidos

Gerenciamento de Estado

Zustand 5 com stores por domínio. Cada workspace tem sua própria instância de CanvasStoreContext e DockStoreContext.

• canvasStore — nós, zoom, viewport, foco, undo/redo, conexões, desenhos
• appStore — workspaces, painéis, sidebar, worktrees, remoto
• dockStore — layout das zonas de dock por janela
• settingsStore — preferências do usuário
• shortcutStore — atalhos rebindáveis

Persistência

Todo estado é salvo como JSON em disco. Arquivos hand-editable em formato JSON — sem banco de dados.

Temas

17 temas embutidos com schema unificado que cobre: cores da interface (CSS custom properties), paleta ANSI do terminal e tokens de syntax highlighting do Monaco.

Temas built-in: Dark Cold (padrão), Dark Warm, Light Subtle, Dracula, Nord, Solarized Dark, Tokyo Night, VS Dark/Light, One Dark Pro (4 variantes), One Light, Clay Dark/Light, IntelliJ Light.

O tema pode ser customizado via skill orquestra-theme — um JSON data-driven que define toda a aparência do app.

FAQ

Perguntas frequentes sobre o Orquestra.