Documentation

Dunu is an AI-first desktop IDE: a native workbench, a Monaco editor, a built-in coding agent, and Open VSX extensions. It ships as Dunu.app.

The app itself is proprietary — you download binaries via Homebrew or GitHub releases. You extend it by building and publishing Open VSX–compatible extensions (themes, languages, and more) and by adding agent plugins under .dunu/.

Dunu ships through one Homebrew tap — dunudev/homebrew-dunu. Tap it once, then install any of the three packages it publishes. They all ride the same vX.Y.Z release, so a single brew upgrade moves them together.

brew tap dunudev/dunu

What the tap installs

brew install --cask dunudev/dunu/dunu-ide
#   -> Dunu.app

brew install dunudev/dunu/dunu-ide-cli
#   -> dunu

brew install dunudev/dunu/dunu-server
#   -> dunu-server

After the tap is added you can drop the dunudev/dunu prefix — brew install --cask dunu-ide and brew install dunu-server resolve the same way.

The app — dunu-ide

Installs Dunu.app into /Applications. The cask does not put dunu on your PATH — install dunu-ide-cli alongside it for the terminal command.

The launcher — dunu-ide-cli

A VS Code–style code shim: it locates Dunu.app and forwards your arguments. The formula is named dunu-ide-cli so it never shadows Homebrew core's OCaml dune — the installed binary is still dunu. If you use both, decide which wins on PATH (for example brew unlink dune).

It looks for the app at $DUNU_IDE_BIN first, then inside a sibling Dunu.app, then /Applications/Dunu.app. Point it at a build elsewhere with:

export DUNU_IDE_BIN="/Applications/Dunu.app/Contents/MacOS/Dunu"
dunu .

The server — dunu-server

Serves a folder's files, git, .dunu/ config, and an interactive terminal over HTTP + WebSocket, so the desktop app can attach to a workspace on another machine. The interactive /pty endpoint requires the hyper HTTP backend:

brew install dunudev/dunu/dunu-server
TISH_HTTP_BACKEND=hyper dunu-server --workspace "$PWD" --port 8787 --token secret
curl localhost:8787/health   # {"ok":true}

Upgrade and uninstall

brew update && brew upgrade dunu-ide-cli dunu-server
brew upgrade --cask dunu-ide

brew uninstall dunu-ide-cli dunu-server
brew uninstall --cask dunu-ide   # add --zap to remove app support files
brew untap dunudev/dunu

Or skip Homebrew entirely: drag Dunu.app from a release DMG into /Applications. Releases are published on dunudev/dunu.

1. 1

   Open a folder. Welcome screen, or File ▸ Open Folder. Dunu treats that folder as the workspace.

2. 2

   Command palette. Cmd+Shift+P (macOS) / Ctrl+Shift+P. Almost every action is listed there — search “theme”, “terminal”, “git”, “extensions”, “remote”.

3. 3

   Sign in to Hypery. Open the account / agent side of the workbench and complete sign-in. Without a Hypery account the editor, git, and extensions still work; the agent does not.

4. 4

   Install a language extension. Open Extensions, search Open VSX (for example a Python or TypeScript pack), and install. Grammar-only and declarative extensions (themes, languages, settings, commands) work immediately.

5. 5

   Talk to the agent. Open chat, pick Agent or Ask, and describe a change. Use @ to attach files or web search. Plan mode writes a checklist you can review before it edits.

6. 6

   Optional CLI. From a terminal, dunu . opens the current folder.

The workbench is a set of internal modules — Explorer, Terminal, Git, Agent, Extensions, Remote, and more. You can disable non-core ones like a feature flag; core modules always stay on. Here's the short tour.

VS Code color themes work as-is. Dunu adds extra chrome tokens — window frame, floating cards, traffic lights — so a theme can style the whole app, not only the editor. Bundled Dunu themes seed into your user extensions on first launch: four Desert times of day (Daybreak, Sunset, Dusk, Midnight) and four Dessert flavors (Macaron, Blackberry, Boysenberry, Blackcurrant).

To write or publish your own theme — including optional dunu.* chrome keys — see Theme authoring.

"statusBar.background": "#E0A968",
"statusBar.foreground": "#1A0F05",
"editor.foreground": "#EADCBF"

Dunu renders standard VS Code color themes and extends them. Real VS Code ignores unknown keys, so one theme file can serve both editors. Ship themes as normal extensions via Open VSX.

Three tiers of effort

1. Ship unchanged. Your existing VS Code theme works full-app — Dunu derives UI colors from standard colors keys.
2. Tune for Dunu. Add dunu.* keys for floating cards, pill tabs, and macOS traffic lights.
3. Full chrome identity. Frame elbows, segmented rails, canvas wallpaper, and chrome typography restyle the whole workbench shell.

Minimal extension

A theme is a VS Code extension with a contributes.themes entry. Set an explicit id if you expect the label to change later — otherwise the label becomes the settings id and renaming orphans user prefs.

{
  "name": "my-theme",
  "publisher": "me",
  "version": "1.0.0",
  "engines": { "vscode": "^1.70.0" },
  "categories": ["Themes"],
  "contributes": {
    "themes": [
      {
        "id": "me.my-theme",
        "label": "My Theme",
        "uiTheme": "vs-dark",
        "path": "./themes/my-theme.json"
      }
    ]
  }
}

{
  "name": "My Theme",
  "colors": {
    "editor.background": "#1C110C",
    "editor.foreground": "#EADCBF",
    "statusBar.background": "#E0A968",
    "statusBar.foreground": "#1A0F05",
    "dunu.app-canvas": "#140C08",
    "dunu.part-radius": "12px",
    "dunu.part-gap": "8px",
    "dunu.part-pad": "8px",
    "dunu.tab-radius": "8px",
    "dunu.tab-inset": "8px",
    "dunu.titleBar.controlsPadX": "12",
    "dunu.titleBar.controlsPadY": "10",
    "dunu.titleBar.controlsColorClose": "#c4453f",
    "dunu.titleBar.controlsColorMinimize": "#e0b23f",
    "dunu.titleBar.controlsColorZoom": "#5f9e54"
  },
  "tokenColors": []
}

Install and test

Copy the extension folder to ~/.dunu/extensions<publisher>.<name>/ and reload Dunu. Or publish to Open VSX and install from the Extensions view. After switching themes, the first paint of the next reload may briefly show the previous colors — a boot cache for flash-free startup; it self-corrects in the same load.

If the theme does not appear, check ~/.dunu/last-theme-scan.json for the scan's view of your extension.

What Dunu reads

The dunu.* namespace

Every dunu.* key lives in the ordinary colors map. There are two contracts:

• CSS-value keys (almost all of them). Dotted and hyphenated spellings are equivalent (dunu.surface.editor ≡ dunu.surface-editor). Values can be colors, lengths, shorthands, calc(), gradients, or SVG data-URIs.
• Native macOS window-control keys — exactly eight under dunu.titleBar., read by exact dotted spelling. Hyphenated forms do nothing. Unset = fully native buttons. Harmless on other platforms.

Typos die silently — an unknown dunu.* key becomes a CSS variable nothing reads. Prefer the key list below, or copy keys from a bundled Desert / Dessert theme after install.

Recipes

Each recipe is additive and safe to ship to VS Code too.

Floating-card layout

"dunu.app-canvas": "#1C110C",
"dunu.part-radius": "12px",
"dunu.part-border-width": "1px",
"dunu.part-gap": "8px",
"dunu.part-pad": "8px",
"dunu.split-size": "8px"

Pill tabs

"dunu.tab-radius": "8px",
"dunu.tab-inset": "8px",
"dunu.tab-gap": "3px",
"dunu.tab-divider-width": "0px",
"dunu.tab-row-h": "46px"

Tinted traffic lights (macOS)

"dunu.titleBar.controlsPadX": "12",
"dunu.titleBar.controlsPadY": "10",
"dunu.titleBar.controlsColorClose": "#c4453f",
"dunu.titleBar.controlsColorMinimize": "#e0b23f",
"dunu.titleBar.controlsColorZoom": "#5f9e54",
"dunu.titleBar.controlsDiameter": "13"

Collections

Group themes into named sections of the picker with dunuThemeCollections. Entries must match theme labels exactly. Ignored by VS Code.

"contributes": {
  "themes": [ /* … */ ],
  "dunuThemeCollections": [
    {
      "id": "me.warm",
      "label": "Warm",
      "order": 1,
      "blurb": "Desert hues",
      "themes": ["My Theme", "My Theme Dusk"]
    }
  ]
}

Packaging traps

• Set an explicit theme id if labels may change.
• Bump extension version on every release — seeded / bundled installs re-copy only when the version changes.
• Publish to Open VSX as a normal VS Code theme extension.

Troubleshooting

• dunu.* key does nothing — typo, wrong spelling on a native titleBar key, or an illegal value on a non-dunu. standard key.
• Not in the picker — check ~/.dunu/last-theme-scan.json: bad JSON, missing contributes.themes, or folder not under ~/.dunu/extensions.
• First paint shows old colors — expected; the boot cache self-heals in the same load.
• Editor right, terminal wrong — set terminal.* keys; the 16 ANSI slots are yours to define.

Highest-value dunu.* keys for most themes. Dotted and hyphenated forms are equivalent except for the eight macOS dunu.titleBar.* controls, which require exact dotted spelling.

Dunu has three extension layers, and they compose — a VS Code theme, an MCP server, and a project skill can all be active in the same workspace.

Built-in features

The workbench itself is a set of internal modules (Explorer, Terminal, Git, Agent, Extensions, Remote, and others). You can disable non-core ones like a feature flag — they stay installed, they just do not activate. Core modules always stay on.

VS Code extensions

Install from Open VSX in the Extensions view, or drop a VSIX into ~/.dunu/extensions. Dunu also scans ~/.vscode/extensions and ~/.cursor/extensions, so packs you already have are picked up.

What works today:

• Declarative package.json contributions: languages, TextMate grammars, themes, commands, keybindings, settings.
• Extensions with a main entry run in a Node or Bun extension host. Set dunu.ide.extensionHost.runtime to auto (default), node, or bun. Native .node addons need Node.

The vscode API surface is still growing toward VS Code 1.96-line parity. Grammars, themes, and many commands are solid; arbitrary marketplace extensions that depend on the full Electron host are not a guarantee yet. Building and publishing your own extensions for Open VSX is supported.

Agent plugins

These live next to your code under .dunu/ (project) and ~/.dunu/ (user). Project wins on name conflict.

The agent is also an MCP client: configure stdio servers in .dunu/mcp.json (or user MCP settings) and their tools show up in chat.

Dunu reads VS Code JSON where it already exists, and prefers .dunu/ when both are present.

User settings live in Dunu's user directory (same idea as VS Code's User settings.json).

The desktop launcher and the headless binaries share one agent loop. Put dunu on your PATH and open any folder from the terminal.

dunu .                                   # open the current folder
dunu -g src/main.rs:42:5                   # jump to line 42, column 5
dunu --wait CHANGELOG.md                  # block until closed (good for $EDITOR)

TISH_HTTP_BACKEND=hyper dunu-server \
  --workspace ./workspace --port 8787       # headless workspace

dunu and dunu-server are the two binaries the Homebrew tap ships — see Homebrew packages. dunu-headless, dunu-cloud-agent, and dunu-cloud-run are not distributed through the tap; they ship inside Dunu.app and on cloud workers.