medit documentation

medit embeds an AI coding agent into your running React app. Select or describe what you want, and medit edits the code, commits to a branch, and opens a PR — from any device on your network.

Install

One command installs the medit binary and puts it on your PATH:

$ curl -fsSL https://dl.medit.software/install.sh | bash

medit itself is a self-contained binary — no Node.js needed to run it. You do need:

git — medit works on branches and commits.
Node.js + npm — only to run your own app's dev server (e.g. npm run dev).

The installer also sets up opencode (medit's default AI engine). Re-run the command any time to upgrade; medit also offers to update itself when a new version ships.

macOS (Apple Silicon & Intel) and Windows are supported today. On macOS the installer clears the download quarantine for you.

Quick start

# 1. go to your React app — or scaffold a fresh one
$ cd path/to/your-app        # or: medit --create-new-canvas

# 2. add an API key to .env (see below)
$ echo "MEDIT_OPENAI_API_KEY=sk-..." >> .env

# 3. run medit + your dev app
$ medit --dev

Open your app in the browser — the medit overlay appears bottom-right. Click it, pick an element or describe a change, and hit Send.

Add an API key

Create a .env in your app's root (medit reads it at runtime). Any one provider key works:

MEDIT_OPENAI_API_KEY=sk-...
# or  MEDIT_ANTHROPIC_API_KEY=sk-ant-...
# or  MEDIT_OPENROUTER_API_KEY=sk-or-...

Prefer a coding CLI? Set MEDIT_AGENT to claude, cursor, or codex and authenticate that tool. For automatic PRs, also add a GitHub token:

GITHUB_TOKEN=ghp_...

Without it, medit still commits to local branches.

Run modes

$ medit                  # medit + dev app + prod (when package.json has dev/start)
$ medit --dev            # medit + dev app only
$ medit --prod           # prod app only (no overlay)
$ medit --medit-only     # medit API only — if you run dev yourself
$ medit --host 0.0.0.0   # expose on your LAN / Tailscale
$ medit -p 5176          # prefer a different port (default 5175)

medit manages your app via the dev / start scripts in package.json.

Add the overlay to your app

Vite / Create React App / plain HTML

Add the loader before </body> (e.g. in public/index.html):

<script src="http://localhost:5175/agent-loader.js" defer></script>

Next.js

Use next/script so medit is never bundled into your app:

import Script from "next/script";

{process.env.NODE_ENV === 'development' && (
  <Script src={`${process.env.NEXT_PUBLIC_MEDIT_AGENT_URL}/agent-loader.js`}
          strategy="afterInteractive" />
)}

.env.local: NEXT_PUBLIC_MEDIT_AGENT_URL=http://localhost:5175

Use it from your phone (LAN / Tailscale)

medit serves over the network, so you can drive it from any device. Start it bound to all interfaces:

$ medit --host 0.0.0.0

Then open your app at your machine's LAN or Tailscale address. Point the loader at the same host (or rely on localhost→page-host rewriting).

HTTPS over the network: browsers block ws:// from secure pages, so use a TLS cert whose names/IPs match the address you load from — otherwise the overlay and hot-reload sockets fail. Set MEDIT_TLS_CERT / MEDIT_TLS_KEY, and include your Tailscale IP/hostname in the cert.

Pro license

medit is free for personal use. Pro unlocks PR automation, multiple projects, production preview, and team access. Add your key to your app's .env:

MEDIT_LICENSE_KEY=MEDIT-...

The overlay shows your tier; hover the badge for license details. Keys validate offline, with a grace period near expiry. Get one at medit.software/pricing.

Environment variables

Variable	Description
`MEDIT_OPENAI_API_KEY` `MEDIT_ANTHROPIC_API_KEY` `MEDIT_OPENROUTER_API_KEY`	API key (one required unless using a CLI agent).
`MEDIT_AGENT`	`opencode` (default), `claude`, `cursor`, or `codex`.
`GITHUB_TOKEN`	Enables push + automatic PR creation.
`MEDIT_LICENSE_KEY`	Pro license key.
`MEDIT_PASSWORD`	Access code for the overlay (optional).
`MEDIT_SERVER_PORT`	medit's own port (default 5175). Same as `-p`.
`MEDIT_DEV_PORT` / `MEDIT_PROD_PORT`	Dev / prod app ports (defaults 3000 / 3001).
`MEDIT_TLS_CERT` / `MEDIT_TLS_KEY`	Serve medit over HTTPS directly.
`MEDIT_NO_UPDATE`	`1` to disable the self-update prompt.

CLI reference

medit [options]

  -p, --port <n>      Preferred port (default 5175)
      --host <host>   Bind host (use 0.0.0.0 for LAN/Tailscale)
      --dev          medit + dev app only
      --prod         prod app only (no overlay)
      --medit-only   medit API only
      --create-new-canvas [name]   Scaffold a medit-ready Next.js app
  -v, --version      Print the version
  -h, --help         Show help

Updating

When you run medit and a newer version exists, it asks if you'd like to upgrade (default yes), then replaces itself and restarts. To upgrade manually, just re-run the install command. Disable the prompt with MEDIT_NO_UPDATE=1.

Troubleshooting

Overlay doesn't appear

Confirm medit is reachable: open http://<host>:<port>/agent-loader.js in the browser. Over the network, start with --host 0.0.0.0 and make sure the loader points at an address your device can reach.

Hot reload / overlay fails over HTTPS

Your TLS cert must cover the exact host/IP you load the app from (a localhost-only cert breaks wss:// from a Tailscale IP). Re-issue the cert with that IP/hostname included.

"API key required"

.env must live in your app's repo root (the project medit edits), not where medit is installed.

Wrong port / "port in use"

medit picks the next free port and prints it. Two instances bound to different interfaces can both report the same number — check the "ready" banner for the actual port.