muse-cli 0.2.0__tar.gz

muse_cli-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+build/
+
+# Local secrets and state (never commit)
+cookies.txt
+agent-cookies.json
+config.json
+*.har
+
+# OS
+.DS_Store

muse_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nik Ships
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

muse_cli-0.2.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.5
+Name: muse-cli
+Version: 0.2.0
+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
+Project-URL: Repository, https://github.com/nikships/muse-cli
+Project-URL: Issues, https://github.com/nikships/muse-cli/issues
+Project-URL: Changelog, https://github.com/nikships/muse-cli/releases
+Project-URL: Protocol Notes, https://github.com/nikships/muse-cli/blob/main/docs/PROTOCOL.md
+Author-email: Nik <mntechsurvey@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,agent-skill,ai,ai-agent,ai-assistant,automation,chat,chatbot,cli,command-line,llm,muse,muse-ai,muse-cli,muse.ai,noise-protocol,personal-ai,personal-assistant,terminal,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: curl-cffi>=0.11
+Requires-Dist: noiseprotocol>=0.3
+Requires-Dist: protobuf>=5.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# muse-cli
+
+Talk to your personal muse.ai AI agent from the terminal.
+
+[![PyPI](https://img.shields.io/pypi/v/muse-cli?style=for-the-badge)](https://pypi.org/project/muse-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/muse-cli?style=for-the-badge)](https://pypi.org/project/muse-cli/)
+[![Downloads](https://img.shields.io/pepy/dt/muse-cli?style=for-the-badge)](https://pepy.tech/project/muse-cli)
+[![License: MIT](https://img.shields.io/github/license/nikships/muse-cli?style=for-the-badge)](https://github.com/nikships/muse-cli/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/nikships/muse-cli?style=for-the-badge)](https://github.com/nikships/muse-cli/stargazers)
+
+![muse-cli hero](https://raw.githubusercontent.com/nikships/muse-cli/main/assets/hero.webp)
+
+</div>
+
+## What is this?
+
+A command-line client for your personal muse.ai AI agent: chat from the terminal, automate it with scripts, and manage side chats, feed, goals, ideas, and sessions without opening a browser. It speaks the app's own gateway protocol directly: HTTPS auth, then an encrypted Noise-XX WebSocket to your personal VM.
+
+- **Chat from the shell:** send a message and get the agent's reply back as JSON.
+- **Script it:** every command prints JSON, so it pipes into `jq`, cron jobs, and other AI agents.
+- **Full coverage:** named commands for the common tasks, plus a `raw` escape hatch for all 258 gateway methods.
+- **Agent-ready:** ships an agent skill so coding agents can drive your muse.ai agent for you.
+
+## Quick Start
+
+```bash
+uv tool install muse-cli      # or: pipx install muse-cli   /   pip install muse-cli
+```
+
+Then log in and check the connection:
+
+```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
+```
+
+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`.
+
+The command is `muse-cli`, not `muse`, because `muse` clashes with Muse Code
+on many machines.
+
+## Usage
+
+```bash
+muse-cli threads                                  # main chat + side chats
+muse-cli history --limit 5                        # recent messages
+muse-cli history --thread <session-id> --limit 5  # one side chat
+muse-cli send "summarize my unread" --wait 120    # send + wait for the reply
+muse-cli watch --timeout 60                       # tail live agent events
+
+muse-cli feed --limit 5
+muse-cli feed-react <unit-id> love
+muse-cli goals
+muse-cli ideas
+muse-cli idea-exec <idea-id>                      # agent acts on the idea
+
+muse-cli session-start --title "trip planning"    # new side chat
+muse-cli session-rename <id> "new title"
+muse-cli session-archive <id>                     # also: pin, unpin, unarchive, delete
+muse-cli seen <thread-id>
+muse-cli wake
+muse-cli raw <method> --body '{}'                 # escape hatch: any of 258 gateway methods
+```
+
+Every command prints JSON. Your VM is auto-discovered from your session, and a
+random device id is generated on first run.
+
+Pipe it into other tools:
+
+```bash
+muse-cli send "what's on my calendar today?" | jq -r .reply.text
+```
+
+## How it works
+
+![how muse-cli connects](https://raw.githubusercontent.com/nikships/muse-cli/main/assets/how-it-works.webp)
+
+![muse-cli connection flow](https://raw.githubusercontent.com/nikships/muse-cli/main/assets/flow.webp)
+
+See [docs/PROTOCOL.md](https://github.com/nikships/muse-cli/blob/main/docs/PROTOCOL.md)
+for the full protocol notes, including the method table and the server quirks
+found during reverse engineering.
+
+## Documentation
+
+| Resource | Description |
+|----------|-------------|
+| [skills/muse-cli/SKILL.md](https://github.com/nikships/muse-cli/blob/main/skills/muse-cli/SKILL.md) | Agent skill: install check, auth setup, command reference |
+| [docs/PROTOCOL.md](https://github.com/nikships/muse-cli/blob/main/docs/PROTOCOL.md) | Gateway protocol reference: auth chain, Noise transport, framing, method quirks |
+| [routes.json](https://github.com/nikships/muse-cli/blob/main/src/muse_cli/routes.json) | All 258 gateway methods with paths and services |
+| `muse-cli raw --help` | Escape hatch for calling any gateway method directly |
+
+## Development
+
+```bash
+git clone https://github.com/nikships/muse-cli.git
+cd muse-cli
+uv run muse-cli --help
+```
+
+```
+muse-cli/
+assets/              README artwork (generated with Muse Image)
+docs/PROTOCOL.md     protocol reference for re-derivation
+skills/muse-cli/     agent skill
+src/muse_cli/
+  cli.py             argument parsing and all commands
+  gateway.py         gateway client (auth, Noise transport, subscriptions)
+  routes.json        258 gateway methods extracted from the web client
+  desc0.bin          protobuf descriptors for the wire framing
+  desc1.bin
+install.sh           CLI + skill installer
+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.
+- 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.
+
+## Contributing
+
+Issues and PRs welcome. If the protocol drifts, the most useful contribution
+is a note of which method broke and the new server error text.
+
+<a href="https://github.com/nikships/muse-cli/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=nikships/muse-cli" />
+</a>
+
+## License
+
+MIT. See [LICENSE](https://github.com/nikships/muse-cli/blob/main/LICENSE).
+
+---
+
+<div align="center">
+
+[![Star History Chart](https://api.star-history.com/svg?repos=nikships/muse-cli&type=Date)](https://star-history.com/#nikships/muse-cli&Date)
+
+</div>

muse_cli-0.2.0/README.md

@@ -0,0 +1,158 @@
+<div align="center">
+
+# muse-cli
+
+Talk to your personal muse.ai AI agent from the terminal.
+
+[![PyPI](https://img.shields.io/pypi/v/muse-cli?style=for-the-badge)](https://pypi.org/project/muse-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/muse-cli?style=for-the-badge)](https://pypi.org/project/muse-cli/)
+[![Downloads](https://img.shields.io/pepy/dt/muse-cli?style=for-the-badge)](https://pepy.tech/project/muse-cli)
+[![License: MIT](https://img.shields.io/github/license/nikships/muse-cli?style=for-the-badge)](https://github.com/nikships/muse-cli/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/nikships/muse-cli?style=for-the-badge)](https://github.com/nikships/muse-cli/stargazers)
+
+![muse-cli hero](https://raw.githubusercontent.com/nikships/muse-cli/main/assets/hero.webp)
+
+</div>
+
+## What is this?
+
+A command-line client for your personal muse.ai AI agent: chat from the terminal, automate it with scripts, and manage side chats, feed, goals, ideas, and sessions without opening a browser. It speaks the app's own gateway protocol directly: HTTPS auth, then an encrypted Noise-XX WebSocket to your personal VM.
+
+- **Chat from the shell:** send a message and get the agent's reply back as JSON.
+- **Script it:** every command prints JSON, so it pipes into `jq`, cron jobs, and other AI agents.
+- **Full coverage:** named commands for the common tasks, plus a `raw` escape hatch for all 258 gateway methods.
+- **Agent-ready:** ships an agent skill so coding agents can drive your muse.ai agent for you.
+
+## Quick Start
+
+```bash
+uv tool install muse-cli      # or: pipx install muse-cli   /   pip install muse-cli
+```
+
+Then log in and check the connection:
+
+```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
+```
+
+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`.
+
+The command is `muse-cli`, not `muse`, because `muse` clashes with Muse Code
+on many machines.
+
+## Usage
+
+```bash
+muse-cli threads                                  # main chat + side chats
+muse-cli history --limit 5                        # recent messages
+muse-cli history --thread <session-id> --limit 5  # one side chat
+muse-cli send "summarize my unread" --wait 120    # send + wait for the reply
+muse-cli watch --timeout 60                       # tail live agent events
+
+muse-cli feed --limit 5
+muse-cli feed-react <unit-id> love
+muse-cli goals
+muse-cli ideas
+muse-cli idea-exec <idea-id>                      # agent acts on the idea
+
+muse-cli session-start --title "trip planning"    # new side chat
+muse-cli session-rename <id> "new title"
+muse-cli session-archive <id>                     # also: pin, unpin, unarchive, delete
+muse-cli seen <thread-id>
+muse-cli wake
+muse-cli raw <method> --body '{}'                 # escape hatch: any of 258 gateway methods
+```
+
+Every command prints JSON. Your VM is auto-discovered from your session, and a
+random device id is generated on first run.
+
+Pipe it into other tools:
+
+```bash
+muse-cli send "what's on my calendar today?" | jq -r .reply.text
+```
+
+## How it works
+
+![how muse-cli connects](https://raw.githubusercontent.com/nikships/muse-cli/main/assets/how-it-works.webp)
+
+![muse-cli connection flow](https://raw.githubusercontent.com/nikships/muse-cli/main/assets/flow.webp)
+
+See [docs/PROTOCOL.md](https://github.com/nikships/muse-cli/blob/main/docs/PROTOCOL.md)
+for the full protocol notes, including the method table and the server quirks
+found during reverse engineering.
+
+## Documentation
+
+| Resource | Description |
+|----------|-------------|
+| [skills/muse-cli/SKILL.md](https://github.com/nikships/muse-cli/blob/main/skills/muse-cli/SKILL.md) | Agent skill: install check, auth setup, command reference |
+| [docs/PROTOCOL.md](https://github.com/nikships/muse-cli/blob/main/docs/PROTOCOL.md) | Gateway protocol reference: auth chain, Noise transport, framing, method quirks |
+| [routes.json](https://github.com/nikships/muse-cli/blob/main/src/muse_cli/routes.json) | All 258 gateway methods with paths and services |
+| `muse-cli raw --help` | Escape hatch for calling any gateway method directly |
+
+## Development
+
+```bash
+git clone https://github.com/nikships/muse-cli.git
+cd muse-cli
+uv run muse-cli --help
+```
+
+```
+muse-cli/
+assets/              README artwork (generated with Muse Image)
+docs/PROTOCOL.md     protocol reference for re-derivation
+skills/muse-cli/     agent skill
+src/muse_cli/
+  cli.py             argument parsing and all commands
+  gateway.py         gateway client (auth, Noise transport, subscriptions)
+  routes.json        258 gateway methods extracted from the web client
+  desc0.bin          protobuf descriptors for the wire framing
+  desc1.bin
+install.sh           CLI + skill installer
+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.
+- 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.
+
+## Contributing
+
+Issues and PRs welcome. If the protocol drifts, the most useful contribution
+is a note of which method broke and the new server error text.
+
+<a href="https://github.com/nikships/muse-cli/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=nikships/muse-cli" />
+</a>
+
+## License
+
+MIT. See [LICENSE](https://github.com/nikships/muse-cli/blob/main/LICENSE).
+
+---
+
+<div align="center">
+
+[![Star History Chart](https://api.star-history.com/svg?repos=nikships/muse-cli&type=Date)](https://star-history.com/#nikships/muse-cli&Date)
+
+</div>

muse_cli-0.2.0/docs/PROTOCOL.md

@@ -0,0 +1,79 @@
+# Protocol notes
+
+How `muse` talks to the muse.ai personal gateway. Derived from the web app's
+own client bundle and verified live. Internal APIs are unversioned and can
+change without notice; if calls start failing, re-derive from a fresh bundle
+(HAR capture + the `derive-client` workflow).
+
+## Layers
+
+```
+muse CLI
+  │  HTTPS (browser TLS fingerprint via curl-impersonated requests)
+  ▼
+muse.ai            cookies → POST /api/auth/check → access_token
+                   POST /api/hatch/token {vmAddress, vmName} → hatch token
+                   GET /api/session → assigned VM id (auto-discovered)
+  │  wss://hatch.metaaivm.com/v1/noise?vm_id=..&auth_token=..
+  │  Noise_XX_25519_AESGCM_SHA256, empty payloads both ways
+  ▼
+personal VM gateway
+  │  protobuf envelopes (descriptors in desc0.bin / desc1.bin)
+  │  request/response + newline-JSON event subscriptions
+  ▼
+chat / feed / goals / ideas / sessions / ...
+```
+
+## Details
+
+- **Gateway host:** the shared `hatch.metaaivm.com`, not the per-VM hostname.
+  Plain TLS to the per-VM host is reset at the edge; a Chrome fingerprint
+  (curl_cffi `impersonate="chrome"`) is required.
+- **Handshake:** standard Noise XX. This account negotiates standard mode
+  (empty msg3). An attested/RV mode with SNP attestation and HMAC proofs
+  exists in the client for other configurations.
+- **Framing:** `NoiseTransportFrame{chunk_id(i64), chunk_index, total_chunks,
+  payload}` protobuf → Noise transport encrypt → one WS binary frame each.
+- **Request:** `ServiceRequest{service, payload =
+  ServiceFrame{stream_id, request =
+  ApplicationRequest{verb, path, headers, body, end_body}}}`. Stream ids start
+  at 1. Services: daemon 0, sentinel 1, vault 2, authd 3.
+- **Response:** `ServiceResponse{payload = ServiceFrame{... response =
+  ApplicationResponse{status, headers, body, end_body}}}` plus `body_chunk`
+  frames until `end_body`.
+- **Subscriptions** (`chat.subscribe`, `chat.stream`, ...): same envelope, the
+  server streams `application/x-ndjson` records in body chunks.
+- **Method table:** `routes.json` (258 methods extracted from the web bundle).
+
+## Server quirks learned from live errors
+
+- `chat.history`: GET query params only; `transcript_mode` is rejected, omit
+  it; `session_id` scopes to a side chat; `limit` works. History events use
+  `event_name` (`message.user` / `message.assistant`), carry the text in both
+  top-level and `payload.display_text`, and are the source of truth.
+- Genuine assistant replies have an **empty `reply_to_message_id`**; proactive
+  pushes (Telegram drafts, background task updates) are self-referential
+  there. That is how `send` tells a reply apart from background chatter.
+- Live `chat.subscribe` events use **different shapes** (`delta.text_append`
+  with `message_seq` + text chunks, `delta.message_done` with the full
+  transcript) and only cover main-chat traffic: threaded replies never arrive
+  as live events, just a `sessions.updated` snippet. `send` therefore polls
+  history instead of watching the stream. The `chat.stream` response stream
+  itself carries only the send echo, then ends.
+- `/api/session` can return 200 `{"status":"unavailable",
+  "vm_resolution_issue":{"kind":"retryable"}}` while the VM restarts. The
+  client raises a clean error (not KeyError); retry, or wake a known VM id
+  via `MUSE_VM_ID=<id> muse-cli wake`.
+- Concurrent `_read_frame` calls from two threads split frames and corrupt
+  the stateful Noise decrypt (fatal BAD_DECRYPT). `Gateway` serializes
+  receives with a lock as a backstop, but callers must still keep exactly
+  one frame consumer at a time (`send` makes sequential unary calls only).
+- `session.start`: `{method: "/api/session/start", params: {origin: "fresh",
+  lifecycle: "persistent", title?}}`.
+- `session.rename`: flat `{session_id, title}`. pin/unpin/archive/unarchive/
+  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.

muse_cli-0.2.0/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "muse-cli"
+dynamic = ["version"]
+description = "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."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Nik", email = "mntechsurvey@gmail.com" }]
+keywords = [
+    "muse",
+    "muse.ai",
+    "muse-ai",
+    "muse-cli",
+    "ai",
+    "ai-agent",
+    "ai-assistant",
+    "personal-ai",
+    "personal-assistant",
+    "agent",
+    "chatbot",
+    "chat",
+    "llm",
+    "cli",
+    "terminal",
+    "command-line",
+    "automation",
+    "agent-skill",
+    "noise-protocol",
+    "websocket",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Communications :: Chat",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Terminals",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "curl_cffi>=0.11",
+    "noiseprotocol>=0.3",
+    "protobuf>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/nikships/muse-cli"
+Documentation = "https://github.com/nikships/muse-cli#readme"
+Repository = "https://github.com/nikships/muse-cli"
+Issues = "https://github.com/nikships/muse-cli/issues"
+Changelog = "https://github.com/nikships/muse-cli/releases"
+"Protocol Notes" = "https://github.com/nikships/muse-cli/blob/main/docs/PROTOCOL.md"
+
+[project.scripts]
+muse-cli = "muse_cli.cli:main"
+
+[tool.hatch.version]
+path = "src/muse_cli/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/muse_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/muse_cli",
+    "docs",
+    "skills",
+    "README.md",
+    "LICENSE",
+]

muse_cli-0.2.0/skills/muse-cli/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: muse-cli
+description: Manage a personal muse.ai agent from the terminal (send messages, read chats, watch live events, feed/goals/ideas/sessions). Use when asked to message, check, or automate someone's Muse personal AI, work with muse.ai chats/threads/feed/goals outside the browser, or when the muse-cli tool itself needs installing or auth setup.
+---
+
+# muse-cli: drive a muse.ai personal agent from the terminal
+
+Assume a bare machine: only this skill is present. No repo clone, no
+dependencies, no auth. Work top to bottom; stop at the first step that
+fails and report it.
+
+The `muse-cli` package (on PyPI) talks to the muse.ai personal gateway
+directly. No browser needed after the one-time cookie export. Every command
+prints JSON.
+
+## 1. Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nikships/muse-cli/main/install.sh | bash
+```
+
+This installs the CLI from PyPI with `uv tool install muse-cli` (its own
+isolated environment) and this skill (to `~/.agents/skills/muse-cli`). CLI
+only? `uv tool install muse-cli`, `pipx install muse-cli`, or
+`pip install muse-cli` all work. The command is `muse-cli` (`muse` clashes
+with Muse Code, don't use it). Verify before continuing:
+
+```bash
+command -v muse-cli
+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:
+
+```bash
+muse-cli auth export     # saves muse.ai cookies to ~/.config/muse-cli/cookies.txt (0600)
+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.
+
+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`.
+
+## 3. Verify end to end
+
+```bash
+muse-cli status    # VM id, chat count, unread, identity: install + auth proven
+```
+
+## Everyday commands
+
+```bash
+muse-cli threads                                        # main chat + side chats (session_ids)
+muse-cli history --limit 5                              # recent main-chat messages
+muse-cli history --thread <session-id> --limit 5        # one side chat
+muse-cli send "message" --wait 120                      # send + wait for the reply
+muse-cli send "message" --thread <session-id> --wait 0  # fire and forget to a side chat
+muse-cli watch --timeout 60                             # tail live agent events
+muse-cli feed --limit 5
+muse-cli goals
+muse-cli ideas
+muse-cli unread
+muse-cli seen <thread-id>
+```
+
+Management (visible side effects, confirm with the user first when destructive):
+
+```bash
+muse-cli feed-react <unit-id> love
+muse-cli idea-exec <idea-id>          # the agent acts on the idea (real work)
+muse-cli session-start --title "x"    # new side chat
+muse-cli session-rename <id> "title"  # also: pin, unpin, archive, unarchive, delete
+muse-cli wake
+```
+
+## Escape hatch
+
+`muse-cli raw <method> --body '{...}' [--param k=v]` calls any of the 258
+gateway methods in `routes.json`. Prefer the named commands above; use raw
+only for methods with no wrapper.
+
+## Gotchas
+
+- `send` returns `{"sent": true, "reply": {...}}`, polling history until the
+  reply lands (up to `--wait`). If `reply` is missing, the agent was slower
+  than the wait: the message still landed, confirm with `history`. The reply
+  is matched as a genuine answer, not background chatter.
+- `send --wait 0` is fire-and-forget (no polling).
+- `history` without `--thread` reads the main chat only.
+- The gateway API is unversioned. Whole classes of calls failing at once means
+  the protocol drifted: see `docs/PROTOCOL.md` for the re-derivation notes,
+  don't guess at crypto or framing.
+- Respect rate limits. Writes (send, react, execute, session ops) act as the
+  user in their agent: announce them before running, never loop them.

muse_cli-0.2.0/src/muse_cli/__init__.py

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

muse_cli-0.2.0/src/muse_cli/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()