1
MrJ
7 min de leitura ·

Pitch: Openheinerss: O Maestro Universal de AI Coding Agents Harness - Orquestrador de cli's e sdk's oficiais - AGY, claude-code, codex, aider, opencode

Openheinerss Logo Openheinerss Logo

"Esse projeto foi criado rapidamente depois de alguns estudos, e ele visa ser a base de um dos meus outros projetos, mas ele era importante demais para ser só um componente misto, então resolvi isolar. Espero que gostem!"
— mrjcrom / crom-org

🎯 Por que o Openheinerss nasceu?

Hoje em dia o ecossistema de desenvolvimento assistido por inteligência artificial é incrível, mas completamente fragmentado:

  • Você quer usar o Claude Code para refatorações profundas de arquitetura.
  • Quer rodar Aider ou OpenCode para edições cirúrgicas linha a linha.
  • Quer aproveitar modelos locais via Ollama para programar offline ou sem custos de token de API.
  • Quer conectar ferramentas MCP (Model Context Protocol) para que seus agentes consultem bancos de dados, APIs ou documentações.
  • E além de tudo isso, precisa de segurança caso a IA gere código que quebre sua base.

O Openheinerss foi concebido exatamente para resolver essa dor: ele atua como um maestro orquestrador de harnesses, unificando CLI, SDKs e extensões sob uma camada de controle única, transparente e segura.

🧩 O que é um "Harness" e por que precisamos de um Maestro?

[!NOTE]
Definição de Harness: Na engenharia mecânica e automotiva, um harness (chicote ou arnês) é o conjunto de cabos e conectores que padroniza a transmissão de sinal e energia entre peças de fabricantes distintos. No mundo do software e de agentes de IA, um Harness é a camada adaptadora de isolamento e controle que "veste" um agente autônomo, padronizando sua comunicação, ciclo de vida e permissões.

O Problema do Mundo Real

Cada ferramenta de IA opera de uma forma completamente diferente:

  • O Claude Code opera via terminal interativo próprio com prompts especializados.
  • O Aider gerencia commits Git automáticos com formato de chat próprio.
  • O OpenCode consome flags de terminal e parâmetros específicos de contexto.
  • O Codex / Scripts operam via chamadas diretas de API.

Se você tentar integrar todas essas ferramentas ao seu fluxo de trabalho, você acaba refém de dezenas de CLIs conflitantes, formatos de log incompatíveis, configurações de chaves espalhadas e nenhum controle central de segurança.

O Papel do "Maestro de Harness"

O Openheinerss é o maestro que rege essa orquestra. Ele encapsula essas ferramentas heterogêneas através de uma interface padronizada (Harness Interface):

type Harness interface {
    Name() string
    Execute(ctx context.Context, task Task) (TaskResult, error)
    Validate() error
    SupportedEngines() []string
}

Para o desenvolvedor ou para a sua aplicação, a forma de falar é uma só. O Maestro cuida de:

  1. Padronizar Entrada e Saída: Traduz sua solicitação para a sintaxe nativa do harness escolhido.
  2. Gerenciar Ciclo de Vida: Inicia processos em sandbox, monitora tempo de execução e streams de saída.
  3. Injetar Ferramentas MCP: Compartilha as ferramentas do projeto com qualquer motor.
  4. Garantir Segurança: Cria checkpoints antes da execução e permite rollback instantâneo caso o harness cometa erros.

📊 Fluxograma de Arquitetura

O diagrama abaixo ilustra como o Openheinerss orquestra a comunicação desde a interface do usuário até os motores de execução:

flowchart TD
    subgraph Clients["Entradas & Interfaces"]
        CLI["CLI Nativa (Go)"]
        VSCode["Extensão VS Code"]
        SDK_TS["SDK TypeScript / Node"]
        SDK_PY["SDK Python"]
        SDK_PHP["SDK PHP"]
    end

    subgraph Maestro["Openheinerss Core (O Maestro)"]
        Router["Roteador de Tarefas & Perfis"]
        ProfileMgr["Gerenciador Multi-Contas / Tokens"]
        CheckpointEngine["Motor de Checkpoints & Rollback"]
        MCPHub["Hub MCP Centralizado (Context & Tools)"]
    end

    subgraph HarnessLayer["Camada de Harnesses (Adaptadores)"]
        H_Claude["Harness Claude Code"]
        H_Aider["Harness Aider"]
        H_OpenCode["Harness OpenCode"]
        H_Codex["Harness Codex"]
        H_AGY["Harness Antigravity (AGY)"]
        H_Mock["Harness Mock (Testes / Offline)"]
    end

    subgraph Execution["Destinos de Execução"]
        CloudAnthropic["Claude 3.7 / Anthropic"]
        CloudOpenAI["GPT-4o / OpenAI"]
        LocalOllama["Ollama (DeepSeek / Qwen / Llama)"]
        LocalFileSystem["Árvore de Arquivos do Projeto"]
    end

    %% Conexões dos Clientes para o Maestro
    CLI --> Router
    VSCode --> Router
    SDK_TS --> Router
    SDK_PY --> Router
    SDK_PHP --> Router

    %% Fluxo interno do Maestro
    Router --> CheckpointEngine
    CheckpointEngine --> ProfileMgr
    ProfileMgr --> MCPHub

    %% Maestro despachando para a Camada de Harnesses
    MCPHub --> H_Claude
    MCPHub --> H_Aider
    MCPHub --> H_OpenCode
    MCPHub --> H_Codex
    MCPHub --> H_AGY
    MCPHub --> H_Mock

    %% Harnesses executando nas IAs e no disco
    H_Claude --> CloudAnthropic
    H_Aider --> LocalFileSystem
    H_OpenCode --> LocalOllama
    H_Codex --> CloudOpenAI
    H_AGY --> LocalFileSystem

    CheckpointEngine -.->|"Snapshot / Rollback Seguro"| LocalFileSystem

🚀 Principais Recursos do Sistema

1. Suporte Nativo a 6 Harnesses

Troque de motor em tempo de execução sem alterar nenhum arquivo de configuração:

  • claude-code: Raciocínio avançado e refatorações complexas.
  • opencode: Autonomia em linha de comando.
  • codex: Execuções rápidas de scripts e scaffolds.
  • aider: Pair programming guiado por histórico Git.
  • agy (Antigravity): Agente autônomo multi-tarefas.
  • mock: Execução instantânea para testes de integração sem gastar cotas.

2. Multi-Contas e Múltiplos Perfis (Multi-Account)

O Openheinerss permite configurar perfis isolados de autenticação (personal, work, enterprise). Se o limite de uso de uma chave for atingido, o Maestro pode alternar automaticamente para a próxima conta configurada.

3. Hub Central de Ferramentas MCP (Model Context Protocol)

Em vez de configurar servidores MCP separadamente para cada agente ou IDE, você configura no Openheinerss uma única vez. Todos os motores conectados herdam acesso aos mesmos recursos (PostgreSQL, Git, Puppeteer, APIs internas).

4. Checkpoints & Rollback Atômico

Cada tarefa executada cria um ponto de restauração instantâneo da sua árvore de código. Se a IA cometer um deslize ou refatorar algo além do esperado, reverta o estado do projeto com um único clique ou comando:

openheinerss rollback --to chk_latest

5. Execução 100% Offline com Ollama

Total privacidade: rode modelos como deepseek-coder-v2, qwen2.5-coder ou llama3 localmente sem que uma única linha de código saia da sua máquina.

📦 Como Instalar

O Openheinerss possui binários nativos compilados para Linux, macOS (Apple Silicon e Intel) e Windows, além de pacotes oficiais em todos os grandes gerenciadores.

Binário CLI (Go Nativo)

Baixe o executável pronto para o seu sistema direto das Releases no GitHub:

# Ou via Go:
go install github.com/crom-org/openheinerss/cmd/openheinerss@latest

SDKs em Todas as Linguagens

🐍 Python (PyPI)

pip install openheinerss

👉 Ver no PyPI

🟨 Node.js / TypeScript (npm)

npm install @openheinerss/sdk

👉 Ver no npm

🐘 PHP (Packagist)

composer require crom-org/openheinerss-sdk

👉 Ver no Packagist

💻 Exemplos Práticos de Uso

1. Via Linha de Comando (CLI)

# Disparar uma tarefa usando Claude Code
openheinerss task "Crie um endpoint REST para autenticação JWT" --engine claude-code

# Usar um perfil corporativo com rollback ativado
openheinerss task "Refatore a camada de banco de dados" --engine aider --profile work --checkpoint

# Rodar 100% offline via Ollama
openheinerss task "Documente todas as funções públicas" --engine opencode --model ollama/deepseek-coder

2. Em TypeScript / JavaScript

import { OpenheinerssClient } from '@openheinerss/sdk';

const client = new OpenheinerssClient({
  baseUrl: 'http://localhost:8080'
});

async function main() {
  const result = await client.runTask({
    engine: 'claude-code',
    prompt: 'Otimize a query SQL da função getActiveUsers()',
    autoCheckpoint: true
  });

  console.log('Status da execução:', result.status);
  console.log('Arquivos alterados:', result.modifiedFiles);
}

main();

3. Em Python

from openheinerss import OpenheinerssClient

client = OpenheinerssClient(base_url="http://localhost:8080")

task = client.run_task(
    engine="aider",
    prompt="Escreva testes unitários para a classe PaymentService",
    profile="personal"
)

print(f"Tarefa finalizada: {task.id}")
print(task.summary)

4. Em PHP

<?php
require 'vendor/autoload.php';

use Openheinerss\Client;

$client = new Client('http://localhost:8080');

$response = $client->runTask([
    'engine' => 'opencode',
    'prompt' => 'Migre os controllers para o padrão invokable do PHP 8.2',
    'checkpoint' => true
]);

print_r($response);

🔌 Extensão Oficial para VS Code (openheinerss-vscode) - BETA E PARA FINS DE ESTUDOS, NÃO SE APEGUE

Para quem prefere a produtividade visual, também desenvolvemos a extensão nativa para o Visual Studio Code!

Repositório: crom-org/openheinerss-vscode

O que ela oferece:

  • Painel Lateral Dedicado: selecione com um clique o motor desejado (Claude Code, Aider, OpenCode, etc.).
  • Gerenciador de Perfis & Tokens: troque entre contas e provedores diretamente da barra de status.
  • Visualizador de Diffs e Checkpoints: veja exatamente o que o agente modificou e faça rollback visual em caso de erros.
  • Hub MCP Integrado: ative ou pause servidores MCP sob demanda.

ℹ️ Nota de publicação: A extensão já está totalmente codificada, compilada e disponível no repositório GitHub. Ela ainda não foi publicada na Marketplace pública da Microsoft, mas já pode ser clonada, testada localmente em modo desenvolvedor (F5) ou empacotada via vsce package para gerar o .vsix.

🌐 Links e Ecossistema

Desenvolvido com carinho por crom-org. Feedbacks, PRs e sugestões são muito bem-vindos! ⭐

Chega de perder tempo procurando o que assistir

Sabe quando você abre a internet e passa minutos navegando sem saber o que dar play? A Crom TV resolveu isso. É uma TV online grátis, em português, com 76 canais ao vivo 24h — tecnologia, IA, notícias, podcasts, filmes, entretenimento e muito mais. 1.6 milhões de vídeos linkados.

Crom TV — TV online grátis: canais ao vivo 24h e vídeos

Ligue, troque de canal e assista agora: tv.crom.run

Carregando publicação patrocinada...