Marx

The single visual + agentic coding IDE.

Marx is a VS Code-compatible IDE (built on Eclipse Theia) with an agent engine (embedded opencode) at its core. It routes every task to the right model tier by complexity, and it treats token conservation as a first-class feature, not an afterthought.

Why Marx

Most AI coding tools are either a plain editor with a chat bolted on, or a terminal agent with no editor at all. Marx is both in one window:

• A full VS Code-compatible editor (Monaco, LSP, terminals, extensions from Open VSX) so it drops into any existing workflow.
• An agent engine (opencode, MIT, embedded via SDK) with main agent + background subagents, plan/act modes, permission gating, and checkpoints.
• A complexity-aware LLM router that picks the cheapest model tier that can still finish the job, with fallback chains per tier and escalation on failure.
• Token conservation by design: symbol-based navigation, tool-output compaction, MCP tool budgets, progressive-disclosure skills, prompt caching, and per-call token metrics.

Install

git clone https://github.com/cpntodd/marx.git
cd marx
yarn install
yarn start:electron

Manual setup (Debian/Ubuntu):

# Node 20 LTS or newer, yarn classic
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install -g yarn@1.22.22

Manual setup (CachyOS / Arch Linux):

# Node, build toolchain, yarn classic
sudo pacman -S --needed nodejs npm base-devel python
sudo npm install -g yarn@1.22.22
# Electron runtime libraries
sudo pacman -S --needed gtk3 nss libsecret alsa-lib

Flatpak (sandboxed, all Linux distros):

# Once published on Flathub:
flatpak install flathub io.github.cpntodd.Marx
flatpak run io.github.cpntodd.Marx

# Or build locally (requires flatpak + flatpak-builder):
yarn package:electron:dir
./scripts/build-flatpak.sh

Marx ships as a self-contained Electron desktop app (its runtime is bundled), so any Linux distribution can run it. Debian/Ubuntu and CachyOS/Arch are the two primary supported targets; AppImage, AUR, and Flatpak packaging are provided in Phase 6. See docs/INSTALL.md.

Features

• VS Code extension compatibility via Open VSX (16k+ extensions)
• Embedded opencode agent engine (main agent + subagents)
• Complexity router with model tiers and fallback chains
• Plan/Act modes, permission approvals, checkpoints (shadow git)
• Diff review with per-hunk accept/reject
• MCP browser catalog (50 servers, one-click install)
• Agent Skills pack (progressive disclosure, SKILL.md)
• Editor LSP by default; agent-side LSP as an opt-in toggle (token warning)
• Token metrics + session cost dashboard

Repo layout

apps/           Theia applications (browser-app, electron-app)
extensions/     Theia extensions (marx-agent: agent panel, router wiring)
packages/       Shared libraries
  agent-core    opencode SDK wrapper (engine, sessions, permissions)
  router        Complexity classifier, tiers, fallback chains
  mcp           MCP catalog + per-project server manager
  skills        Agent Skills pack (SKILL.md)
  indexer       Symbol-based navigation (tokensave-style)
  config        Shared config types + JSON schema
cli/            Headless marx CLI (same engine as the IDE)
docs/           Phase plan + handoff, ADR, router/token/MCP specs

Docs

• docs/PHASES.md -- phase plan, handoff checklist for agents/humans, and the running interaction log. Read this first when contributing.
• docs/ADR-001-architecture.md -- architecture decision record (all 17 locked decisions)
• docs/ROUTER.md -- complexity router spec (classifier, tiers, fallbacks)
• docs/TOKEN-CONSERVATION.md -- token conservation spec (10 mechanisms)
• docs/MCP-CATALOG.md -- the 50-server MCP catalog and enablement model

License

MIT. See LICENSE.

Marx builds on MIT/EPL-2.0 components (Theia, Monaco, opencode, LiteLLM, Dockview, tokensave) and treats them as upstream dependencies.