Skip to content

linux.md

Latest commit

 

History

History
220 lines (161 loc) · 7.99 KB

linux.md

File metadata and controls

220 lines (161 loc) · 7.99 KB
Raw

MonoCode Linux — Guia Linux

Interface desktop para seus agentes de código, exclusiva para Linux, distribuída como AppImage.

Este documento concentra tudo que é específico de Linux. Para uso geral, veja o README.

Instalação

Baixe o AppImage na página Releases:

chmod +x MonoCode_*.AppImage
./MonoCode_*.AppImage

Funciona em qualquer distro x86_64, sem instalar nada.

Pré-requisitos para build

  • Node.js 20+
  • Rust estável atual (rustup default stable)
  • Dependências Tauri/WebKit no Debian/Ubuntu:
npm run setup:linux

O script scripts/install-linux-deps.sh instala:

  • build-essential, curl, file, wget, patchelf, zenity
  • libgtk-3-dev, libwebkit2gtk-4.1-dev, libayatana-appindicator3-dev
  • libssl-dev, librsvg2-dev, libxdo-dev

Outras distros: instale os equivalentes (webkit2gtk 4.1, gtk3, libsoup3, javascriptcoregtk) pelo seu gerenciador de pacotes.

Build a partir do código

npm ci
npm run build:linux

Saída em target/release/bundle/appimage/: o .AppImage executável.

Para desenvolvimento com hot-reload:

npm install
npm run tauri dev

O Tauri carrega automaticamente src-tauri/tauri.linux.conf.json no Linux (janela sem decoração nativa, bundle appimage).

Provedor (CLI)

Instale e autentique o OpenCode antes de abrir o app:

Provedor Instalação Login
OpenCode https://opencode.ai opencode auth login

É obrigatório, não opcional. O MonoCode procura o binário na inicialização e diz como instalá-lo se faltar.

Primeira abertura

Na primeira abertura, o MonoCode mostra um assistente de quatro passos com a versão instalada, CLIs de agentes detectadas, estado do GitHub CLI e provedores disponíveis. O assistente pode ser pulado a qualquer momento antes da conclusão. Depois disso, ele não aparece novamente. Transferências de janela também não exibem o assistente.

  • Use Pular para sair sem alterar provedores.
  • Use Tentar novamente no passo do GitHub depois de executar gh auth login.
  • O GitHub é opcional; o restante do MonoCode continua disponível sem ele.

OpenCode: MCP, config e auth

O MonoCode não gerencia MCP nem escreve opencode.json. O opencode serve que o app sobe lê a config normal do OpenCode: opencode.json[c] do projeto para cima mais ~/.config/opencode/. MCPs (opencode mcp list), skills (opencode debug skill) e providers (opencode providers list) continuam sendo configurados no próprio OpenCode.

O que o MonoCode faz por sessão: PATCH /session com regras de permissão conforme o modo de acesso (supervised, auto-accept-edits, auto, full-access). question é sempre permitido, allow vira once (a sessão pergunta de novo na próxima vez). Cheque opencode debug config se algo parecer ignorado.

Auth é por provider dentro do OpenCode, então não há botão de login no app para ele. Se o turno falhar com modelo não encontrado, rode opencode models <provider> e escolha um provider/model do catálogo. Overrides via env (OPENCODE_CONFIG, OPENCODE_CONFIG_CONTENT, OPENCODE_AUTH_CONTENT) são repassados do login shell para o serve, igual às chaves de fx e grok.

Sobre o projeto

  • Exclusivo para Linux: CI, release, docs e empacotamento só para AppImage.
  • Mantenedor: yanhenrique-dev.

Fluidez e composição (WebKit)

O interruptor "aceleração de hardware" nas Configurações só desliga os desfoques (backdrop-blur) e o renderizador GPU do terminal. Composição GPU de verdade no WebKitGTK depende do sistema, não do app. Se a rolagem ou as Configurações parecerem pesadas, experimente antes de mexer no código:

# Desliga a composição acelerada (útil para comparar: se melhorar, o
# gargalo está no caminho GPU do WebKit, não no JavaScript)
WEBKIT_DISABLE_COMPOSITING_MODE=1 ./MonoCode_*.AppImage

# Força o renderizador DMA-BUF (Wayland + Mesa recentes)
WEBKIT_DMABUF_RENDERER=1 ./MonoCode_*.AppImage

Para medir com dados, abra o app com o inspetor remoto e grave um trace:

WEBKIT_INSPECTOR_HTTP_SERVER=127.0.0.1:9222 ./MonoCode_*.AppImage

Se alguma flag ajudar de forma consistente, vale registrar aqui o hardware e o driver onde foi testada.

Tela preta ao abrir (EGL_BAD_PARAMETER)

Afeta AppImages construídos no Ubuntu 22.04 rodando em distros rolantes (CachyOS/Arch + Mesa recente + AMD + Wayland): o empacotador embute o libwayland-client antigo do Ubuntu, o Mesa do host falha em eglGetDisplay() e o processo web aborta — a janela abre preta. É o caso de tauri-apps/tauri#15665.

Desde a 0.1.61 o workflow de release remove essas bibliotecas e reempacota o AppImage (scripts/repack-appimage.sh), então o loader usa o libwayland do host. Se ainda assim abrir preto numa versão antiga:

# Confirma o diagnóstico (esperado: EGL_BAD_PARAMETER)
./MonoCode_*.AppImage 2>&1 | grep -i EGL

# Contorno imediato: extrair e rodar contra as libs do sistema
./MonoCode_*.AppImage --appimage-extract
./squashfs-root/AppRun

Sons (runtime)

O app toca cues in-app via Web Audio para atividade da inbox (inboxUnseen, linkedActivity) e para a interface (switch, copy). Não há banners de sistema: nenhum daemon de notificações é necessário.

Pré-requisitos no host:

  • Sons embutidos são sintetizados via Web Audio (sem codec). Arquivos customizados .ogg/.wav decodificam em mais sistemas; .mp3/.m4a/.opus dependem dos plugins GStreamer do WebKitGTK do host. Falha de decodificação aparece nas Configurações com o motivo (missing/decode/unavailable).
  • O Web Audio começa suspenso até o primeiro clique/tecla. Se o primeiro evento sonoro chegar antes de qualquer gesto, o cue pode sair mudo uma vez; depois do primeiro gesto, normaliza.
  • Nenhum som no AppImage: o AppImage usa o WebKitGTK e o GStreamer do host, então sem saída de áudio funcional no sistema não há cue. Nas Configurações, a linha de status do som mostra Áudio pronto, Aguardando primeiro clique ou tecla ou Áudio indisponível. Cheque no host:
# Servidor de áudio de pé? (esperado: PipeWire ou PulseAudio)
pactl info 2>/dev/null | head -n 3 || pipewire --version

# Sinks de áudio do GStreamer presentes?
if ! command -v gst-inspect-1.0 >/dev/null 2>&1; then
  echo "gst-inspect-1.0 não está instalado; não foi possível verificar os sinks"
else
  gst-inspect-1.0 pulsesink alsasink 2>&1 | grep -i "no such element" \
    || echo "sinks OK"
fi

# Web Audio do WebKitGTK funciona? Abra qualquer página de teste Web Audio
# no navegador do sistema; se ela também ficar muda, o problema é o stack
# de áudio do host, não o app.

Links não abrem no navegador

O empacotador incluía o xdg-open do Ubuntu 22.04, que não conhece os desktops Linux atuais: dependendo da sessão (ex. Plasma 6 via KDE_SESSION_VERSION=6), ele não executa nada e sai com sucesso — o clique no link morria em silêncio. Desde a versão com o fix, o scripts/repack-appimage.sh também remove esse xdg-open embutido e o app usa o do sistema, que entende o desktop em execução. Se um link mesmo assim não abrir, teste no terminal:

/usr/bin/xdg-open "https://example.com"

e confira o navegador padrão com xdg-settings get default-web-browser.

Interface borrada ou apagada

Ordem de checagem:

  1. Escala da interface diferente de 100% (Ctrl+=, Ctrl+-, Ctrl+0): zoom fracionário borra botões e ícones. Em Configurações → Aparência a linha da escala mostra botão de reset quando não está em 100%.
  2. Escala fracionária do Wayland (125%/150%): o WebKitGTK renderiza em resolução não inteira e tudo amacia. Se o passo 1 não resolveu e o sistema usa fração, teste 100% ou 200% para confirmar a origem.

Verificação

npm run check:web   # vitest + tsc
npm run check:rust  # cargo fmt, clippy, test
npm run check       # ambos (igual ao CI)