overmux 0.0.4 → 0.0.6

package/dist/docs/000-index.md

@@ -1,15 +1,13 @@
 ---
 title: Overmux documentation
-description: Build and understand an Overmux application.
 ---
 
 # Overmux documentation
 
 Overmux is a local or self-hosted web UI for tmux sessions, Pi agents, and Git workspaces.
 
-- [What is Overmux?](./100-introduction/100-what-is-overmux.md)
 - [How Overmux Works](./100-introduction/200-how-overmux-works.md)
-- [Why Overmux?](./100-introduction/300-why-overmux.md)
+- [Why I Built Overmux](./100-introduction/300-why-i-built-overmux.md)
 - [Install and Run Overmux](./200-getting-started/100-install-and-run-overmux.md)
 - [Install Overmux Desktop](./200-getting-started/200-install-overmux-desktop.md)
 - [Install Overmux PWA](./200-getting-started/300-install-overmux-pwa.mdx)
@@ -18,4 +16,4 @@ Overmux is a local or self-hosted web UI for tmux sessions, Pi agents, and Git w
 - [Cloudflare Tunnel](./200-getting-started/400-secure-with-https/300-cloudflare-tunnel.md)
 - [Self-hosted Reverse Proxy](./200-getting-started/400-secure-with-https/400-self-hosted-reverse-proxy.md)
 
-Run `overmux docs` to print the absolute path to this installed documentation directory.
+Run `overmux docs path` to print the absolute path to this installed documentation directory.

package/dist/docs/100-introduction/200-how-overmux-works.md

@@ -2,6 +2,130 @@
 title: How Overmux Works
 ---
 
-Overmux is a [light-weight web framework](oxymoron definition), designed to be run in an Electron shell, a PWA on your phone, or a mobile app.
+Overmux lets you build your own customized dev environment by writing TypeScript server code for Node.js and React components for your browser UI.
 
-It's highly customizable
+Run `overmux serve` on your dev machine to expose your dev environment in the browser on localhost:4242.
+
+## The Overmux server
+
+`overmux serve` runs your server-side Node.js code and serves your React UI, bundled using [Vite](https://vite.dev/).
+
+Overmux server code is organized around three concepts:
+
+### Resources
+
+Resources expose server-side data from your dev machine, making them available in your UI.
+
+For example, to run `ls /` on your server and expose the result:
+
+```ts
+// server.ts
+defineOvermuxServer({
+  resources: {
+    ls: {
+      kind: "query",
+      contract: defineResourceContract({
+        input: noInputSchema,
+        output: z.array(z.string()),
+      }),
+      read: async () => {
+        const { stdout } = await execFileAsync("ls", ["/"]);
+        return stdout.split("\n").filter(Boolean);
+      },
+    },
+  },
+});
+```
+
+Later in React:
+
+```tsx
+const ls = useResource({ id: "ls" });
+
+return (
+  <div>
+    {ls.data?.map((name) => (
+      <div key={name}>{name}</div>
+    ))}
+  </div>
+);
+```
+
+Resources have three modes: **query** reads data on request, **subscription** adds change notifications, and **derived** computes a value from other resources. See [resources docs](../400-reference/500-server/100-resources.md) for more details.
+
+### Operations
+
+Operations are "calls" you can make to your server code.
+
+For example:
+
+```ts
+defineOvermuxServer({
+  operations: {
+    helloWorld: defineOperation({
+      input: noInputSchema,
+      handle: () => console.log("Hello world"),
+    }),
+  },
+});
+```
+
+Trigger it from React:
+
+```tsx
+const helloWorld = useOperation({ id: "helloWorld" });
+
+return <button onClick={() => helloWorld.mutate()}>Say hello</button>;
+```
+
+Or run `overmux call helloWorld` on your server. This also allows your agents to call Overmux operations.
+
+Operations can run your server-side code, invalidate resources, or send notifications using `notifications.send()`.
+
+See [Operations](../400-reference/500-server/200-operations.md) for defining and calling operations.
+
+### Streams
+
+Streams are high throughput bidirectional streams. They're used when latency and throughput are important.
+
+Examples:
+- Connecting to tmux
+- Streaming AI Agent output
+
+See [Streams](../400-reference/500-server/300-streams.md) for defining and consuming streams.
+
+### Ecosystem packages
+
+Overmux's resource, operation, and stream APIs let the community publish npm packages for common development tasks.
+
+## The Overmux client
+
+The Overmux client is a website built with React and TypeScript (TSX), bundled using [Vite](https://vite.dev/).
+
+See [Client](../400-reference/600-client/000-index.md) for defining your browser application.
+
+## Authentication
+
+Overmux handles authentication for you. This is important because most overmux setups give sensitive access to your dev machine.
+
+Run `overmux serve` and then `overmux auth login` to get a login code or a link to instantly login.
+
+See [Authentication and Security](../400-reference/400-authentication-and-security.md) for more details.
+
+## Technology choices
+
+### Mandatory
+
+- **[Node.js](https://nodejs.org/)** runs your server code and the Overmux CLI.
+- **[TypeScript](https://www.typescriptlang.org/)** provides type checking across your server and UI. This is the expected development workflow; Overmux does not require you to run `tsc` before serving.
+- **[React and React DOM](https://react.dev/)** render your UI.
+- **[Vite](https://vite.dev/)** serves your UI during development and builds it for production.
+- **[Zod](https://zod.dev/)** defines and validates your API's input and output schemas.
+
+### Recommended
+
+- **[Mise](https://mise.jdx.dev/)** manages developer tools and their versions; `overmux init` uses it when installed and activated.
+- **[pnpm](https://pnpm.io/)** manages application dependencies; required by `overmux init`.
+
+
+You can use any other npm packages you like. You can make your own choices for routing, styling, and component libraries. See [tech stack recommendations](../400-reference/600-client/300-tech-stack-recommendations.md) for some recommendations if you're new to building for the web.

package/dist/docs/100-introduction/{300-why-overmux.md → 300-why-i-built-overmux.md}

@@ -1,5 +1,5 @@
 ---
-title: Why Overmux?
+title: Why I Built Overmux
 ---
 
 As AI coding agents have improved my time has shifted from:

package/dist/docs/200-getting-started/100-install-and-run-overmux.md

@@ -37,7 +37,7 @@ Once the CLI is installed, create your Overmux setup:
 overmux init
 ```
 
-This validates your toolchain, creates a minimal application in `$XDG_CONFIG_HOME/overmux`, installs its dependencies, and checks the result. Existing scaffold files are left unchanged. Read more in the [`overmux init` reference](../400-reference/400-cli/050-init.md) and [project structure](../300-fundamentals/100-project-structure.md).
+This validates your toolchain, creates a minimal application in `$XDG_CONFIG_HOME/overmux` (default `~/.config/overmux`; see [storage locations](../400-reference/300-storage-locations.md)), installs its dependencies, and checks the result. Existing scaffold files are left unchanged. Read more in the [`overmux init` reference](../400-reference/700-cli/050-init.md) and [project structure](../400-reference/100-project-structure.md).
 
 ## Start the server
 
@@ -47,4 +47,4 @@ overmux serve
 
 Open Overmux in your browser to confirm it works.
 
-To configure hosts and ports, see [Configuration](../300-fundamentals/200-configuration.md).
+To configure hosts and ports, see [Configuration](../400-reference/200-configuration.md).

package/dist/docs/200-getting-started/400-secure-with-https/200-tailscale-serve.md

@@ -16,7 +16,7 @@ export default defineOvermuxConfig({
     trustedProxyPeer: "127.0.0.1",
   },
   host: "127.0.0.1",
-  port: 4200,
+  port: 4242,
   // ...
 });
 ```
@@ -34,11 +34,11 @@ overmux serve
 In another terminal, publish its loopback listener through Tailscale Serve:
 
 ```bash
-tailscale serve --bg http://127.0.0.1:4200
+tailscale serve --bg http://127.0.0.1:4242
 ```
 
 Open the HTTPS URL printed by Tailscale on another device in your tailnet. Run `overmux auth login` to create a login link if authentication is enabled.
 
-Do not expose port 4200 directly or change `trustedProxyPeer` to a non-loopback address. Overmux trusts forwarded HTTPS and host information only from this immediate proxy peer.
+Do not expose port 4242 directly or change `trustedProxyPeer` to a non-loopback address. Overmux trusts forwarded HTTPS and host information only from this immediate proxy peer.
 
 See Tailscale's [Serve documentation](https://tailscale.com/docs/features/tailscale-serve) for installation, tailnet access controls, and command reference.

package/dist/docs/200-getting-started/400-secure-with-https/300-cloudflare-tunnel.md

@@ -22,7 +22,7 @@ credentials-file: /home/you/.cloudflared/<tunnel-id>.json
 
 ingress:
   - hostname: overmux.example.com
-    service: http://127.0.0.1:4200
+    service: http://127.0.0.1:4242
   - service: http_status:404
 ```
 
@@ -38,7 +38,7 @@ export default defineOvermuxConfig({
     trustedProxyPeer: "127.0.0.1",
   },
   host: "127.0.0.1",
-  port: 4200,
+  port: 4242,
   // ...
 });
 ```

package/dist/docs/200-getting-started/400-secure-with-https/400-self-hosted-reverse-proxy.md

@@ -20,13 +20,13 @@ export default defineOvermuxConfig({
     trustedProxyPeer: "127.0.0.1",
   },
   host: "127.0.0.1",
-  port: 4200,
+  port: 4242,
   // ...
 });
 ```
 
 Do not expose the loopback backend directly or configure a non-loopback address as `trustedProxyPeer`.
 
-For complete proxy-specific walkthroughs and example configurations, see Open WebUI's [HTTPS and reverse proxy guide](https://docs.openwebui.com/reference/https/). Adapt the upstream address and port to `http://127.0.0.1:4200`, and retain Overmux's origin and trusted-proxy configuration above.
+For complete proxy-specific walkthroughs and example configurations, see Open WebUI's [HTTPS and reverse proxy guide](https://docs.openwebui.com/reference/https/). Adapt the upstream address and port to `http://127.0.0.1:4242`, and retain Overmux's origin and trusted-proxy configuration above.
 
 You can also consult the official documentation for [Caddy](https://caddyserver.com/docs/quick-starts/reverse-proxy), [Nginx](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/), or [HAProxy](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/proxying-essentials/).

package/dist/docs/200-getting-started/500-set-up-overmux-with-packages.md

@@ -0,0 +1,42 @@
+---
+title: Set Up with Packages
+---
+
+To understand how Overmux works and how to configure your Overmux, start with the [reference docs](/docs/reference/project-structure). They cover your project structure, configuration, server, and browser UI.
+
+To get the most out of Overmux you'll want to use some packages.
+
+## What are packages?
+
+Packages are building blocks for your Overmux. They can provide server functionality, UI components, or both.
+
+Overmux packages are just standard npm packages you install and use in your Overmux project.
+
+## Packages to start with
+
+### Terminals with xterm and tmux
+
+Use these two packages together to add interactive terminals backed by persistent tmux sessions.
+
+- **[tmux](/docs/packages/tmux)** connects your Overmux to your machine's tmux sessions, windows, and panes. It provides live state, terminal streaming, and operations for controlling tmux, along with React components and hooks for your UI.
+- **[xterm](/docs/packages/xterm)** renders an [xterm.js](https://xtermjs.org/) terminal in your browser. It handles terminal display and input, but doesn't start a shell or manage sessions.
+
+Together, they let you interact with your terminals through Overmux UI while tmux keeps your sessions running when you disconnect.
+
+Follow the package docs for installation and wiring examples.
+
+### Source control with git
+
+The **[git package](/docs/packages/git)** adds repository changes and diffs to your Overmux, with ready-made UI components for browsing them.
+
+You choose which repository paths your server can access. You can also enable actions such as staging, unstaging, and discarding changes; write permissions are off by default.
+
+## Explore more packages
+
+Depending on your setup, you might also want:
+
+- **[Zellij](/docs/packages/zellij)** for a Zellij-backed terminal setup instead of tmux. Experimental; compatibility is not guaranteed.
+- **[Pi](/docs/packages/pi)** for viewing AI agent conversations and interacting with running agents. Experimental; compatibility is not guaranteed.
+- **[JSONL store](/docs/packages/jsonl-store)** for storing schema-validated records in a local file.
+
+Start with the pieces you need. Each package's documentation explains what it provides and how to connect it to your Overmux.

package/dist/docs/400-reference/100-project-structure.md

@@ -0,0 +1,83 @@
+---
+title: Project Structure
+---
+
+Your Overmux application lives in `~/.config/overmux/`. Here is the project structure after running `overmux init`:
+
+```text
+~/.config/overmux/
+├── overmux.config.ts     # Connects your server and browser UI
+├── vite.config.ts        # UI build configuration
+├── package.json          # Dependencies and scripts
+├── pnpm-lock.yaml        # Locked dependency versions (via pnpm)
+├── mise.toml             # Tool versions, when using Mise. Manages pnpm version.
+├── AGENTS.md             # Instructions for coding agents
+├── CLAUDE.md
+├── .gitignore
+└── src/
+    ├── server/
+    │   └── index.ts      # Your Overmux serve side code, runs in Node.js
+    └── ui/
+        ├── app.tsx       # Your React UI, Shortcuts etc.
+        ├── main.tsx      # UI entrypoint
+        ├── index.html    # HTML entry point
+        └── styles.css
+```
+
+See [Storage Locations](./300-storage-locations.md) for directory defaults and overrides.
+
+# Server
+
+Your server definition lives in `src/server/index.ts` and runs in Node.js. Import it into `overmux.config.ts` and pass it as `server`:
+
+```ts title="overmux.config.ts"
+import { defineOvermuxConfig } from "overmux";
+
+import server from "./src/server/index"; // import it
+
+export default defineOvermuxConfig({
+  server, // pass it to overmux
+
+  auth: { mode: "cli-login" },
+  productionWebAssetsDir: "./dist",
+  vite: "./vite.config.ts",
+});
+```
+
+Define your server's capabilities with [Resources](./500-server/100-resources.md), [Operations](./500-server/200-operations.md), and [Streams](./500-server/300-streams.md).
+
+# Client
+
+By default your Overmux client code lives in `src/ui/` and is built using [Vite](https://vite.dev/). Point `vite` in `overmux.config.ts` to your Vite configuration:
+
+```ts title="overmux.config.ts"
+import { defineOvermuxConfig } from "overmux";
+import server from "./src/server/index";
+
+export default defineOvermuxConfig({
+  server,
+  auth: { mode: "cli-login" },
+  productionWebAssetsDir: "./dist",
+
+  vite: "./vite.config.ts", // vite configuration
+});
+```
+
+The default `vite.config.ts` sets `src/ui/` as the UI root and builds production assets into `dist/`:
+
+```ts title="vite.config.ts"
+import viteReact from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  build: { emptyOutDir: true, outDir: "../../dist" },
+  plugins: [viteReact()],
+  root: "src/ui",
+});
+```
+
+This is a pretty vanilla Vite React application which is yours to configure how you see fit.
+
+See [Client](./600-client/000-index.md) for building your UI, [Client API](./600-client/100-api.md) for available APIs, and [Theming](./600-client/200-theming.md) for styling.
+
+

package/dist/docs/400-reference/200-configuration.md

@@ -0,0 +1,257 @@
+---
+title: Configuration
+---
+
+## `overmux.config.ts`
+
+Loaded from `$XDG_CONFIG_HOME/overmux/overmux.config.ts`, fallback: `~/.config/overmux/overmux.config.ts`. Override with `--config /another/overmux.config.ts`. See [storage locations](/docs/reference/storage-locations).
+
+### `server`
+
+```ts
+import { defineOvermuxConfig, defineOvermuxServer } from "overmux";
+
+export default defineOvermuxConfig({
+  // ...other config
+
+  // Required.
+  // Your server's resources, operations, and streams.
+  // Shown inline; prefer defining and exporting this from ./server.ts.
+  server: defineOvermuxServer({
+    resources: {},
+    operations: {},
+    streams: {},
+  }),
+});
+```
+
+See [Server](/docs/reference/server).
+
+### `auth`
+
+```ts
+import { defineOvermuxConfig } from "overmux";
+
+export default defineOvermuxConfig({
+  // ...other config
+
+  // Required.
+  // Configure client authentication.
+  auth: {
+    // Required. Only supported mode: "cli-login".
+    // Authenticate clients using credentials created by the CLI.
+    mode: "cli-login",
+
+    // Default: the server's local origin.
+    // Allowed browser origins. Non-loopback origins require HTTPS.
+    origins: ["http://localhost:4242"],
+
+    // Default: "forever".
+    // Session lifetime: "forever" or a positive whole number with m, h, or d.
+    // For example: "30m", "24h", or "30d".
+    sessionLifetime: "forever",
+
+    // Default: unset; proxy headers are not trusted.
+    // Loopback IP of the reverse proxy allowed to supply forwarded headers.
+    trustedProxyPeer: "127.0.0.1",
+  },
+});
+```
+
+See [`overmux auth`](/docs/reference/cli/auth) for creating and managing credentials.
+
+### `host`
+
+```ts
+import { defineOvermuxConfig } from "overmux";
+
+export default defineOvermuxConfig({
+  // ...other config
+
+  // Default: "localhost".
+  // Network address to listen on.
+  host: "localhost",
+});
+```
+
+See [`overmux serve`](/docs/reference/cli/serve) for command-line overrides.
+
+### `port`
+
+```ts
+import { defineOvermuxConfig } from "overmux";
+
+export default defineOvermuxConfig({
+  // ...other config
+
+  // Default: 4242.
+  // Listening port; an integer from 1-65535.
+  port: 4242,
+});
+```
+
+See [`overmux serve`](/docs/reference/cli/serve) for command-line overrides.
+
+### `instanceId`
+
+```ts
+import { hostname } from "node:os";
+import { defineOvermuxConfig } from "overmux";
+
+export default defineOvermuxConfig({
+  // ...other config
+
+  // Optional custom identity: a fixed ID or a function of the listening port.
+  // Default instance ID:
+  instanceId: ({ port }) => `${hostname()}-${port}`,
+});
+```
+
+IDs must be 1-253 lowercase ASCII characters, start and end with a letter or digit, and contain only letters, digits, dots, or hyphens. Explicit IDs are validated, not normalized. Set an explicit ID if the machine hostname does not meet these rules.
+
+An ID function runs once at startup using the actual listening port. Every address serving the same running instance reports the same ID. Distinct instances need distinct IDs; IDs are not credentials.
+
+See [Deep links](./600-client/007-deep-links.md) and [`overmux instance`](/docs/reference/cli/instance).
+
+### `vite`
+
+```ts
+import { defineOvermuxConfig } from "overmux";
+
+export default defineOvermuxConfig({
+  // ...other config
+
+  // No default; required by `overmux serve`.
+  // Path to your application's Vite configuration.
+  vite: "./vite.config.ts",
+});
+```
+
+See [`overmux serve`](/docs/reference/cli/serve).
+
+### `productionWebAssetsDir`
+
+```ts
+import { defineOvermuxConfig } from "overmux";
+
+export default defineOvermuxConfig({
+  // ...other config
+
+  // No default; required by `overmux serve --production`.
+  // Directory containing the built browser assets.
+  productionWebAssetsDir: "./dist",
+});
+```
+
+See [`overmux serve`](/docs/reference/cli/serve) for production serving.
+
+### `watch`
+
+```ts
+import { defineOvermuxConfig } from "overmux";
+
+export default defineOvermuxConfig({
+  // ...other config
+
+  // Default: true.
+  // Watch application files and restart the development server on changes.
+  watch: true,
+});
+```
+
+See [`overmux serve`](/docs/reference/cli/serve) for development mode.
+
+### `debug`
+
+```ts
+import { defineOvermuxConfig } from "overmux";
+
+export default defineOvermuxConfig({
+  // ...other config
+
+  // Default: true.
+  // Enable debug logging.
+  debug: true,
+});
+```
+
+See [Storage locations](/docs/reference/storage-locations) for the server log location.
+
+### `aiContextSnippets`
+
+```ts
+import { defineOvermuxConfig } from "overmux";
+
+export default defineOvermuxConfig({
+  // ...other config
+
+  // Default: ["package-source", "tech-stack-recommendations"].
+  // Select guidance emitted by `overmux docs ai-context`; [] emits no context.
+  aiContextSnippets: ["package-source", "tech-stack-recommendations"],
+});
+```
+
+See [`overmux docs ai-context`](/docs/reference/cli/docs#overmux-docs-ai-context) for setup instructions and snippet descriptions.
+
+## `overmux.desktop.ts`
+
+Loaded from `$XDG_CONFIG_HOME/overmux/overmux.desktop.ts`, fallback: `~/.config/overmux/overmux.desktop.ts`. A missing file uses the defaults.
+
+Desktop configuration is trusted TypeScript, loaded once at startup. Restart the desktop app after changes. Use `--desktop-config <path>` to load another file.
+
+### `titleBar`
+
+```ts
+import { defineOvermuxDesktopConfig } from "@overmux/desktop";
+
+export default defineOvermuxDesktopConfig({
+  // ...other config
+
+  // Default: "hidden". Options: "hidden", "native".
+  // Show or hide the native window title bar.
+  titleBar: "hidden",
+});
+```
+
+### `menuBar`
+
+```ts
+import { defineOvermuxDesktopConfig } from "@overmux/desktop";
+
+export default defineOvermuxDesktopConfig({
+  // ...other config
+
+  // Default: "auto-hide". Options: "auto-hide", "hidden", "visible".
+  // Control the Linux/Windows window menu; auto-hide reveals it with Alt.
+  // Does not affect the macOS global menu.
+  menuBar: "auto-hide",
+});
+```
+
+### `macosTitleBarStyle`
+
+```ts
+import { defineOvermuxDesktopConfig } from "@overmux/desktop";
+
+export default defineOvermuxDesktopConfig({
+  // ...other config
+
+  // Default: unset; follows titleBar. Options: "native", "transparent".
+  // Override titleBar on macOS; transparent extends content into its area.
+  macosTitleBarStyle: "transparent",
+});
+```
+
+### `macosTrafficLights`
+
+```ts
+import { defineOvermuxDesktopConfig } from "@overmux/desktop";
+
+export default defineOvermuxDesktopConfig({
+  // ...other config
+
+  // Default: "hidden". Options: "hidden", "visible".
+  // Show or hide the macOS close, minimize, and zoom buttons.
+  macosTrafficLights: "hidden",
+});
+```

package/dist/docs/400-reference/300-storage-locations.md

@@ -0,0 +1,46 @@
+---
+title: Storage Locations
+---
+
+Overmux follows [XDG base directory conventions](https://specifications.freedesktop.org/basedir-spec/latest/).
+
+## Configuration
+
+`$XDG_CONFIG_HOME/overmux`, default `~/.config/overmux`.
+
+- `overmux.config.ts`: application configuration. Override with `--config /another/overmux.config.ts`.
+- `overmux.desktop.ts`: optional Overmux Desktop settings. Override with `--desktop-config /another/overmux.desktop.ts`.
+- Your Overmux project, created by `overmux init`. See [project structure](./100-project-structure.md).
+
+## Data
+
+`$XDG_DATA_HOME/overmux`, default `~/.local/share/overmux`.
+
+- `auth/auth.json`: persisted authentication state.
+- `auth/auth.lock`: authentication store lock.
+- `background-notifications/vapid.json`: push notification keys, including the private key.
+- `background-notifications/subscriptions.json`: push notification subscriptions.
+
+## State
+
+`$XDG_STATE_HOME/overmux`, default `~/.local/state/overmux`.
+
+- `overmux.log`: server logs.
+- `desktop/`: desktop profile, including saved server addresses, browser sessions, and Chromium caches. Can contain credentials; not disposable cache.
+
+## Cache
+
+`$XDG_CACHE_HOME/overmux`, default `~/.cache/overmux`.
+
+Cache files; currently unused.
+
+## Runtime
+
+`$XDG_RUNTIME_DIR/overmux`, default `/tmp/overmux-<uid>`.
+
+- `<id>.sock`: per-instance control socket for local CLI requests.
+- `<id>.json`: instance registration, including its process ID, URLs, port, and control socket path.
+
+Overmux uses `/tmp/overmux-<uid>` when `XDG_RUNTIME_DIR` is unset. If the runtime directory path exceeds 80 bytes, Overmux uses `/tmp/overmux-<uid>-<hash>` to stay within socket path limits.
+
+`<uid>` is your numeric user ID. `<hash>` is derived from the original runtime directory path.