convez.ai
AgenteDesenvolvimento WebAvançado
Liruns

MaruDesk

Liruns/marudesk

IA vê seu app rodando, não só o código

Ver no GitHub
BomPluginScore · de 0 a 100

Agent agentico em desktop que integra navegador real, DevTools, editor e terminal em um único processo. O agente vê a aplicação rodando em tempo real — não apenas o código-fonte — permitindo debugar e corrigir erros através de evidência de runtime.

Instalação

$npx convez-ai Liruns/marudesk

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 4 meses
Versão
v0.9.0
Issues abertas
0
Contribuidores
2

Casos de uso

  • Debugar aplicações web em tempo real com agentes IA
  • Corrigir erros mapeando stack frames direto para o código-fonte
  • Automação de testes e interação com elementos da página via agente

Veredito

Ferramenta inovadora que fecha a lacuna entre AI coding assistants tradicionais e realidade de runtime. Promissora em desenvolvimento ativo, mas ainda em estágio 0.2.0 — use como daily driver só se aceitar o risco de bugs.

README

A tradução para o português deste README ainda está na fila.

MaruDesk is a desktop application (Electron) for building and debugging web software. Unlike source-only AI coding tools, it embeds a real Chromium browser and speaks the Chrome DevTools Protocol (CDP) in-process, so the agent can read the live DOM, console, and network of the app you are running and act on that runtime evidence — for example, turning a console error into a source fix and confirming the fix by reloading the page.

Status: in active development — built as a daily driver and portfolio project. See Project status.

Download

Grab the installer for your platform from the latest release →.

PlatformInstallerNotes
Windowsmarudesk-Setup-0.2.0.exeInstalls and auto-updates in place.
macOS · Apple Siliconmarudesk-0.2.0-arm64.dmgUnsigned — on first launch, right-click → Open to pass Gatekeeper.
macOS · Intelmarudesk-0.2.0.dmgUnsigned — on first launch, right-click → Open.
Linux.AppImage · .debchmod +x the AppImage and run it, or sudo dpkg -i the .deb.

Prefer to build from source? See Getting started.

The idea

Most AI coding assistants only see your source files. MaruDesk co-locates the surfaces a developer actually moves between — browser, DevTools, editor, terminal, and the agent — inside one process, and connects the seams between them:

  • A console error in the embedded DevTools carries a one-click Fix this: the agent maps the stack frame back to your source file, edits it, reloads the page, and verifies the error is gone (get_console_errors → edit → reload_and_verify).
  • The agent can click, type, and scroll the live page, read network requests, and evaluate expressions — the same things you would do by hand in DevTools.
  • Because the agent shares the workspace, terminals, and open tabs through an in-process context server, it works from what is actually on screen instead of guessing.

Screenshots

Features

Agentic AI chat

  • Many providers, one app. Anthropic, OpenAI, Google (Gemini), xAI (Grok), Ollama (local), and any custom OpenAI-compatible endpoint (OpenRouter, LM Studio, vLLM, and similar).
  • Bring your own subscription. Connect by API key, or sign in with an OAuth subscription. Claude (Pro/Max) and xAI work today; ChatGPT and Gemini subscription backends are experimental.
  • Provider fallback chain. When the active model is rate-limited or errors (429 / 5xx), the agent automatically retries on the next connected model you have ranked, instead of failing the turn.
  • Streaming, reasoning, and control. Live token streaming, collapsible reasoning blocks, a per-provider reasoning-effort dial, and approval modes (plan / read-only / ask / auto).
  • Composer that keeps up. Slash commands (/init, /review, /diff, /context, /compact, /copy, …), @-mention workspace files, paste or drop images for vision models, recall past prompts with the arrow keys, and queue a message while a turn is still running.
  • Plan mode. Have the agent research read-only and propose a step-by-step plan before you let it edit.
  • Compaction and verify. /compact summarizes a long conversation to reclaim context; an optional post-edit verify command (e.g. npm run typecheck) runs after the agent edits and folds the PASS/FAIL back into the chat.
  • Approvals that remember. Approve a gated tool once, or "Allow always" to stop re-prompting for it for the rest of the conversation.
  • Sessions and memory. Resume past conversations from a history rail; keep durable cross-session notes.

Runtime-aware tools (the differentiator)

  • Read console errors with source mapping back to workspace files.
  • Query the DOM, read network requests and response bodies, evaluate JavaScript.
  • Drive the live page: click, fill, press keys, scroll.
  • A reload-and-verify loop that checks whether a change actually removed the error.
  • One-click Fix this on console errors.

A real browser, not a preview

Tabbed browsing on a split-pane grid, with favicons, history, downloads, find-in-page, zoom, configurable search engines, crash recovery, and per-site partitioning.

Custom DevTools (CDP)

A React-built DevTools dock with Console, Network, Elements, Application, and Rendering panels plus a REPL — dockable or popped out into its own window. Chromium's own DevTools remain available as an escape hatch.

Editor, terminal, explorer

A Monaco code editor, a real shell terminal (node-pty) with find and copy/paste, a file explorer, and workspace-scoped file tools the agent can use — guarded by configurable never-edit globs. Workspace content search (Ctrl/Cmd+Shift+F, ripgrep with a Node fallback) adds case/word/regex toggles, include/exclude glob filters, highlighted match previews, and click-to-jump to the exact line and column.

Context MCP and external MCP

A built-in, in-process MCP server exposes tabs, the active page, terminals, editor buffers (including unsaved edits), the explorer tree, sessions, and memory to the agent. External MCP servers can also be connected — local over stdio or remote over HTTP (Streamable HTTP, with an SSE fallback) — configured Claude-Desktop-style in mcp-servers.json. Each external tool is routed through the same approval / read-only mediation as the built-in ones; a server can be marked trust to auto-approve its tools, hide specific tools via disabledTools, and a dropped connection is detected and surfaced. Manage them in Settings → MCP Servers.

Plugins

Extend the agent with your own JavaScript. A plugin is a folder with a manifest.json and an index.js exporting activate(ctx); it can contribute agent tools and slash commands. Plugins run in an isolated worker (Electron utilityProcess with the Node Permission Model + a module sandbox), never in the main process, and reach the filesystem/network only through a capability-gated bridge the user approves per plugin (fs:read, fs:write, net). Contributed tools flow through the same approval / read-only mediation as the built-in ones, and a plugin's file writes show up in the chat diff/revert history. Manage them in Settings → Plugins; see marudesk/docs/plugin-runtime-design.md. Plugin folders are scanned from <userData>/plugins/ (user) and <workspace>/.marudesk/plugins/ (project); a runnable example lives in marudesk/examples/plugins/hello-world.

Remote / mobile bridge

Drive your PC's agent from your phone. QR-code pairing, application-level end-to-end encryption (X25519 + AES-GCM), direct LAN / Tailscale transport, and an optional cloud relay for access from anywhere. The phone is a thin client; the model, tools, and workspace always stay on the PC.

Repository layout

MaruDesk is a three-package workspace.

PathRole
marudesk/Electron desktop app — browser stage, DevTools, agent loop, editor/terminal, workspace integration, packaging. Owns the model/tool/workspace loop.
mobile/Capacitor thin client — phone UI that sends commands and renders PC-owned agent state. Runs no model or tools locally.
relay/Node/TypeScript relay and auth service — brokers same-account host/client WebSocket traffic for the cloud-relay path.

Inside marudesk/:

  • electron/ — main process: browser/* (tabs, navigation, downloads, CDP runtime capture), agent/* (session loop, tools, MCP, context sources, provider auth), plus settings, secrets, and the remote server.
  • src/ — React renderer, organized into feature slices (features/browser, devtools, editor, agent, settings, terminal, and others).
  • shared/ — transport-safe typed contracts used across main, renderer, and tests.
  • e2e/ — Playwright end-to-end tests. docs/ — design and architecture notes. DESIGN.md — design-system rules.

Tech stack

  • Electron 42 (Chromium 148), React 19, TypeScript (strict project builds)
  • Vite 8 build, Zustand state, Tailwind design tokens
  • Monaco editor, xterm.js + node-pty terminal
  • Vercel AI SDK (@ai-sdk/*) for model integration, Model Context Protocol SDK for tools
  • Playwright for Electron/runtime end-to-end tests

Getting started

Prerequisites: Node.js 20 or newer and npm. There is no root package; install per package.

# Desktop app
cd marudesk
npm install
npm run dev        # starts the Vite renderer + Electron shell

Optional companion packages:

cd mobile && npm install && npm run dev    # phone client (web/PWA in dev)
cd relay  && npm install && npm start      # cloud relay (defaults to port 8788)

Configure a provider

Open Settings → AI Providers and either paste an API key or sign in with a subscription (OAuth). Then choose a model from the command-palette model picker. To enable automatic failover, turn on Settings → Agent → Model fallback and rank your models.

Build a desktop package

cd marudesk
npm run build            # type-check + bundle
npm run package:win      # or: npm run package:mac / npm run package:linux

Cut a release (CI)

Releases are built and published by the Release GitHub Actions workflow (.github/workflows/release.yml). Pushing a v* tag builds marudesk on native runners — macOS arm64 and x64 cross-built on Apple Silicon (macos-14), Windows x64 (windows-latest), and Linux x64 (ubuntu-latest) — and uploads the installers (dmg for macOS, NSIS exe for Windows, AppImage + deb for Linux) to the GitHub release that matches marudesk/package.json version:

# bump marudesk/package.json version first, commit, then:
git tag v0.2.0
git push origin v0.2.0

A manual workflow_dispatch run builds the same matrix without publishing, so you can smoke-test packaging. To build/publish from your own machine instead, use npm run publish:win / publish:mac / publish:linux (GH_TOKEN required), or npm run package:* for a local-only build.

Auto-update (Windows)

The Windows build auto-updates in place via electron-updater: on launch it checks the GitHub Releases feed, downloads a newer NSIS package in the background, and offers a "restart & install" action in Settings → About (it also installs on the next quit). For this to work, each release must carry the update metadata (latest.yml + the installer and its .blockmap), which the CI workflow (and npm run publish:win) produce automatically.

The feed is configured by build.publish in marudesk/package.json (Liruns/marudesk). macOS and Linux keep the manual check (it opens the releases page): the Mac dmg is currently unsigned (download-and-run, requires Apple code signing + notarization before auto-update can be enabled), and the Linux AppImage/deb are download-and-run for now.

Development and verification

Run the checks for the package you changed:

cd marudesk
npm run typecheck
npm run lint
npm run e2e              # Playwright end-to-end suite

Targeted main-process and server harnesses:

npm run harness:server        # remote server (loopback)
npm run harness:e2e           # server end-to-end
npm run harness:pair          # secure device pairing
npm run harness:relay-bridge  # cloud relay bridge
npm run harness:mcp           # MCP tools
npm run harness:plugins       # isolated plugin runtime (worker sandbox + tool RPC)

UI work follows marudesk/DESIGN.md: dark-first, restrained, token-based colors only (no hard-coded colors), Lucide icons, and calm, precise copy.

Project status

MaruDesk is a personal, in-development project used as a daily driver and portfolio piece. Expect rough edges.

  • Subscription OAuth for ChatGPT and Gemini uses undocumented backends and is experimental; API-key access and Claude / xAI OAuth are the stable paths.
  • MaruDesk is not affiliated with any model provider. Using subscription logins in a third-party client may be subject to each provider's terms — use at your own discretion.
  • Released under the MIT License.

Documentation

  • AGENTS.md — workspace agent guide and command rules
  • marudesk/README.md — desktop package details
  • marudesk/DESIGN.md — design system
  • marudesk/docs/ — product roadmap and architecture / design notes
  • mobile/README.md, relay/README.md — companion packages

License

MIT © 2026 Liruns

Ver o original no GitHub

Bom para

Relacionados