muse-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{muse_cli-0.2.0 → muse_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: muse-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: Command-line client for your personal muse.ai AI agent: chat, automate, and manage side chats, feed, goals, ideas, and sessions from the terminal. No browser needed.
 Project-URL: Homepage, https://github.com/nikships/muse-cli
 Project-URL: Documentation, https://github.com/nikships/muse-cli#readme
@@ -66,27 +66,124 @@ A command-line client for your personal muse.ai AI agent: chat from the terminal
 uv tool install muse-cli      # or: pipx install muse-cli   /   pip install muse-cli
 ```
 
-Then log in and check the connection:
+The command is `muse-cli`. The name `muse` belongs to Muse Code on many machines.
+
+Want the agent skill too? The installer sets up the CLI and copies the skill
+to `~/.agents/skills/muse-cli`:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nikships/muse-cli/main/install.sh | bash
+```
+
+Upgrade with `uv tool upgrade muse-cli`, remove with `uv tool uninstall muse-cli`.
+
+Logging in is a separate one-time step. Chrome shares its cookies after you
+turn on remote debugging. Follow [Log in once](#log-in-once) before running
+any other command.
+
+## Log in once
+
+muse-cli borrows the login you already have in Chrome, saves those cookies
+to `~/.config/muse-cli/cookies.txt` (mode `600`, only your user can read it),
+and after that talks to muse.ai directly. Access tokens are fetched fresh
+on every command. When a command later says the cookies expired, repeat this
+section.
+
+Do the steps in order. Each one checks itself before you continue.
+
+### 1. Install the cookie reader
+
+`auth export` uses [agent-browser](https://github.com/vercel-labs/agent-browser)
+to read Chrome's cookies. That package comes from npm, so you need Node.js first.
+
+```bash
+node --version    # if this fails, install Node.js LTS from https://nodejs.org
+                  # and open a new terminal
+npm i -g agent-browser
+agent-browser --version
+```
+
+`npm i -g` needs permission to write to npm's global bin directory. If it
+errors with `EACCES`, pick one and use it from then on: configure an
+[npm prefix you own](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally),
+or run the install with the same rights you use for other global npm tools.
+Then check `command -v agent-browser` prints a path.
+
+### 2. Let Chrome share cookies
+
+Open **Google Chrome**, the same profile you use for muse.ai. Paste this in
+the address bar:
+
+```
+chrome://inspect/#remote-debugging
+```
+
+Turn on remote debugging. The checkbox reads **Allow remote debugging for
+this browser instance**. Leave Chrome open.
+
+Turn this on while Chrome is already open and muse.ai is loaded. The export
+can see that window only after the switch is on. The page is in Chrome 144
+and newer.
+
+Stay in this window. Starting a second Chrome with
+`--remote-debugging-port` opens a different profile, and that profile does
+not have your muse.ai login.
+
+### 3. Be logged in, on a muse.ai tab
+
+In that same Chrome window, open https://muse.ai/ and log in. Leave the tab
+open. The exporter reads whichever tab is active, so the muse.ai tab has to
+be the one in front when you run the next command.
+
+### 4. Save the login
 
 ```bash
-# 1. Log in to https://muse.ai/ in Chrome
-# 2. Export your session (one time; re-run when it expires):
 muse-cli auth export
+```
 
-muse-cli status
+Chrome may ask to allow the debugging connection. Click **Allow**. If the
+command already failed, run it again after you click Allow.
+
+Success looks like this (the count varies):
+
+```
+saved 12 muse.ai cookies to /home/you/.config/muse-cli/cookies.txt
 ```
 
-Want the agent skill too? The installer sets up the CLI and copies the skill
-to `~/.agents/skills/muse-cli`:
+The command prints the fix on the failure itself. These are the ones it
+recognizes:
+
+| What it says | What to do |
+| --- | --- |
+| No running Chrome / remote debugging | The switch in step 2 is off. Turn it on in the Chrome you already have open, then run the command again. |
+| No muse.ai tab | Step 3. Open https://muse.ai/ in that same window and leave the tab open. |
+| No `hatch_sess` | The tab is open and you are logged out. Log in, then export again. The cookies file already on disk is left as it was. |
+| `agent-browser` is not installed | Step 1. `node --version`, then `npm i -g agent-browser`, then a new terminal. |
+| Daemon already running | A previous attempt is stuck. `agent-browser close`, then `muse-cli auth export`. |
+
+### 5. Check the connection
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/nikships/muse-cli/main/install.sh | bash
+muse-cli status
 ```
 
-Upgrade with `uv tool upgrade muse-cli`, remove with `uv tool uninstall muse-cli`.
+You get JSON with your VM id, how many chats you have, the unread count, and
+your identity. That means install and login both worked.
 
-The command is `muse-cli`, not `muse`, because `muse` clashes with Muse Code
-on many machines.
+### Copy cookies by hand
+
+Use this when you don't have Node, or you don't want remote debugging on.
+
+1. In Chrome, open https://muse.ai/ and log in.
+2. Open DevTools (F12, or Ctrl+Shift+I) → **Application** → **Cookies** → `https://muse.ai`.
+3. Copy the cookies onto one line. `hatch_sess` has to be there. Separate cookies with `; ` (semicolon, space). A Netscape cookie jar (what curl writes) and a JSON object such as `{"hatch_sess": "..."}` also work.
+
+```bash
+mkdir -p ~/.config/muse-cli
+printf '%s\n' 'hatch_sess=the-value-from-devtools; other_cookie=other_value' > ~/.config/muse-cli/cookies.txt
+chmod 600 ~/.config/muse-cli/cookies.txt
+muse-cli status
+```
 
 ## Usage
 
@@ -164,12 +261,13 @@ pyproject.toml
 
 ## Setup notes
 
-- `auth export` reads cookies from a running Chrome via
-  [agent-browser](https://github.com/nikships/foundry) (`npm i -g agent-browser`).
-  No Chrome? Copy your `muse.ai` cookies into `~/.config/muse-cli/cookies.txt`
-  by hand (Netscape jar or `name=value; ...` format, needs `hatch_sess`).
-- Cookies live at `~/.config/muse-cli/cookies.txt` (mode 600). Access and
-  gateway tokens are fetched fresh on every run, nothing long-lived is stored.
+- Login is the [Log in once](#log-in-once) section above. Cookies live at
+  `~/.config/muse-cli/cookies.txt` (mode 600). Access and gateway tokens are
+  fetched fresh on every run.
+- `auth export` reads those cookies from Google Chrome through
+  [agent-browser](https://github.com/vercel-labs/agent-browser). Chrome has
+  to be open, with remote debugging on
+  (`chrome://inspect/#remote-debugging`) and a logged-in muse.ai tab in front.
 - Respect muse.ai's terms and rate limits. Internal APIs are unversioned and
   can change; if calls fail, re-derive from a fresh app bundle.
 

{muse_cli-0.2.0 → muse_cli-0.2.2}/README.md

@@ -29,27 +29,124 @@ A command-line client for your personal muse.ai AI agent: chat from the terminal
 uv tool install muse-cli      # or: pipx install muse-cli   /   pip install muse-cli
 ```
 
-Then log in and check the connection:
+The command is `muse-cli`. The name `muse` belongs to Muse Code on many machines.
+
+Want the agent skill too? The installer sets up the CLI and copies the skill
+to `~/.agents/skills/muse-cli`:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nikships/muse-cli/main/install.sh | bash
+```
+
+Upgrade with `uv tool upgrade muse-cli`, remove with `uv tool uninstall muse-cli`.
+
+Logging in is a separate one-time step. Chrome shares its cookies after you
+turn on remote debugging. Follow [Log in once](#log-in-once) before running
+any other command.
+
+## Log in once
+
+muse-cli borrows the login you already have in Chrome, saves those cookies
+to `~/.config/muse-cli/cookies.txt` (mode `600`, only your user can read it),
+and after that talks to muse.ai directly. Access tokens are fetched fresh
+on every command. When a command later says the cookies expired, repeat this
+section.
+
+Do the steps in order. Each one checks itself before you continue.
+
+### 1. Install the cookie reader
+
+`auth export` uses [agent-browser](https://github.com/vercel-labs/agent-browser)
+to read Chrome's cookies. That package comes from npm, so you need Node.js first.
+
+```bash
+node --version    # if this fails, install Node.js LTS from https://nodejs.org
+                  # and open a new terminal
+npm i -g agent-browser
+agent-browser --version
+```
+
+`npm i -g` needs permission to write to npm's global bin directory. If it
+errors with `EACCES`, pick one and use it from then on: configure an
+[npm prefix you own](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally),
+or run the install with the same rights you use for other global npm tools.
+Then check `command -v agent-browser` prints a path.
+
+### 2. Let Chrome share cookies
+
+Open **Google Chrome**, the same profile you use for muse.ai. Paste this in
+the address bar:
+
+```
+chrome://inspect/#remote-debugging
+```
+
+Turn on remote debugging. The checkbox reads **Allow remote debugging for
+this browser instance**. Leave Chrome open.
+
+Turn this on while Chrome is already open and muse.ai is loaded. The export
+can see that window only after the switch is on. The page is in Chrome 144
+and newer.
+
+Stay in this window. Starting a second Chrome with
+`--remote-debugging-port` opens a different profile, and that profile does
+not have your muse.ai login.
+
+### 3. Be logged in, on a muse.ai tab
+
+In that same Chrome window, open https://muse.ai/ and log in. Leave the tab
+open. The exporter reads whichever tab is active, so the muse.ai tab has to
+be the one in front when you run the next command.
+
+### 4. Save the login
 
 ```bash
-# 1. Log in to https://muse.ai/ in Chrome
-# 2. Export your session (one time; re-run when it expires):
 muse-cli auth export
+```
 
-muse-cli status
+Chrome may ask to allow the debugging connection. Click **Allow**. If the
+command already failed, run it again after you click Allow.
+
+Success looks like this (the count varies):
+
+```
+saved 12 muse.ai cookies to /home/you/.config/muse-cli/cookies.txt
 ```
 
-Want the agent skill too? The installer sets up the CLI and copies the skill
-to `~/.agents/skills/muse-cli`:
+The command prints the fix on the failure itself. These are the ones it
+recognizes:
+
+| What it says | What to do |
+| --- | --- |
+| No running Chrome / remote debugging | The switch in step 2 is off. Turn it on in the Chrome you already have open, then run the command again. |
+| No muse.ai tab | Step 3. Open https://muse.ai/ in that same window and leave the tab open. |
+| No `hatch_sess` | The tab is open and you are logged out. Log in, then export again. The cookies file already on disk is left as it was. |
+| `agent-browser` is not installed | Step 1. `node --version`, then `npm i -g agent-browser`, then a new terminal. |
+| Daemon already running | A previous attempt is stuck. `agent-browser close`, then `muse-cli auth export`. |
+
+### 5. Check the connection
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/nikships/muse-cli/main/install.sh | bash
+muse-cli status
 ```
 
-Upgrade with `uv tool upgrade muse-cli`, remove with `uv tool uninstall muse-cli`.
+You get JSON with your VM id, how many chats you have, the unread count, and
+your identity. That means install and login both worked.
 
-The command is `muse-cli`, not `muse`, because `muse` clashes with Muse Code
-on many machines.
+### Copy cookies by hand
+
+Use this when you don't have Node, or you don't want remote debugging on.
+
+1. In Chrome, open https://muse.ai/ and log in.
+2. Open DevTools (F12, or Ctrl+Shift+I) → **Application** → **Cookies** → `https://muse.ai`.
+3. Copy the cookies onto one line. `hatch_sess` has to be there. Separate cookies with `; ` (semicolon, space). A Netscape cookie jar (what curl writes) and a JSON object such as `{"hatch_sess": "..."}` also work.
+
+```bash
+mkdir -p ~/.config/muse-cli
+printf '%s\n' 'hatch_sess=the-value-from-devtools; other_cookie=other_value' > ~/.config/muse-cli/cookies.txt
+chmod 600 ~/.config/muse-cli/cookies.txt
+muse-cli status
+```
 
 ## Usage
 
@@ -127,12 +224,13 @@ pyproject.toml
 
 ## Setup notes
 
-- `auth export` reads cookies from a running Chrome via
-  [agent-browser](https://github.com/nikships/foundry) (`npm i -g agent-browser`).
-  No Chrome? Copy your `muse.ai` cookies into `~/.config/muse-cli/cookies.txt`
-  by hand (Netscape jar or `name=value; ...` format, needs `hatch_sess`).
-- Cookies live at `~/.config/muse-cli/cookies.txt` (mode 600). Access and
-  gateway tokens are fetched fresh on every run, nothing long-lived is stored.
+- Login is the [Log in once](#log-in-once) section above. Cookies live at
+  `~/.config/muse-cli/cookies.txt` (mode 600). Access and gateway tokens are
+  fetched fresh on every run.
+- `auth export` reads those cookies from Google Chrome through
+  [agent-browser](https://github.com/vercel-labs/agent-browser). Chrome has
+  to be open, with remote debugging on
+  (`chrome://inspect/#remote-debugging`) and a logged-in muse.ai tab in front.
 - Respect muse.ai's terms and rate limits. Internal APIs are unversioned and
   can change; if calls fail, re-derive from a fresh app bundle.
 

{muse_cli-0.2.0 → muse_cli-0.2.2}/docs/PROTOCOL.md

@@ -74,6 +74,9 @@ chat / feed / goals / ideas / sessions / ...
   delete: `{method: "/api/session/<op>", session_id}`.
 - `api.idea-cards.execute`: `{ideaCardId, mode: "full"}` plus path param.
 - POSTs to muse.ai need browser `Sec-Fetch-*` headers or they return 403.
-- `auth export` must focus a muse.ai tab before reading cookies (the export
-  follows the active tab) and must never overwrite a working jar without a
-  `hatch_sess` in the new one.
+- `auth export` reads cookies from the user's own Google Chrome through
+  agent-browser `--auto-connect`. Chrome 144+ shares that profile only after
+  remote debugging is enabled at `chrome://inspect/#remote-debugging`. The
+  export follows the active tab, so a muse.ai tab has to be focused first,
+  and it must never overwrite a working jar without a `hatch_sess` in the
+  new one. A freshly launched browser has no login; do not fall back to one.

{muse_cli-0.2.0 → muse_cli-0.2.2}/skills/muse-cli/SKILL.md

@@ -32,22 +32,96 @@ muse-cli --help >/dev/null && echo cli-ok   # proves the install + deps resolve
 
 ## 2. Auth
 
-The user must be logged in to https://muse.ai/ in Chrome first. Then:
+The CLI stores the user's muse.ai browser login at
+`~/.config/muse-cli/cookies.txt` (mode 0600). Chrome hides those cookies
+until remote debugging is on. Walk the user through the steps below and wait
+for them. Do not run `muse-cli auth export` before they say the Chrome
+switch is on and a logged-in muse.ai tab is open.
+
+Access and gateway tokens are fetched fresh on every run; only cookies
+persist. When a later command fails with `auth error`, the cookies expired:
+repeat 2b (or 2c).
+
+### 2a. Cookie reader
+
+```bash
+command -v node >/dev/null && node --version
+command -v npm >/dev/null && npm --version
+command -v agent-browser >/dev/null && agent-browser --version
+```
+
+If `agent-browser` is missing and `npm` works:
 
 ```bash
-muse-cli auth export     # saves muse.ai cookies to ~/.config/muse-cli/cookies.txt (0600)
+npm i -g agent-browser
+agent-browser --version   # must print a version
+command -v agent-browser  # must print a path
+```
+
+`EACCES` from `npm i -g` means npm cannot write its global bin directory.
+Stop and tell the user. They fix it with an npm prefix they own
+(https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)
+or by installing with the same rights they use for other global npm tools.
+Do not sudo unless they tell you to.
+
+If `node` or `npm` is missing, stop. Tell them to install Node.js LTS from
+https://nodejs.org, open a new terminal, and come back. Offer 2c if they
+would rather not install Node.
+
+### 2b. Chrome, then export
+
+Tell the user to do all of this in the Google Chrome window they already
+use for muse.ai. Needs Chrome 144 or newer. Wait until they confirm:
+
+1. Address bar: `chrome://inspect/#remote-debugging`
+2. Turn on remote debugging ("Allow remote debugging for this browser instance").
+3. Open https://muse.ai/ and log in. Leave that tab in front. The export
+   reads the active tab.
+
+Then:
+
+```bash
+muse-cli auth export
 test -s ~/.config/muse-cli/cookies.txt && echo auth-ok
 ```
 
-`auth export` pulls cookies from a running Chrome via
-[agent-browser](https://github.com/nikships/foundry) (`npm i -g agent-browser`
-if it is missing). No Chrome? Copy the `muse.ai` cookies by hand (DevTools →
-Application → Cookies; needs `hatch_sess`) into
-`~/.config/muse-cli/cookies.txt` as Netscape-jar or `name=value; ...` text.
+If Chrome shows an Allow prompt, they click Allow. If the command failed
+before that click, run it once more.
 
-Access and gateway tokens are fetched fresh on every run; only cookies
-persist. When commands later fail with `auth error`, cookies expired:
-re-run `auth export`.
+Success is a line like `saved N muse.ai cookies to ~/.config/muse-cli/cookies.txt`.
+
+If it fails, the CLI prints the next step. Map it like this, and do not retry
+in a loop:
+
+- "No running Chrome" or "remote-debugging-port": the switch in step 2 is
+  off, or they are in a different Chrome. Send them back to the steps above.
+  Do not tell them to launch Chrome with `--remote-debugging-port`. That
+  opens another profile, and it does not have their muse.ai login.
+- "no muse.ai tab": Chrome connected. They still need https://muse.ai/ open
+  and in front in that same window.
+- "no hatch_sess" / "do not include hatch_sess": the tab is open and they
+  are logged out. The cookies file on disk was kept.
+- "daemon already running": `agent-browser close`, then `muse-cli auth export` once.
+- `agent-browser` not found: back to 2a.
+
+### 2c. Copy cookies by hand
+
+Use this when Node is unavailable, or the user does not want remote debugging on.
+
+1. They are logged in at https://muse.ai/ in Chrome.
+2. DevTools (F12) → Application → Cookies → `https://muse.ai`.
+3. Write one line to `~/.config/muse-cli/cookies.txt`. `hatch_sess` is required.
+   Separate cookies with `; `:
+
+```
+hatch_sess=VALUE; other_name=other_value
+```
+
+A Netscape jar or `{"hatch_sess": "..."}` JSON also works.
+
+4. `chmod 600 ~/.config/muse-cli/cookies.txt`
+5. `test -s ~/.config/muse-cli/cookies.txt && echo auth-ok`, then `muse-cli status`.
+   Stop if status fails and report the error text.
 
 ## 3. Verify end to end
 

{muse_cli-0.2.0 → muse_cli-0.2.2}/src/muse_cli/__init__.py

@@ -1,3 +1,3 @@
 """muse-cli: talk to your personal muse.ai AI agent from the terminal."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{muse_cli-0.2.0 → muse_cli-0.2.2}/src/muse_cli/cli.py

@@ -1,14 +1,17 @@
-"""muse-cli: CLI for your personal muse.ai agent. No browser needed (after cookie export).
+"""muse-cli: CLI for your personal muse.ai agent. No browser needed after cookie export.
 
-Setup:
-  1. Log in to https://muse.ai/ in Chrome (Auth profile).
-  2. muse-cli auth export   # saves session cookies locally (chmod 600)
+One-time setup (also printed by `muse-cli auth export` when a step is missing):
+  1. npm i -g agent-browser
+  2. In Chrome, open chrome://inspect/#remote-debugging and turn remote debugging on.
+  3. Open https://muse.ai/ in that same window and log in. Leave the tab open.
+  4. muse-cli auth export   # saves session cookies locally (chmod 600)
 
 Then: muse-cli status | muse-cli threads | muse-cli history | muse-cli send "hello" | ...
 """
 import argparse
 import json
 import os
+import shutil
 import sys
 import time
 
@@ -43,8 +46,11 @@ def load_config():
 
 def connect(cfg):
     if not os.path.exists(cfg["cookies_file"]):
-        raise AuthError(f"no cookies at {cfg['cookies_file']}; log in to https://muse.ai/ "
-                        "in Chrome, then run `muse-cli auth export`")
+        raise AuthError(
+            f"no cookies at {cfg['cookies_file']}. Run `muse-cli auth export` "
+            "and follow the steps it prints: turn on Chrome remote debugging at "
+            "chrome://inspect/#remote-debugging, open https://muse.ai/ in that "
+            "window, then export again.")
     cookies = load_cookies(cfg["cookies_file"])
     if not cookies.strip():
         raise AuthError(f"cookies file {cfg['cookies_file']} is empty; run `muse-cli auth export`")
@@ -55,66 +61,175 @@ def out(obj):
     print(json.dumps(obj, indent=2, ensure_ascii=False))
 
 
+def _parse_browser_doc(stdout):
+    """agent-browser prints a JSON envelope, sometimes after a warning line."""
+    text = (stdout or "").strip()
+    if not text:
+        return None
+    blobs = [text]
+    for line in reversed(text.splitlines()):
+        line = line.strip()
+        if line.startswith("{") and line not in blobs:
+            blobs.append(line)
+    for blob in blobs:
+        try:
+            doc = json.loads(blob)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(doc, dict):
+            return doc
+    return None
+
+
 def _browser_run(argv):
-    """Run agent-browser, parsing its JSON envelope. NOTE: it exits 0 even
-    on failure, reporting {"success": false, "error": ...} on stdout."""
+    """Run agent-browser and return the JSON envelope's data.
+
+    On failure the tool prints {"success": false, "error": ...}. Some versions
+    exit 0 anyway, some exit non-zero; trust the envelope when it is there.
+    """
     import subprocess
     r = subprocess.run(argv, capture_output=True, text=True)
-    if r.returncode != 0:
-        raise RuntimeError((r.stderr or r.stdout)[:200] or f"exit {r.returncode}")
-    try:
-        doc = json.loads(r.stdout)
-    except json.JSONDecodeError:
-        raise RuntimeError((r.stdout or r.stderr)[:200] or "empty output")
+    doc = _parse_browser_doc(r.stdout) or _parse_browser_doc(r.stderr)
     if isinstance(doc, dict) and doc.get("success") is False:
-        raise RuntimeError(str(doc.get("error") or "unknown error")[:200])
+        raise RuntimeError(str(doc.get("error") or "unknown error")[:400])
+    if r.returncode != 0 or doc is None:
+        msg = (r.stderr or r.stdout or "").strip()
+        raise RuntimeError(msg[:400] or f"exit {r.returncode}")
     return doc.get("data", {}) if isinstance(doc, dict) else doc
 
 
-def _browser_cookies(headed):
-    """Read the cookie jar via agent-browser. Headed auto-connect attaches
-    to the user's real Chrome; plain mode uses a fresh browser (no login)."""
-    base = ["agent-browser"] + (["--headed", "--auto-connect"] if headed else [])
+def _export_error_kind(err):
+    e = (err or "").lower()
+    if "daemon already running" in e:
+        return "daemon"
+    if ("no running chrome" in e or "remote-debugging" in e
+            or "auto-launch failed" in e or "auto-connect" in e):
+        return "debug"
+    if err == "no muse.ai tab open in Chrome":
+        return "tab"
+    return "other"
+
+
+def _print_hand_copy():
+    print("Copy the login by hand instead:", file=sys.stderr)
+    print("  1. In Chrome, open https://muse.ai/ and log in.", file=sys.stderr)
+    print("  2. DevTools (F12) → Application → Cookies → https://muse.ai", file=sys.stderr)
+    print("  3. Write one line to ~/.config/muse-cli/cookies.txt", file=sys.stderr)
+    print("       hatch_sess=VALUE; other_name=other_value", file=sys.stderr)
+    print("     hatch_sess is required. Separate cookies with '; '.", file=sys.stderr)
+    print("  4. chmod 600 ~/.config/muse-cli/cookies.txt", file=sys.stderr)
+    print("  5. muse-cli status", file=sys.stderr)
+
+
+def _print_chrome_debug_steps():
+    print("Turn on remote debugging so muse-cli can read the muse.ai cookies.", file=sys.stderr)
+    print("Do this in the Chrome window where you already use muse.ai:", file=sys.stderr)
+    print(file=sys.stderr)
+    print("  1. Open chrome://inspect/#remote-debugging", file=sys.stderr)
+    print("  2. Turn on remote debugging", file=sys.stderr)
+    print('     ("Allow remote debugging for this browser instance").', file=sys.stderr)
+    print("  3. Open https://muse.ai/ and log in. Leave that tab open.", file=sys.stderr)
+    print("  4. Run `muse-cli auth export` again.", file=sys.stderr)
+    print("     If Chrome asks to allow the connection, click Allow.", file=sys.stderr)
+    print("     If this command already failed, run it again after Allow.", file=sys.stderr)
+    print(file=sys.stderr)
+    print("Stay in that same window. A second Chrome started with", file=sys.stderr)
+    print("--remote-debugging-port is another profile and has no muse.ai login.", file=sys.stderr)
+    print(file=sys.stderr)
+    print("Success looks like:", file=sys.stderr)
+    print(f"  saved N muse.ai cookies to {COOKIES_FILE}", file=sys.stderr)
+    print(file=sys.stderr)
+    _print_hand_copy()
+
+
+def _print_need_agent_browser():
+    print("agent-browser is not installed, so muse-cli cannot read Chrome's cookies.", file=sys.stderr)
+    print(file=sys.stderr)
+    print("  1. Install Node.js LTS if `node --version` fails: https://nodejs.org", file=sys.stderr)
+    print("  2. Open a new terminal, then:", file=sys.stderr)
+    print("       npm i -g agent-browser", file=sys.stderr)
+    print("       agent-browser --version", file=sys.stderr)
+    print("  3. Run `muse-cli auth export` again and follow the Chrome steps it prints.", file=sys.stderr)
+    print(file=sys.stderr)
+    _print_hand_copy()
+
+
+def _print_export_failure(err):
+    kind = _export_error_kind(err)
+    print("cookie export failed.", file=sys.stderr)
+    if kind == "daemon":
+        print("agent-browser is still running from an earlier attempt. Close it, then retry:", file=sys.stderr)
+        print("  agent-browser close", file=sys.stderr)
+        print("  muse-cli auth export", file=sys.stderr)
+        print(file=sys.stderr)
+        _print_chrome_debug_steps()
+        return
+    if kind == "debug":
+        _print_chrome_debug_steps()
+        return
+    if kind == "tab":
+        print("Chrome is connected, but no muse.ai tab is open.", file=sys.stderr)
+        print("Open https://muse.ai/, log in, leave that tab open, and run", file=sys.stderr)
+        print("`muse-cli auth export` again.", file=sys.stderr)
+        return
+    print(err, file=sys.stderr)
+    print(file=sys.stderr)
+    print("Check both of these, then run `muse-cli auth export` again:", file=sys.stderr)
+    print("  - chrome://inspect/#remote-debugging has remote debugging on", file=sys.stderr)
+    print("  - https://muse.ai/ is open in that same Chrome and you are logged in", file=sys.stderr)
+    print(file=sys.stderr)
+    _print_hand_copy()
+
+
+def _browser_cookies():
+    """Read muse.ai cookies from the user's Chrome via agent-browser.
+
+    Auto-connect attaches to the real profile. A fresh browser has no login,
+    so this never falls back to launching one.
+    """
+    base = ["agent-browser", "--headed", "--auto-connect"]
     last_err = "unknown error"
-    for _ in range(3):
+    for attempt in range(3):
         try:
-            if headed:
-                # Cookies follow the active tab: focus a muse.ai tab first,
-                # else the export comes back empty even when logged in.
-                data = _browser_run(base + ["tab", "list", "--json"])
-                tabs = data.get("tabs", []) if isinstance(data, dict) else []
-                muse_tabs = [t for t in tabs
-                             if isinstance(t, dict) and "muse.ai" in (t.get("url") or "")
-                             and (t.get("id") or t.get("tabId"))]
-                if not muse_tabs:
-                    return None, "no muse.ai tab open in Chrome"
-                _browser_run(base + ["tab", muse_tabs[0].get("id") or muse_tabs[0]["tabId"]])
+            # Cookies follow the active tab: focus a muse.ai tab first,
+            # else the export comes back empty even when logged in.
+            data = _browser_run(base + ["tab", "list", "--json"])
+            tabs = data.get("tabs", []) if isinstance(data, dict) else []
+            muse_tabs = [t for t in tabs
+                         if isinstance(t, dict) and "muse.ai" in (t.get("url") or "")
+                         and (t.get("id") or t.get("tabId"))]
+            if not muse_tabs:
+                return None, "no muse.ai tab open in Chrome"
+            _browser_run(base + ["tab", muse_tabs[0].get("id") or muse_tabs[0]["tabId"]])
             data = _browser_run(base + ["cookies", "get", "--json"])
             jar = data.get("cookies", []) if isinstance(data, dict) else []
             return [c for c in jar if "muse.ai" in c.get("domain", "")], None
         except RuntimeError as e:
             last_err = str(e)
+            # Missing debug port and a stuck daemon will not change on retry.
+            if _export_error_kind(last_err) in ("debug", "daemon") or attempt == 2:
+                return None, last_err
             time.sleep(2)
     return None, last_err
 
 
 def cmd_auth_export(_args):
     os.makedirs(CONFIG_DIR, exist_ok=True)
-    jar, err = _browser_cookies(headed=True)
-    if jar is None and err != "no muse.ai tab open in Chrome":
-        # Headed attach failed (no Chrome, old agent-browser, ...): a plain
-        # browser shares no login, so this is a last resort at best.
-        jar, err = _browser_cookies(headed=False)
+    if shutil.which("agent-browser") is None:
+        _print_need_agent_browser()
+        sys.exit(1)
+    print("Reading muse.ai cookies from Chrome...", file=sys.stderr)
+    jar, err = _browser_cookies()
     if jar is None:
-        print(f"cookie export failed: {err}", file=sys.stderr)
-        print("is Chrome running with muse.ai open?", file=sys.stderr)
-        print("alternative: export cookies by hand, see README Setup.", file=sys.stderr)
+        _print_export_failure(err)
         sys.exit(1)
     # Never clobber a working login with an empty or logged-out jar.
     if not any(c["name"] == "hatch_sess" for c in jar):
-        print("refusing to overwrite cookies: no hatch_sess in export "
-              "(are you logged in to muse.ai?). Existing file left intact.",
+        print("Chrome answered, but the cookies do not include hatch_sess.", file=sys.stderr)
+        print("That cookie is set only after you log in at https://muse.ai/.", file=sys.stderr)
+        print("Log in, leave the muse.ai tab open, and run `muse-cli auth export` again.",
               file=sys.stderr)
+        print(f"Left {COOKIES_FILE} unchanged.", file=sys.stderr)
         sys.exit(1)
     lines = ["# Netscape HTTP Cookie File"]
     for c in jar:
@@ -471,7 +586,32 @@ def main():
     sub = ap.add_subparsers(dest="cmd", required=True)
 
     p = sub.add_parser("auth", help="auth helpers"); a = p.add_subparsers(dest="op", required=True)
-    a.add_parser("export", help="export Chrome session cookies for the CLI").set_defaults(fn=cmd_auth_export)
+    export_help = (
+        "Copy your muse.ai login out of Google Chrome into\n"
+        "~/.config/muse-cli/cookies.txt (mode 600).\n"
+        "\n"
+        "Chrome shares those cookies only after remote debugging is on.\n"
+        "In the Chrome window you already use for muse.ai:\n"
+        "\n"
+        "  1. Open chrome://inspect/#remote-debugging\n"
+        "  2. Turn on remote debugging\n"
+        '     ("Allow remote debugging for this browser instance")\n'
+        "  3. Open https://muse.ai/ and log in. Leave that tab open.\n"
+        "  4. Run this command. If Chrome asks to allow the connection,\n"
+        "     click Allow, then run it again if it failed before the click.\n"
+        "\n"
+        "Requires agent-browser: npm i -g agent-browser\n"
+        "(install Node.js LTS from https://nodejs.org first if npm is missing).\n"
+        "\n"
+        "Stay in that same Chrome. Starting another Chrome with\n"
+        "--remote-debugging-port uses a different profile and has no muse.ai login."
+    )
+    a.add_parser(
+        "export",
+        help="copy the muse.ai login out of Chrome (remote debugging must be on)",
+        description=export_help,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    ).set_defaults(fn=cmd_auth_export)
 
     sub.add_parser("status", help="VM, session count, unread, identity").set_defaults(fn=cmd_status)
     p = sub.add_parser("threads", help="list chats and side chats")