clay-server 2.19.0 → 2.20.0-beta.2

package/README.md

@@ -1,10 +1,12 @@
-# Clay
+<p align="center">
+  <img src="media/logo/icon-full-banded-256-transparent.png" alt="Clay" />
+</p>
 
-<h3 align="center">Claude Code in your browser. Bring your team, or build one.</h3>
+<h3 align="center">Your AI dev team. Not another coding agent.</h3>
 
 [![npm version](https://img.shields.io/npm/v/clay-server)](https://www.npmjs.com/package/clay-server) [![npm downloads](https://img.shields.io/npm/dw/clay-server)](https://www.npmjs.com/package/clay-server) [![GitHub stars](https://img.shields.io/github/stars/chadbyte/clay)](https://github.com/chadbyte/clay) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/chadbyte/clay/blob/main/LICENSE)
 
-Everything Claude Code does, Clay does in your browser. Plus multi-session, file browser, scheduled agents, mobile notifications, and more. Invite your team to work together in the same session, or build an AI team from scratch. **Your machine is the server.** No cloud relay, no middleman.
+AI teammates who remember your decisions, challenge your thinking, and grow with your codebase. Runs on your machine.
 
 ```bash
 npx clay-server
@@ -15,78 +17,64 @@ npx clay-server
 
 ## What you get
 
-### Everything the CLI does
-
-Your CLI sessions, your CLAUDE.md rules, your MCP servers. **All of it works in Clay as-is.** Pick up a CLI session in the browser, or continue a browser session in the CLI. Same SDK, same tools, same results.
-
-<p align="center">
-  <img src="media/split.gif" alt="split-screen workflow" width="700">
-</p>
-
-### Everything the CLI doesn't
+### Debate before you decide
 
-**Multiple agents, multiple projects, at the same time.** Switch between them in the sidebar. Browse project files live while the agent works, with syntax highlighting for 180+ languages. Mermaid diagrams render as diagrams. Tables render as tables.
+<!-- TODO: debate.gif -->
 
-**Schedule agents with cron**, or let them run autonomously with **Ralph Loop**. Your phone buzzes when Claude needs approval, finishes a task, or hits an error. Install as a **PWA for push notifications**. Close your laptop, sessions keep running.
+Let your Mates challenge each other. Set up a debate. Pick a moderator and panelists, give them a topic, and let them go. You can raise your hand to interject.
 
-<p align="center">
-  <img src="media/phone.gif" alt="Clay on phone" width="280">
-</p>
+"REST vs GraphQL for the new API?" "Monorepo or separate repos?" "This architecture won't scale past 10k users. Here's why." Get opposing perspectives before you commit.
 
-### Bring your whole team
+### Build your team with Mates
 
-**One API key runs the whole workspace.** Invite teammates, set permissions per person, per project, per session. A designer reports a bug in plain language. A junior dev works with guardrails. If someone gets stuck, **jump into their session** to help in real time.
+<!-- TODO: mates.gif -->
 
-Add a CLAUDE.md and the AI operates within those rules: explains technical terms simply, escalates risky operations to seniors, summarizes changes in plain words. Real-time presence shows who's where.
+Mates are AI teammates shaped through real conversation, built to hold their own perspective. Give them a name, avatar, expertise, and working style. **They don't flatter you. They push back.**
 
-### Build your team with Mates
+@mention them in any project session, DM them directly, or bring multiple into the same conversation. Each Mate builds persistent knowledge over time, remembering past decisions, project context, and how you work together.
 
-Not *"act like a design expert."* Mates are AI teammates shaped through real conversation, trained with your context, and built to hold their own perspective. Give them a name, avatar, expertise, and working style. **They don't flatter you. They push back.**
+### Drop-in replacement
 
-They live in your sidebar next to your human teammates. @mention them in any project session when you need their take, DM them directly, or bring multiple into the same conversation. Each Mate builds persistent knowledge over time, remembering past decisions, project context, and how you work together.
+Your existing agent setup works as-is. CLI sessions, CLAUDE.md rules, MCP servers. **No migration needed.** Pick up a CLI session in the browser, or continue a browser session in the CLI.
 
-#### Debate before you decide
+### Your machine, your server
 
-Let your Mates challenge each other. Set up a debate. Pick a moderator and panelists, give them a topic, and let them go. You can raise your hand to interject. When it wraps up, you get opposing perspectives from every angle.
+Clay runs as a daemon on your machine. **No cloud relay, no intermediary service.** Schedule agents with cron, get push notifications on your phone, close your laptop. Sessions keep running.
 
-"Should we rewrite this in Rust?" "Should we delay the launch to fix onboarding?" "Should we position this as enterprise-first or PLG?" Get real opposing perspectives before you commit.
+### Bring your whole team
 
-### Your machine, your server
+**One API key runs the whole workspace.** Invite teammates, set permissions per person, per project, per session. If someone gets stuck, **jump into their session** to help in real time.
 
-Clay runs as a daemon on your machine. **No cloud relay, no intermediary service** between your browser and your code. Data flows directly to the Anthropic API, exactly as it does from the CLI.
+### Before vs Clay
 
-PIN authentication, per-project permissions, and HTTPS are built in. For remote access, use a VPN like Tailscale.
+| Before | With Clay |
+|---|---|
+| One CLI session at a time | Multiple agents across projects, persistent |
+| No shared context across teammates | Shared workspace with roles and permissions |
+| No memory between decisions | AI that remembers past decisions and challenges new ones |
+| No teammates, just prompts | Mates with names, knowledge, and opinions |
 
----
+### Why not just use Claude Code directly?
 
-## How a bug gets fixed
+Claude Code is excellent for solo coding. Clay is for when you need more than a single agent session. A team that debates your architecture decisions. AI colleagues who remember what you decided last month. A workspace where your human teammates and AI teammates sit side by side.
 
-**Without Clay:**
-Designer finds a bug → writes up a ticket on Asana → dev asks clarifying questions → PM prioritizes → dev opens terminal, fixes it → shares a preview → QA checks → deploy
-<br>*7 steps. 3 people. 2 days.*
+If Claude Code is a solo instrument, Clay is the band.
 
-**With Clay:**
-Designer opens Clay in the browser, describes the bug in plain language → senior joins the same session, reviews the fix together → merge
-<br>*2 steps. 2 people. Minutes. The designer never touched a terminal.*
+## Who is Clay for
 
----
+- **Solo dev juggling multiple roles.** You need a code reviewer, a marketing lead, a writing partner, but it's just you. Build them as Mates.
+- **Small team sharing one AI workflow.** One API key, everyone in the browser, no terminal knowledge required.
+- **Founder doing dev + product + ops.** Run agents overnight, get notified on your phone, review in the morning.
 
-## How Clay compares
+## Why I built Clay
 
-*As of March 2026.*
+I wanted AI teammates, not just a coding agent. The underlying agent is the best foundation for a personal AI I've found. I wanted to turn it into my own AI assistant, one that knows my context, remembers my decisions, and works the way I work.
 
-| | CLI | Remote Control | Channels | **Clay** |
-|---|---|---|---|---|
-| Multi-user with roles | – | – | Platform-dependent | **Accounts + RBAC** |
-| AI teammates (Mates + Debates) | – | – | – | **Yes** |
-| Join teammate's session | – | – | – | **Yes** |
-| Persistent daemon | – | Session-based | – | **Yes** |
-| Native mobile app | – | **Yes** | **Platform app** | PWA |
-| Official support | **Anthropic** | **Anthropic** | **Anthropic** | Community |
+That started as a browser interface so I could access it from anywhere. Then I added multi-user so my team could use it too. Then I started building the AI teammates themselves.
 
-Clay is a community project, not affiliated with Anthropic. Official tools receive guaranteed support and updates.
+Most AI agent projects go for full autonomy. Let the AI loose, give it all the permissions, let it run. I wanted the opposite: **AI that works as part of a team.** Visible, controllable, accountable. Your teammates can see what the agent is doing, jump in when it needs help, and set the rules it operates under.
 
----
+That's Clay now. A workspace where AI teammates have names, persistent memory, and their own perspective. Not "act like an expert" prompting. Actual teammates that push back, remember last week, and sit in your sidebar next to your human colleagues.
 
 ## Getting Started
 
@@ -96,21 +84,25 @@ Clay is a community project, not affiliated with Anthropic. Official tools recei
 npx clay-server
 ```
 
-On first run, it walks you through port and PIN setup.
+On first run, it asks for a port number and whether you're using it solo or with a team.
 Scan the QR code to connect from your phone instantly.
 
 For remote access, use a VPN like Tailscale.
 
-<p align="center">
-  <img src="media/start.gif" alt="Clay starting from CLI" width="600">
-</p>
+## Philosophy
 
----
+**AI is a teammate, not a tool.** A tool gets used once and forgotten. A teammate accumulates your history, your decisions, your working style. Give them a specialty, let them build context over time, and bring them into any project as a colleague.
+
+**AI should understand you first.** When you create a Mate, set up a scheduled task, or start a Ralph Loop, Clay interviews you. Not to save time, but to use AI's capability to understand what you actually want. "Just do it for me" is a trap. The better AI understands you, the better the output.
+
+**Your data is yours.** Sessions are JSONL files. Settings are JSON. Knowledge is Markdown. Everything lives on your machine in formats you can read, move, and back up. No proprietary database, no cloud lock-in. If you stop using Clay tomorrow, your data doesn't disappear.
+
+**Friction is a feature.** The goal of AI is not to remove all friction. It's to free you to focus on the friction that matters. Reviewing a critical decision, shaping the direction, catching what the agent missed. Clay keeps those moments in, on purpose.
 
 ## FAQ
 
 **"Is this just a terminal wrapper?"**
-No. Clay runs on the Claude Agent SDK. It doesn't wrap terminal output. It communicates directly with the agent through the SDK.
+No. Clay is a team workspace that happens to use Claude as its engine. It manages AI teammates, persistent knowledge, and structured debates. The agent runtime is an implementation detail.
 
 **"Does my code leave my machine?"**
 The Clay server runs locally. Files stay local. Only Claude API calls go out, which is the same as using the CLI.
@@ -127,36 +119,8 @@ No. Teammates share the Claude Code session logged in on the server. You can als
 **"Does it work with MCP servers?"**
 Yes. MCP configurations from the CLI carry over as-is.
 
----
-
-## HTTPS
-
-HTTPS is enabled by default using a builtin wildcard certificate for `*.d.clay.studio`. No setup required. Available from `v2.17.0-beta.2`. Your browser connects to a URL like:
-
-```
-https://192-168-1-50.d.clay.studio:2633
-```
-
-The domain resolves to your local IP. All traffic stays on your network. See [clay-dns](clay-dns/) for details on how this works.
-
-Push notifications require HTTPS, so they work out of the box with this setup. Install Clay as a PWA on your device to receive them.
-
-<details>
-<summary><strong>Alternative: local certificate with mkcert</strong></summary>
-
-If you prefer to use a locally generated certificate (e.g. air-gapped environments where DNS is unavailable):
-
-```bash
-brew install mkcert
-mkcert -install
-npx clay-server --local-cert
-```
-
-This generates a self-signed certificate trusted by your machine. The setup wizard will guide you through installing the CA on other devices.
-
-</details>
-
----
+**"What is d.clay.studio in my browser URL?"**
+It's a DNS-only service that resolves to your local IP for HTTPS certificate validation. No data passes through it. All traffic stays between your browser and your machine. See [clay-dns](clay-dns/) for details.
 
 ## CLI Options
 
@@ -180,11 +144,9 @@ npx clay-server --dangerously-skip-permissions
 npx clay-server --dev        # Dev mode (foreground, auto-restart on lib/ changes, port 2635)
 ```
 
----
-
 ## Architecture
 
-Clay drives Claude Code execution through the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) and streams it to the browser over WebSocket.
+Clay drives agent execution through the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) and streams it to the browser over WebSocket.
 
 ```mermaid
 graph LR
@@ -207,8 +169,6 @@ graph LR
 
 For detailed sequence diagrams, daemon architecture, and design decisions, see [docs/architecture.md](docs/architecture.md).
 
----
-
 ## Contributors
 
 <a href="https://github.com/chadbyte/clay/graphs/contributors">

package/bin/cli.js

@@ -33,7 +33,7 @@ if (_isDev || process.argv.includes("--debug")) {
 }
 
 var crypto = require("crypto");
-var { loadConfig, saveConfig, configPath, socketPath, logPath, ensureConfigDir, isDaemonAlive, isDaemonAliveAsync, generateSlug, clearStaleConfig, loadClayrc, saveClayrc, readCrashInfo } = require("../lib/config");
+var { loadConfig, saveConfig, configPath, socketPath, logPath, ensureConfigDir, isDaemonAlive, isDaemonAliveAsync, generateSlug, clearStaleConfig, loadClayrc, saveClayrc, readCrashInfo, REAL_HOME } = require("../lib/config");
 var { sendIPCCommand } = require("../lib/ipc");
 var { generateAuthToken } = require("../lib/server");
 var { enableMultiUser, disableMultiUser, hasAdmin, isMultiUser } = require("../lib/users");
@@ -610,8 +610,7 @@ function ensureCerts(ip) {
     return null;
   }
 
-  var homeDir = os.homedir();
-  var certDir = path.join(process.env.CLAY_HOME || path.join(homeDir, ".clay"), "certs");
+  var certDir = path.join(process.env.CLAY_HOME || path.join(REAL_HOME, ".clay"), "certs");
   var keyPath = path.join(certDir, "key.pem");
   var certPath = path.join(certDir, "cert.pem");
 
@@ -891,7 +890,7 @@ function promptText(title, placeholder, callback, opts) {
 
     // Resolve ~ to home
     if (current.charAt(0) === "~") {
-      current = os.homedir() + current.substring(1);
+      current = REAL_HOME + current.substring(1);
     }
 
     var resolved = path.resolve(current);
@@ -1605,14 +1604,11 @@ async function forkDaemon(mode, keepAwake, extraProjects, addCwd, wantOsUsers) {
   }
 
   // Enable/disable multi-user mode based on startup config
+  var _pendingSetupCode = null;
   if (config.mode === "multi") {
     var muResult = enableMultiUser();
     if (muResult.setupCode) {
-      log("");
-      log(sym.done + "  " + a.green + "Multi-user mode enabled." + a.reset);
-      log(sym.bar + "  Setup code:  " + a.bold + muResult.setupCode + a.reset);
-      log(sym.bar + "  Open Clay in your browser and enter this code to create the admin account.");
-      log("");
+      _pendingSetupCode = muResult.setupCode;
     }
   } else if (isMultiUser()) {
     disableMultiUser();
@@ -1628,13 +1624,19 @@ async function forkDaemon(mode, keepAwake, extraProjects, addCwd, wantOsUsers) {
     console.log("  " + sym.done + "  " + url);
     if (config.builtinCert) console.log("  " + sym.done + "  d.clay.studio provides HTTPS certificates only. Your traffic never leaves your network.");
     if (config.mkcertDetected) console.log("  " + sym.warn + "  Clay now ships with a builtin HTTPS certificate. To use it, pass --builtin-cert or uninstall mkcert.");
+    if (_pendingSetupCode) {
+      console.log("");
+      console.log("  " + sym.done + "  " + a.green + "Multi-user mode enabled." + a.reset);
+      console.log("  " + sym.bar + "  Setup code:  " + a.bold + _pendingSetupCode + a.reset);
+      console.log("  " + sym.bar + "  Open Clay in your browser and enter this code to create the admin account.");
+    }
     console.log("  " + sym.done + "  Headless mode — exiting CLI");
     process.exit(0);
     return;
   }
 
   // Show success + QR
-  showServerStarted(config, ip);
+  showServerStarted(config, ip, _pendingSetupCode);
 }
 
 // ==============================
@@ -1959,14 +1961,14 @@ async function restartDaemonWithTLS(config, callback) {
 // ==============================
 // Show server started info
 // ==============================
-function showServerStarted(config, ip) {
-  showMainMenu(config, ip);
+function showServerStarted(config, ip, setupCode) {
+  showMainMenu(config, ip, setupCode);
 }
 
 // ==============================
 // Main management menu
 // ==============================
-function showMainMenu(config, ip) {
+function showMainMenu(config, ip, setupCode) {
   startDaemonWatcher();
   var protocol = config.tls ? "https" : "http";
   var url = config.builtinCert
@@ -2007,6 +2009,12 @@ function showMainMenu(config, ip) {
         log("");
       }
 
+      if (setupCode) {
+        log("  " + a.yellow + sym.warn + " Setup code:  " + a.bold + setupCode + a.reset);
+        log("  " + a.dim + "Open Clay in your browser and enter this code to create the admin account." + a.reset);
+        log("");
+      }
+
       showMenuItems();
     }
 
@@ -2507,7 +2515,19 @@ function showSettingsMenu(config, ip) {
         ], function (confirmChoice) {
           if (confirmChoice === "confirm") {
             sendIPCCommand(socketPath(), { cmd: "set_os_users", value: true }).then(function (res) {
-              if (res.ok) {
+              if (res.error === "acl_not_installed") {
+                log(sym.bar);
+                log(sym.bar + "  " + a.red + sym.warn + " setfacl is not installed." + a.reset);
+                log(sym.bar);
+                log(sym.bar + "  OS user isolation requires the ACL (Access Control List) package");
+                log(sym.bar + "  to manage per-user file permissions on shared projects.");
+                log(sym.bar);
+                log(sym.bar + "  " + a.bold + "Install it:" + a.reset);
+                log(sym.bar + "  " + a.cyan + res.installCmd + a.reset);
+                log(sym.bar);
+                log(sym.bar + "  " + a.dim + "Then try enabling OS user isolation again." + a.reset);
+                log(sym.bar);
+              } else if (res.ok) {
                 config.osUsers = true;
                 log(sym.bar);
                 log(sym.done + "  " + a.green + "OS-level user isolation enabled." + a.reset);
@@ -2858,6 +2878,21 @@ var currentVersion = require("../package.json").version;
         return;
       }
 
+      // os-users requires setfacl (ACL package)
+      if (savedOsUsers && process.platform === "linux") {
+        var { checkAclSupport } = require("../lib/os-users");
+        var aclCheck = checkAclSupport();
+        if (!aclCheck.available) {
+          console.error(a.red + "OS user isolation requires the 'acl' package (setfacl)." + a.reset);
+          console.error("");
+          console.error("Install it:  " + a.bold + aclCheck.installCmd + a.reset);
+          console.error("");
+          console.error("Then restart Clay.");
+          process.exit(1);
+          return;
+        }
+      }
+
       if (savedConfig && savedConfig.port) port = savedConfig.port;
       if (savedConfig && savedConfig.host) host = savedConfig.host;
       if (savedConfig && savedConfig.dangerouslySkipPermissions) dangerouslySkipPermissions = true;