Skip to content

Commit 4d5966a

Browse files
buzhidaosmbuzhidaosm
committed
Release original Muse CLI and Codex/Claude task bridge v0.3.0
0 parents  commit 4d5966a

51 files changed

Lines changed: 4071 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Compatibility or bug report
2+
description: Report a reproducible issue without account secrets.
3+
title: "[Bug] "
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: "Do not include cookies, authorization headers, HAR files, credentials or private chats."
8+
- type: input
9+
id: version
10+
attributes:
11+
label: Muse Bridge version
12+
validations:
13+
required: true
14+
- type: textarea
15+
id: reproduction
16+
attributes:
17+
label: Redacted steps and observed behavior
18+
validations:
19+
required: true
20+
- type: textarea
21+
id: expected
22+
attributes:
23+
label: Expected behavior
24+
- type: textarea
25+
id: environment
26+
attributes:
27+
label: macOS, Python, Codex/Claude versions and safe error codes

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: Security boundaries
4+
url: https://github.com/buzhidaosm/muse-cli-bridge/blob/main/SECURITY.md
5+
about: Read the boundary and reporting guidance before sharing sensitive details.

‎.gitignore‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.venv/
2+
__pycache__/
3+
.pytest_cache/
4+
.ruff_cache/
5+
dist/
6+
*.egg-info/
7+
*.log
8+
*.cookies
9+
.env
10+
.DS_Store
11+
*.sqlite*
12+
*.db
13+
*.har
14+
.env.*
15+
*.key
16+
*.pem

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Changelog
2+
3+
## 0.3.0 — first public release
4+
5+
- Explicit local project authorization for new relay setups.
6+
- Separate write-mode opt-in, checked again before execution.
7+
- Independently implemented Muse CLI, Keychain login and seven read-only MCP tools.
8+
- Bidirectional Muse-chat task relay for Codex and Claude Code on macOS.
9+
- Durable task ids, interrupted-job recovery, process-group deadlines and ambiguous send handling.
10+
- Known NON_TEE key-binding payload support; confidential/unknown payloads remain refused.
11+
- English/Chinese quick starts, boundary documentation and reproducible validation material.
12+
13+
## Private development history
14+
15+
0.2.0 introduced the relay and verified both live agent roundtrips and disposable project edits. 0.1.1 fixed a mistaken rejection of every nonempty handshake payload. 0.1.0 established the independent client and local tests. These internal iterations were not public releases.

‎CONTRIBUTING.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Contributing
2+
3+
The highest-value contribution is a reproducible, redacted compatibility report or a focused fix with a meaningful test.
4+
5+
```bash
6+
uv sync --no-editable --group dev
7+
uv run --no-editable pytest -q
8+
uv run --no-editable ruff check src tests
9+
uv build
10+
```
11+
12+
Automated tests must not require account credentials. OS-specific tests can skip when their platform is unavailable. Live tests must be opt-in and use disposable projects, never an existing user's source or private data.
13+
14+
Do not add generated wire descriptors or copied client implementations. Cite protocol facts, standards and dependencies in PROVENANCE.md. Do not overstate safety, supported platforms, compatibility or release validation.
15+
16+
Keep changes small enough to review. Describe the concrete behavior, reproduction and validation. If your change affects sends, retries, job recovery, process termination, authentication or permissions, include tests for the failure path.
17+
18+
Respect other people and their work. No spam, star trading, fake users or unsupported claims about competitors.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Muse Bridge contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎PROVENANCE.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Provenance — 2026-10-08
2+
3+
## Independently authored implementation
4+
5+
All files under `src/musebridge` and `tests` were written for this project. No fork, vendored `muse_cli` module, descriptor `.bin`, or copied 258-method table is included. There is no dependency on `muse-cli` or `agent-browser`.
6+
7+
## Interoperability references
8+
9+
- Muse's public webpage and JavaScript assets were inspected at `https://muse.ai/` on 2026-10-08. Those assets are outside the deliverable and are not redistributed.
10+
- https://github.com/nikships/muse-cli/blob/main/docs/PROTOCOL.md was consulted for authentication endpoints, standard Noise XX parameters, framing and documented failure modes.
11+
- The reference client's protocol descriptors were decoded during research to learn factual field numbers, types and service identifiers. The source was also consulted to resolve the gateway-token `vmAddress` format. No descriptor data or implementation was copied into this package.
12+
- Seven endpoint paths were recorded as interoperability facts; they are not a copy of the reference's route table.
13+
- https://protobuf.dev/programming-guides/encoding/ describes the standard varint and length-delimited encoding used by the original codec.
14+
- https://noiseprotocol.org/noise.html defines the handshake implemented by the third-party `noiseprotocol` package.
15+
- https://modelcontextprotocol.io/specification/2025-03-26/basic/transports describes stdio JSON-RPC framing.
16+
17+
This is independently written code informed by public protocol research, **not** a clean-room implementation. Naming, architecture, source and tests are new. The project does not claim ownership of Muse's service, APIs, trademarks or the underlying standards.
18+
19+
## Third-party dependencies
20+
21+
Standard third-party libraries handle TLS/browser fingerprinting (`curl-cffi`), Noise and cryptography (`noiseprotocol`, `cryptography`), Keychain access (`keyring`), and dedicated browser login (`playwright`). Dependency licenses remain their own. The versions tested are recorded in `uv.lock`; the package declarations are in `pyproject.toml`.
22+
23+
## v0.1.1 protocol correction
24+
25+
On 2026-10-08 an authenticated live handshake returned an `AttestationBundle` for the `NON_TEE` platform, containing `ReportDataInput.x25519_public_key`. The key matched the public key authenticated by the Noise message-2 exchange. The vendor's public JavaScript assets, including `/_next/static/chunks/1yednwfd38pyt.js`, expose the names and wire fields of `attestation_bundle.proto`; these schema facts were checked to distinguish ordinary public-key binding from AMD SEV-SNP evidence and recovery-key challenges.
26+
27+
The new `trust.py` is independently written: it accepts only the known NON_TEE envelope, verifies key equality, and refuses additional evidence, confidential-platform labels, duplicate/unknown fields, and mismatches. No vendor JavaScript or descriptor bytes are included in the deliverable. Research printed only payload structure, types, lengths, and a boolean key comparison, never credential values or actual private conversation content.
28+
29+
## v0.2.0 task bridge
30+
31+
The relay, SQLite job store, executor adapters, CLI management and tests are independently authored. The bridge uses its already implemented Muse chat transport, standard Python process/SQLite APIs, macOS Seatbelt, and installed Codex/Claude CLIs. Runtime command flags were checked against local CLI help and official documentation: https://developers.openai.com/blog/codex-as-a-platform and https://code.claude.com/docs/en/headless. Claude shell-sandbox scope and its limits were checked at https://code.claude.com/docs/en/sandboxing. No third-party relay implementation was copied or embedded.

‎README.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Muse Bridge — Muse CLI for Codex & Claude Code
2+
3+
**Give your muse.ai personal agent a path to your local coding tools.**
4+
5+
Muse Bridge is an independent, open-source **Muse CLI** for macOS. Read chats, goals and ideas from the terminal, expose read-only MCP tools, or let Muse request a bounded Codex / Claude Code task and get the result back in the same chat.
6+
7+
![Muse Bridge: Muse to your Mac to Codex or Claude Code and back](assets/hero.svg)
8+
9+
[Quick start](#quick-start) · [中文说明](README.zh-CN.md) · [Task bridge](TASK_BRIDGE.md) · [Validation](VALIDATION.md) · [Security boundaries](SECURITY.md) · [Protocol provenance](PROVENANCE.md)
10+
11+
> **macOS / Python 3.11+ / experimental internal API.** This connects the muse.ai personal agent. It is not the official Muse Code CLI and is not affiliated with Meta, OpenAI or Anthropic.
12+
13+
## What you can do
14+
15+
| Workflow | Example |
16+
|---|---|
17+
| Read Muse from a terminal | `muse-bridge history --limit 5` |
18+
| Query goals, ideas and feed | `muse-bridge goals` / `ideas` / `feed` |
19+
| Send a message deliberately | `muse-bridge send "Hello" --allow-write` |
20+
| Let an MCP client read Muse | `muse-bridge mcp` |
21+
| Let Muse ask Codex or Claude to work | `muse-bridge bridge start --background` |
22+
| Check or stop the relay | `muse-bridge bridge status` / `bridge stop` |
23+
24+
The task bridge is **bidirectional**:
25+
26+
```text
27+
You ask Muse for a local task
28+
↓
29+
Muse emits a structured request in its chat
30+
↓
31+
Your Mac polls that chat → Codex or Claude Code CLI
32+
↓
33+
A bounded final result returns to the same Muse chat
34+
```
35+
36+
No public inbound port, reverse tunnel or remote shell endpoint is required. The Mac must stay awake, connected and running the relay.
37+
38+
## Quick start
39+
40+
Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.11 or later. Install and sign in to Codex and/or Claude Code if you want the task bridge. Google Chrome in `/Applications` is used for a dedicated manual Muse login.
41+
42+
From the GitHub release:
43+
44+
```bash
45+
uv tool install https://github.com/buzhidaosm/muse-cli-bridge/releases/download/v0.3.0/muse_bridge_cli-0.3.0-py3-none-any.whl
46+
muse-bridge doctor
47+
muse-bridge login
48+
muse-bridge identity
49+
```
50+
51+
Or install from source:
52+
53+
```bash
54+
git clone https://github.com/buzhidaosm/muse-cli-bridge.git
55+
cd muse-cli-bridge
56+
uv tool install .
57+
```
58+
59+
`login` opens a separate, temporary Chrome window. Complete your login yourself. A validated session is stored in the **macOS Keychain**; your existing browser profile is not read. Do not paste passwords, cookies or bearer tokens into issues. A manual cookie import fallback is described in [authentication](docs/authentication.md).
60+
61+
### Let Muse use a project
62+
63+
Authorize one project locally first. Start in read mode:
64+
65+
```bash
66+
muse-bridge bridge init --project /absolute/path/to/your/project
67+
muse-bridge bridge start --background
68+
muse-bridge bridge notify
69+
```
70+
71+
`notify` sends the protocol instructions to Muse. In **that same Muse chat**, ask:
72+
73+
> Use Codex to review `/absolute/path/to/your/project` through Muse Bridge. Don't change files. Wait for the local result before summarizing it.
74+
75+
To allow edits, stop the relay and explicitly opt in:
76+
77+
```bash
78+
muse-bridge bridge stop
79+
muse-bridge bridge init --project /absolute/path/to/your/project --allow-write
80+
muse-bridge bridge start --background
81+
muse-bridge bridge notify
82+
```
83+
84+
Repeat `--project` to authorize additional projects. `--all-projects` is a separate, explicit broad-access option. See [the task guide](TASK_BRIDGE.md) before enabling it. Project selection and write permission are checked again immediately before a queued task executes.
85+
86+
## Terminal commands
87+
88+
```bash
89+
muse-bridge status # HTTPS login + VM assignment; not a gateway test
90+
muse-bridge identity # authenticated gateway query
91+
muse-bridge threads
92+
muse-bridge history --limit 10
93+
muse-bridge history --thread SESSION_ID --limit 10
94+
muse-bridge goals
95+
muse-bridge ideas
96+
muse-bridge feed --limit 10
97+
muse-bridge send "Hello" --allow-write --timeout 60
98+
muse-bridge bridge status
99+
muse-bridge bridge job TASK_ID
100+
muse-bridge bridge stop
101+
muse-bridge logout # remove local credentials; does not revoke server session
102+
```
103+
104+
Normal CLI commands return one JSON object. Help/version output is plain text. `mcp` uses stdio JSON-RPC. Sends and local agent tasks are not automatically retried; an ambiguous delivery is reported as `unknown` instead of claimed as success.
105+
106+
## MCP integration
107+
108+
The MCP server exposes seven **read-only** tools: status, identity, threads, history, goals, ideas and feed. It does not expose sending or local execution.
109+
110+
```json
111+
{
112+
"mcpServers": {
113+
"muse-bridge": {
114+
"command": "/absolute/path/to/muse-bridge",
115+
"args": ["mcp"]
116+
}
117+
}
118+
}
119+
```
120+
121+
`command -v muse-bridge` gives the executable path. Authenticated responses are external data, not instructions for the calling agent.
122+
123+
## Tested, with limits
124+
125+
Real-account validation confirmed both directions for Codex and Claude Code: Muse produced task requests, the local agents returned the expected result, and the returned result was independently found in Muse history. Both agents also edited separate disposable test projects, and their final file contents were checked. See [the dated validation record](VALIDATION.md) and [sanitized example evidence](examples/verified-roundtrips.json).
126+
127+
![Sanitized replay of a verified Muse Bridge roundtrip](assets/roundtrip.gif)
128+
129+
*This is a replay of verified test events with paths and identifiers replaced, not an unedited recording or a fabricated conversation.*
130+
131+
The OS boundary limits **writes**, not all reads or network access. Runtime state and temporary directories are additionally writable. This is not a general computer-use sandbox. Do not use tasks for credentials or data you do not want to send to AI services. [Read the full boundary](SECURITY.md).
132+
133+
Current limits:
134+
135+
- macOS only; standard NON_TEE / legacy Noise handshakes only.
136+
- No desktop clicking or injection into an existing Codex/Claude desktop conversation.
137+
- One selected Muse chat, sequential jobs, no automatic login/startup service.
138+
- No claim that a completed agent process proves an arbitrary task was solved.
139+
- Internal Muse endpoints can change; no official OAuth integration or API stability guarantee.
140+
141+
## Development
142+
143+
```bash
144+
uv sync --no-editable --group dev
145+
uv run --no-editable pytest -q
146+
uv run --no-editable ruff check src tests
147+
uv build
148+
```
149+
150+
After editing source, reinstall the local noneditable package when testing CLI behavior: `uv sync --no-editable --reinstall-package muse-bridge-cli`. Tests import the current `src/` tree directly. Automated tests never require a Muse account; live smoke tests are opt-in.
151+
152+
## Original implementation and contributions
153+
154+
The code, wire codec, relay, executor adapters and tests were independently written. Research consulted public protocol notes and descriptor fields from another client, with attribution in [PROVENANCE.md](PROVENANCE.md). This is not claimed to be a clean-room implementation, and it does not depend on or vendor that client's source.
155+
156+
Useful contributions include reproducible compatibility reports, redacted failure cases, tests and onboarding improvements. Start with [CONTRIBUTING.md](CONTRIBUTING.md). If this makes your workflow easier, a GitHub star helps other developers discover it. Please don't star-swap or buy engagement.
157+
158+
MIT licensed. Canonical repository: [buzhidaosm/muse-cli-bridge](https://github.com/buzhidaosm/muse-cli-bridge).

‎README.zh-CN.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Muse Bridge — 连接 Muse、Codex 和 Claude Code 的 CLI
2+
3+
让 muse.ai 个人助手向你的 Mac 提交项目任务，本机调用 Codex 或 Claude Code，再把结果传回同一个 Muse 聊天。也支持读取 Muse 数据和只读 MCP。
4+
5+
这是独立编写的开源工具，面向 macOS / Python 3.11+。不是官方 Muse Code CLI，也不属于 Meta、OpenAI 或 Anthropic。
6+
7+
## 安装和登录
8+
9+
```bash
10+
uv tool install https://github.com/buzhidaosm/muse-cli-bridge/releases/download/v0.3.0/muse_bridge_cli-0.3.0-py3-none-any.whl
11+
muse-bridge doctor
12+
muse-bridge login
13+
muse-bridge identity
14+
```
15+
16+
登录在独立临时 Chrome 窗口中由你完成，验证后保存在 macOS 钥匙串，不读取原有浏览器配置。Mac 需要安装 Google Chrome。
17+
18+
## 把一个项目交给 Muse
19+
20+
```bash
21+
muse-bridge bridge init --project /你的项目绝对路径
22+
muse-bridge bridge start --background
23+
muse-bridge bridge notify
24+
```
25+
26+
在收到说明的同一个 Muse 聊天里说：
27+
28+
> 用 Codex 只读审阅 `/我的项目绝对路径`，通过 Muse Bridge 交给本机执行，等返回结果后再总结。
29+
30+
允许修改，需要明确启用：
31+
32+
```bash
33+
muse-bridge bridge stop
34+
muse-bridge bridge init --project /你的项目绝对路径 --allow-write
35+
muse-bridge bridge start --background
36+
muse-bridge bridge notify
37+
```
38+
39+
可以重复 `--project` 授权多个项目；`--all-projects` 是单独的全项目选项，不是默认权限。Mac 保持开机联网即可，不需要开放公共端口。
40+
41+
## 常用命令
42+
43+
```bash
44+
muse-bridge history --limit 5
45+
muse-bridge threads
46+
muse-bridge goals
47+
muse-bridge ideas
48+
muse-bridge feed --limit 10
49+
muse-bridge send '你好' --allow-write
50+
muse-bridge mcp
51+
muse-bridge bridge status
52+
muse-bridge bridge job TASK_ID
53+
muse-bridge bridge stop
54+
```
55+
56+
任务 id 去重、持久化状态、进程组超时和不确定投递状态均已实现。重启不自动重跑中断任务。完整流程已用真实账号验证，也验证了两个助手修改独立测试项目的实际内容。
57+
58+
## 真实边界
59+
60+
文件写入受到 macOS OS 沙箱限制，但不是完整的读取或网络隔离。它启动新的 CLI 任务，不会向既有桌面聊天插入消息，也不会点击屏幕。内部 Muse 接口未经版本化，随时可能改变；只支持标准 NON_TEE / 旧式标准握手。
61+
62+
[英文首页](README.md) · [任务桥说明](TASK_BRIDGE.md) · [验证记录](VALIDATION.md) · [权限边界](SECURITY.md) · [协议来源](PROVENANCE.md)

0 commit comments

Comments
 (0)