User Guide

Overview

Meowtrix is a browser-based remote workspace. The UI is a tiling pane layout: each pane holds tabs, and each tab is either a terminal (a real PTY-backed shell, rendered with xterm.js) or an embedded browser. A single small Node server hosts the frontend and multiplexes the terminal sessions over a WebSocket.

You run it on a host machine (your laptop, a home server, a VPS) and reach it from any browser on the network — or from anywhere via a tunnel. Because the shells live on the server, you can close the tab, switch from laptop to phone, or ride out a dropped connection without losing your running processes.

Installation

Prerequisites

Meowtrix runs on the host machine (macOS or Linux) — the devices you connect from only need a browser.

• Zero-Dependency Install (Recommended): No dependencies required. The installer automatically downloads the pre-packaged Node.js runtime and compiled native modules for your platform.
• Source-Based Install:
  • Node.js 18+ and npm — runs the server
  • git — clones the repo
  • A C/C++ build toolchain — to compile node-pty natively:
    • macOS: Xcode Command Line Tools (xcode-select --install)
    • Linux: build-essential (or gcc/make) and python3

Build your command

Pick what you want to do and the exact command updates below — copy it and paste it into a terminal on the host machine.

curl -fsSL https://raw.githubusercontent.com/tianhaoz95/hejitech-apps/main/projects/meowtrix/install.sh | bash

Running it

Start the server (defaults to port 9123, override with the PORT env var):

meowtrix            # if installed via the installer
# or, from source:
npm start
PORT=8080 npm start

Then open http://localhost:9123 in your browser. You'll land in a single pane with one terminal, ready to type.

By default Meowtrix binds to 127.0.0.1 (localhost only), so it is not reachable from other machines on your network — see Reaching it remotely to change that safely.

Reaching it remotely

Meowtrix hands whoever can reach it a real shell on the host, so it binds to 127.0.0.1 (localhost only) by default. There are two safe ways to use it from another device.

1. SSH tunnel (recommended)

Leave the default localhost binding and forward the port over SSH from your client machine:

ssh -L 9123:localhost:9123 <user>@<host>
# then open http://localhost:9123 in your local browser

This keeps Meowtrix off the network entirely — only your authenticated SSH session can reach it. Tunnels like ngrok http 9123 work the same way, since they connect to localhost on the host.

2. Bind to the network

To reach Meowtrix directly from other devices on a trusted network, bind to all interfaces:

meowtrix --network          # or: meowtrix --host 0.0.0.0
# from source:
HOST=0.0.0.0 npm start

Then open http://<host-ip>:9123 from any device. Use --host <addr> (or the HOST env var) to bind a specific interface instead.

Panes & tabs

The workspace is a tree of panes. Each pane has a tab strip; open as many tabs as you like inside a pane.

• Split a pane with the toolbar's Split V (side by side) or Split H (top/bottom) buttons.
• Resize by dragging the divider between panes. Sizes are proportional, so they hold up when you resize the window or move between screens.
• Add a tab with the + on the tab strip, then pick Terminal or Browser.
• Reorder / move tabs by dragging them — within a pane or across panes (works with mouse and touch).
• Close a tab with its ✕, or close the whole pane with the toolbar's Close button.

Splitting again in the same direction adds an equal sibling rather than nesting deeper, so layouts stay flat and predictable.

Terminals

A terminal tab is a full PTY-backed shell — your real shell, with colors, TUIs, and job control. The key property is that the shell lives on the server, not in the browser tab:

• Refresh the page, and the terminal reattaches to the same running shell with its recent output replayed.
• Close the browser, walk away, come back on another device — the process kept running.
• A dropped connection auto-reconnects (about once a second) and resumes the live stream.

Double-click (or double-tap) anywhere in a terminal to send Tab — handy for autocomplete without reaching for the key.

Browser panes

A browser tab is an embedded mini-browser with an address bar, back/forward, reload, and an "open in a new window" (↗) button. Pages are fetched through a built-in server-side proxy that strips frame-blocking headers, so many sites that normally refuse to be embedded will render right in the pane. The proxy keeps its own cookie jar (domain-aware, saved to ~/.meowtrix/proxy-cookies.json), so most sign-ins stick — across subdomains and across server restarts — and pages' WebSockets are tunnelled too. "Clear embedded-browser cookies" in the command palette signs the proxy out of everything.

In the desktop app, browser tabs are real native webviews instead of proxied iframes: sites run on their own origins with your OS cookie store, so they behave like any browser. ⌘L focuses the address bar and ⌘[ / ⌘] go back and forward; links that open new windows open as new tabs. (Settings → Browser tabs switches back to the proxy.) The same layout opened from a regular browser or a phone shows those tabs through the proxy.

Some sites — Google, OAuth popups, heavily bot-protected pages — still won't work through the proxy. For those, use a Host Browser tab.

Host Browser tabs

A Host Browser tab (the + menu, or "New host browser tab" in the palette) shows a real Chromium running on the host, streamed into the pane. Because it's a real browser, nearly everything works: Google sign-in, OAuth popups (they open as new tabs), WebSockets, file uploads and downloads (saved to the host's ~/Downloads, with a click-to-save toast). The signed-in profile lives on the host in ~/.meowtrix/host-browser-profile, so you stay logged in when you switch devices, and localhost URLs reach the host's dev servers.

• Like terminals, the page keeps running when you refresh or switch devices — the tab re-attaches to it.
• Passkeys don't work here: they live on your own devices, which the host can't reach. When a site asks for one, the request is declined right away (as if you'd cancelled the prompt) and a toast reminds you to pick another method, such as Google's “Try another way”.
• Copy/paste goes through your own clipboard; on phones, tap a text field (or the ⌨ button) for the keyboard.
• It needs a Chromium-based browser on the host (Chrome, Chromium, Edge or Brave are auto-detected). If there's none, the tab offers to download Chrome for Testing.
• The picture is a compressed stream, so it's a little less crisp and responsive than a local tab — lower or raise Host browser stream quality in Settings.

You can set a default homepage for new browser tabs in Settings.

CoDesign review

CoDesign is a review loop between you and a coding agent over a living HTML design spec. Before the agent builds a UI, it writes a mockup to .codesign/spec.html in the project. You review and annotate it in a CoDesign tab, and the agent waits for your verdict.

1. Ask your agent (Claude Code, Codex, Gemini CLI, … running in a Meowtrix terminal) to design the screen as a self-contained HTML file at .codesign/spec.html and then run mtx review. An empty CoDesign tab (+ → CoDesign) has a ready-made prompt you can copy.
2. mtx review opens a CoDesign tab beside the agent's terminal and blocks until you decide.
3. In the tab, switch between Responsive / Desktop / Tablet / Mobile frames and zoom in or out (⌘/Ctrl + scroll). Inspect mode shows each element's size, typography, colors and spacing. In Comment mode, click any element to pin a comment to it.
4. Press Send feedback: the agent's mtx review returns your comments with each element's CSS selector and text. It edits the spec (the tab reloads live as a new revision), marks comments done with mtx resolve c1 c2, and runs mtx review again.
5. Press Approve & sign off when it's right; mtx review prints APPROVED.

• Commands: mtx spec [dir] opens the tab; mtx review [dir] [--timeout SECS] waits for a decision (default 540s, exit code 2 if none yet, so run it again); mtx feedback [dir] [--all] lists comments without waiting; mtx resolve <id>... [-m note] resolves them. Give agents a ~10 minute tool timeout for mtx review.
• Outside Meowtrix terminals: set MEOWTRIX_URL (e.g. http://127.0.0.1:9123) and call ~/.meowtrix/app/bin/mtx.
• State on disk: the revision counter, comments and the latest decision live in .codesign/review.json. Restarts lose nothing, and you can commit the folder.
• Sandboxed: the spec runs in an opaque-origin sandbox, so agent-written HTML and CDN scripts can't call Meowtrix's file or terminal APIs. One side effect: localStorage isn't available to the spec.

Agent tools (mtx & MCP)

Coding agents running in a Meowtrix terminal can show you things directly instead of handing you a link to click. Each command places its tab beside the agent's terminal, never on top of it, and leaves your keyboard focus where it was.

• mtx open <url> opens a page in a browser tab. A bare localhost:5173 works. Pages on a local dev server reuse that server's existing tab and reload it, so tabs don't pile up. The host fetches the page, so localhost URLs work even when you're on another device. Add --split for a fresh pane beside the terminal, --pane <id> for a specific pane, --new to always open a new tab, or --host to open it in a Host Browser tab.
• mtx browser list, mtx browser shot <tab> [file.png], mtx browser text <tab> and mtx browser goto <tab> <url> let an agent see and steer the Host Browser page you're looking at (the MCP server offers the same as host_browser_list / host_browser_screenshot / host_browser_read).
• mtx edit <file>[:line] opens a file in an editor tab at that line. It reuses an editor already rooted above the file, otherwise it opens one at the file's git repo.
• mtx layout prints the current workspace as JSON: the split tree, pane sizes, each pane's tabs, and which pane is yours (containsCaller).
• mtx notify [--title T] <message> shows a toast and puts a dot on the agent's tab until you look at it. Clicking the toast jumps to that terminal.

As an MCP server: mtx mcp serves the same actions as MCP tools (open_url, open_file, get_layout, notify) over stdio. Run mtx mcp --install once in a Meowtrix terminal to register it with Claude Code. Without Claude Code, it prints a config snippet for other agents. The CLI needs no setup; MCP makes agents more likely to use the tools unprompted.

How placement works: by default a new tab goes to a pane other than the agent's own. It prefers one already showing pages, then the largest, and avoids the pane you're focused on. If the agent's pane is the only one, it is split along its longer side. On phones nothing is split. Commands report an error if no Meowtrix session is active, so the agent can print the link instead.

Code editor & Git

Meowtrix comes with a built-in code editor based on Monaco (the same core that powers VS Code). You can open a folder directly via the tab picker (+ → Code Editor), the command palette, or by typing mtx code /path/to/dir in any terminal.

• File Tree Sidebar: Browse the directory structure of the host machine and click to open files. Unsaved changes are marked with a dot indicator.
• Markdown Preview: Opening a .md file reveals a Preview button in the editor. Toggle it to view a live, side-by-side formatted preview. A quick-copy button is available on code blocks inside the preview.
• HTML Preview: View your static HTML files directly as preview tabs.
• Source Control: If the opened folder is a git repository, a Source Control tab appears in the sidebar. You can review staged/unstaged changes, view side-by-side diffs, stage/unstage files, and perform commits, pushes, and pulls.
• AI-Powered Commit Messages: Click the AI generate button next to the commit message box to automatically write a descriptive commit message based on your staged diffs.

Broadcast input

Toggle the toolbar's 📡 Broadcast button to mirror your keystrokes to every visible terminal at once — like iTerm2 broadcast or tmux synchronize-panes. Great for running the same command across several hosts side by side. Toggle it off to return to typing into just the focused terminal.

Scheduled Enter presses (⏰)

When working with AI coding agents or long-running commands, you may hit usage quotas or time constraints. Scheduled Enter lets you type a command and schedule its execution for later.

Click the ⏰ button in the toolbar or open it via the command palette to set a delay (e.g. 5h 30m) or a specific clock time. The target terminal will display a blurred countdown overlay and swallow input until the timer fires, writing an Enter character (\r) to the PTY. Because the timer lives server-side next to the shell processes, it will fire even if you close your browser tab or disconnect.

Command palette

Press ⌘K (macOS) or Ctrl/⌘ + Shift + P anywhere to open a fuzzy launcher for every workspace action — no need to remember individual shortcuts or hunt through the toolbar. You can also click the ⌘ Commands button in the toolbar.

• Type to filter; the list narrows as you go (fuzzy, so "spv" finds "Split pane vertically").
• ↑/↓ to move, Enter to run, Esc to dismiss.

Commands include splitting panes, opening terminal or browser tabs, switching between tabs and panes, toggling broadcast input, switching themes, uploading a file, and opening settings.

Settings & themes

Open the ⚙ settings panel to adjust:

The ☀ / 🌙 toolbar button cycles themes quickly. Settings are saved on the host under ~/.meowtrix/settings.json.

Sessions & multiple devices

Only one client is the active session at a time. If you open Meowtrix in a second browser or on another device, the newest one takes over and the others show a "Session active elsewhere" overlay with a Move session here button.

This is coordinated by the server (not just within one browser), so it works across different browsers and devices. When you move the session, your layout follows — the workspace is rebuilt and reconnects to the still-running shells.

On mobile

Meowtrix is built to be usable from a phone:

• An on-screen key bar sits above the soft keyboard with the keys terminals need most (Esc, Tab, arrows, and modifiers).
• Ctrl / Alt / Cmd are "sticky" — tap one, then tap a key to combine them (e.g. Ctrl + C), since mobile keyboards don't emit reliable key events.
• Double-tap the terminal to trigger autocomplete (Tab).

On-device Chat Pet

Mochi is a tiny animal companion that wanders around your workspace. You can click on Mochi to open a chat dialog. Mochi replies instantly, keeping you company as you build.

• On-device AI: All conversation is processed completely locally in your browser. Replies are generated by Chrome's on-device Gemini Nano model (via the Prompt API). No network requests are made, keeping your chats completely private.
• Customizable Faces: Go to settings to choose from 12 different faces for your pet: Cat, Dog, Fox, Bunny, Panda, Penguin, Frog, Chick, Ghost, Robot, Dragon, or Unicorn.
• Wander Controls: You can adjust Mochi's speed (1 for lazy, up to 10 for zoomies) or enable "Stay" to keep Mochi pinned to a specific location (simply drag Mochi anywhere on the screen).

Keystroke combo FX

Celebrate your coding streaks! Keystroke Combo FX tracks your typing speed and streak length to drive dynamic, gamified visual effects in real time.

• Tiers: As you type, your combo builds up through tiers: HEATING UP, ON FIRE, BLAZING, INFERNO, and MELTDOWN.
• Visual Feedback: A heat-tinted combo readout counts up in the bottom-right corner. Keystrokes produce particle bursts, the screen edges glow, and reaching the highest tiers triggers a screen-shake effect.
• Toggleable: If you find the effects distracting, you can toggle them off in the Settings panel.

Self-updates

Meowtrix handles updates directly from the web interface. The server periodically checks its git clone upstream status in the background. If a newer version is available, a non-intrusive update banner will appear at the top of the workspace.

Clicking Update & Restart pulls the latest code (re-compiling native dependencies if needed) and restarts the server process. This is kept user-triggered because restarting the server terminates active PTY terminals, letting you choose the perfect moment to update.

Keyboard shortcuts

Use Cmd on macOS or Ctrl elsewhere:

Trying the demo

The live demo is the full Meowtrix UI running with no server. Because there's no host machine, terminals are replaced by an in-browser JavaScript REPL, and your layout and settings persist to the browser's local storage.

It's the quickest way to feel the panes-and-tabs workflow. Note that the embedded browser there loads pages directly (no proxy), so only sites that allow embedding will appear. For real terminals and the full proxy, install Meowtrix.