Modus

The open-source, local-first desktop workspace for AI coding agents.

Plan a feature, let an agent build it, watch every command and diff, browse pages, run real terminals, and keep the whole loop on your machine.

English | 简体中文

Modus is a desktop app that makes agentic coding visible and local. You open a real
project folder, plan the work, and let an agent execute against your current checkout —
while chat, tool calls, Git changes, terminals, the browser, and permissions all live in
one window. Bring your own model stack (any PI-compatible provider, plus MCP servers and
local skills). Your code and history stay on your machine.

Run from source today — packaged, signed installers for macOS / Windows / Linux are
on the roadmap. The terminal sidecar is already cross-platform (portable-pty); the
remaining work is the build/sign/release matrix.

Quick Start

# Requirements: Node >= 22.19.0, npm, Rust + Cargo, Git
git clone https://github.com/brandlll-lee/modus.git
cd modus
npm install
npm run dev

Then:

1. Open a workspace folder (your real project + Git branch).
2. Connect a model provider in Settings (any PI-compatible provider, or a custom one).
3. Plan, then build — toggle Plan Mode to get a reviewable plan.md, approve it, and
   let the agent execute. Or just start chatting.
4. Inspect everything — review diffs, run terminals, open pages, and approve risky
   actions, all in the right inspector.

Features

What It Feels Like

• The left sidebar is your project shelf: pinned and recent projects (each with a
  "..." actions menu), sessions, and live activity.
• The center is the agent timeline: messages, streamed output, tool cards, diffs,
  terminal actions, todos, checkpoints, and the Review Plan / Questions cards above the
  composer.
• The composer switches model and thinking level, sets the approval mode, toggles
  Plan vs Build, and takes images, / skills, and @ context.
• The right inspector holds Changes, Files, Browser, Terminal, and Security, so you can
  inspect diffs, pages, logs, and runtime state without leaving the conversation.
• The settings window manages providers, custom models, model parameters, MCP servers,
  skills, and security configuration.

Architecture

Renderer (React 19)        Sidebar · chat timeline · composer · inspector
        │                  (Changes / Files / Browser / Terminal / Security) · settings
        ▼
Preload bridge             A narrow, typed doorway: window.modus.*  (no Node in the renderer)
        │
        ▼
Electron main (Node)       Trusted services: workspace · git · browser (CDP) · terminal ·
        │                  files · docs · models · MCP · skills · permissions · agent runtime
        ├──────────────►   Rust PTY sidecar (modus-pty-host)   real terminals via portable-pty
        └──────────────►   SQLite (node:sqlite)                workspaces, sessions, events,
                                                               permissions, docs, checkpoints

Design principles: authoritative signals over heuristics, capability-driven rendering over
name-based dispatch, and a renderer that can only reach the system through validated IPC.
See desktop security notes.

Tech Stack

Project Layout

modus/
├─ apps/
│  └─ desktop/            # Electron app (main · preload · renderer)
├─ crates/
│  └─ pty-host/           # Rust PTY sidecar used by the terminal
├─ docs/                  # Architecture and media
└─ packages/              # Reserved for shared packages

Development

npm run dev          # run the desktop app
npm run check        # biome + typecheck across the workspace
npm run format       # biome --write
npm run test         # vitest (unit + integration)

# desktop-only
npm --workspace @modus/desktop run typecheck
npm --workspace @modus/desktop run build      # builds the app + Rust sidecar
cargo check -p modus-pty-host

Tests use real execution (real git repos, real PTY) rather than mocks, and assert behavior
contracts instead of pinning sample data.

Roadmap

Near-term

• Cross-platform release matrix: build the Rust sidecar per target, bundle it into each
  installer, and sign / notarize (macOS, Windows).
• Sharper timeline rendering and stronger approval UX.
• Hunk-level staging and richer review flows.

Later

• Fusion mode: plan → isolated worktrees → parallel agents → judge → integrator.
• Rules, memories, and automations.

Contributing

There is no formal contribution guide yet. For now:

• Open an issue with a clear reproduction or proposal.
• Keep changes small, scoped, and easy to review (Conventional Commits).
• Run npm run check and npm run test before sending a PR.
• Favor systematic, root-cause solutions over patches: authoritative signals over guessing,
  data/config over name-lists and magic numbers, and no dead or faked UI.

License

Licensed under the Apache License 2.0.