@voyager-crew/cli 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jesse Zhang
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.
package/README.md CHANGED
@@ -1,3 +1,128 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
+ <img src="https://raw.githubusercontent.com/voyager-crew/voyager-cli/main/assets/logo.svg" alt="Voyager CLI logo" width="96" height="96">
3
+ <h1>Voyager CLI</h1>
4
+ <p>Ask ChatGPT from your terminal, or let your coding agent do it,<br>through the ChatGPT you are already signed in to in your browser.</p>
5
+ <p>
6
+ <a href="https://www.npmjs.com/package/@voyager-crew/cli"><img src="https://img.shields.io/npm/v/@voyager-crew/cli?style=flat-square" alt="npm version"></a>
7
+ <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT license">
8
+ </p>
9
+ <p><b>English</b> • <a href="README_ZH.md">简体中文</a></p>
10
+ </div>
2
11
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
12
+ ```sh
13
+ voyager ask "Review this design" --attach ./docs/design.md
14
+ ```
15
+
16
+ Voyager CLI is the reference client for the **ChatGPT Local Bridge** in the
17
+ [Voyager](https://github.com/voyager-crew/voyager) browser extension. The bridge lets programs on
18
+ your computer work with ChatGPT on the web: open a chat, send a prompt with files, wait for the
19
+ reply and read it, manage project files. Voyager CLI puts that in your terminal and saves each
20
+ reply as `response.md`. Everything stays on your machine: the CLI listens on `127.0.0.1` only,
21
+ and ChatGPT sees an ordinary chat from your own browser.
22
+ [More about the bridge →](https://voyager.nagi.fun/en/guide/local-bridge)
23
+
24
+ ## Setup
25
+
26
+ 1. Install Voyager CLI (Node.js 20.3 or later):
27
+
28
+ ```sh
29
+ npm install -g @voyager-crew/cli
30
+ ```
31
+
32
+ 2. Install the Voyager extension, version 2.1.0 or later:
33
+ [Chrome](https://chromewebstore.google.com/detail/iifacdnjakkhjjiengaffnegbndgingi) ·
34
+ [Edge](https://microsoftedge.microsoft.com/addons/detail/voyager/gibmkggjijalcjinbdhcpklodjkhhlne) ·
35
+ [Firefox](https://addons.mozilla.org/firefox/addon/gemini-voyager/). In its popup, open
36
+ **Plugins**, turn on **ChatGPT · Local Bridge** and allow access to chatgpt.com.
37
+ 3. Pair them once:
38
+
39
+ ```sh
40
+ voyager pair
41
+ ```
42
+
43
+ Open the Voyager popup on a ChatGPT tab and enter the eight-character code it prints in the
44
+ Local Bridge settings.
45
+
46
+ ## Asking
47
+
48
+ ```sh
49
+ voyager ask "Explain this stack trace" --attach crash.log
50
+ voyager ask "Look over the repo" --attach ./src # folders go up as a zip, secrets left out
51
+ voyager ask --model high "Quick sanity check" # pro (default), extra-high, high, medium, instant
52
+ voyager ask --chat <link|id> "And the edge cases?" # follow up in a conversation
53
+ voyager read <link|id> # save a conversation's latest reply
54
+ ```
55
+
56
+ Every ask uses GPT-6 Pro in chat mode unless you pick another effort, and leaves it selected.
57
+ Voyager never switches ChatGPT to Work mode. The reply lands in `~/.voyager/jobs/<id>/output/`,
58
+ and `--json` prints its path along with the conversation link.
59
+
60
+ ### Long answers
61
+
62
+ Pro can think for hours. `ask` waits as long as ChatGPT is still working on the reply, and
63
+ only gives up after 20 minutes with no sign of life. To get your terminal back, submit and
64
+ collect later:
65
+
66
+ ```sh
67
+ voyager ask --no-wait "…" # prints a job id
68
+ voyager job wait <id> --timeout 10m # exit 4 means still running: wait again, never resend
69
+ ```
70
+
71
+ ## Projects
72
+
73
+ A ChatGPT project keeps files that every chat in it can read, so a codebase or a paper goes
74
+ up once instead of with every question.
75
+
76
+ ```sh
77
+ voyager project create "Thesis"
78
+ voyager project upload "Thesis" ./thesis # replaced when it changes, skipped when it hasn't
79
+ voyager ask --project "Thesis" "Where is the argument weakest?"
80
+ voyager project files "Thesis"
81
+ voyager project remove "Thesis" old-notes.md # immediate and permanent; asks first
82
+ ```
83
+
84
+ ## Using it from an agent
85
+
86
+ Claude Code, Codex and any other agent that can run shell commands can use Voyager CLI. Install
87
+ the skill that teaches them how:
88
+
89
+ ```sh
90
+ npx skills add voyager-crew/voyager-cli
91
+ ```
92
+
93
+ [`skills/voyager/SKILL.md`](skills/voyager/SKILL.md) is written for them: JSON output, what each
94
+ exit code means, how to wait for a long job without sending the prompt twice, and how to follow
95
+ up with `--chat` and the conversation id it got rather than `--continue`.
96
+
97
+ One job runs at a time. Every result also names your ChatGPT plan (`Pro Lite ($100)`,
98
+ `Pro ($200)`, …) as the page last reported it.
99
+
100
+ ## Good to know
101
+
102
+ - `ask`, `read` and every `project` command open their own ChatGPT tab and close it when they
103
+ end, also after a failure; pass `--keep-tab` to leave it open. If ChatGPT asks you to sign in
104
+ or solve a challenge, Voyager CLI stops, leaves that tab open and says so (exit 3); it never
105
+ works around it.
106
+ - `voyager update` updates everything it can: the CLI (when npm installed it globally),
107
+ `voyager serve` (restarted unless a job is running) and the extension's page data, fetched now
108
+ instead of at its next check. Your browser's store updates the extension itself.
109
+ - Commands: `voyager --help`. State lives in `~/.voyager` (or `$VOYAGER_HOME`), private to
110
+ your user.
111
+ - Tested in Chrome. Edge and Firefox builds of Voyager include the bridge too; Safari does not.
112
+
113
+ ## Disclaimer
114
+
115
+ - Voyager and Voyager CLI are community open-source projects. They are not affiliated with or
116
+ endorsed by OpenAI.
117
+ - The bridge automates ChatGPT on the web in your own signed-in browser. OpenAI's
118
+ [Terms of Use](https://openai.com/policies/terms-of-use/) restrict extracting output by automated or programmatic means, so decide
119
+ for yourself whether your use complies before you rely on it. Any limits placed on your account
120
+ as a result are your own risk.
121
+ - Similar tools take the same line: [oracle](https://github.com/steipete/oracle), for example, makes its browser mode an opt-in
122
+ experimental feature and points people who want to avoid the risk to the API. If you need a
123
+ supported route, use the OpenAI API.
124
+ - The bridge is for your own convenience on your own computer: connect only your own account, do not use it to serve other people, share an account or resell usage, and use it only for lawful purposes.
125
+
126
+ ## License
127
+
128
+ MIT. Development notes are in [CONTRIBUTING.md](CONTRIBUTING.md).
package/README_ZH.md ADDED
@@ -0,0 +1,110 @@
1
+ <div align="center">
2
+ <img src="https://raw.githubusercontent.com/voyager-crew/voyager-cli/main/assets/logo.svg" alt="Voyager CLI logo" width="96" height="96">
3
+ <h1>Voyager CLI</h1>
4
+ <p>在终端里向 ChatGPT 提问,或者交给你的 coding agent 去问,<br>用的就是你浏览器里已经登录的那个 ChatGPT。</p>
5
+ <p>
6
+ <a href="https://www.npmjs.com/package/@voyager-crew/cli"><img src="https://img.shields.io/npm/v/@voyager-crew/cli?style=flat-square" alt="npm version"></a>
7
+ <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT license">
8
+ </p>
9
+ <p><a href="README.md">English</a> • <b>简体中文</b></p>
10
+ </div>
11
+
12
+ ```sh
13
+ voyager ask "帮我审一下这份设计" --attach ./docs/design.md
14
+ ```
15
+
16
+ Voyager CLI 是 [Voyager](https://github.com/voyager-crew/voyager) 浏览器插件里 **ChatGPT 本地桥**
17
+ 的参考客户端。本地桥让本机程序可以跟 ChatGPT 网页版协作:打开对话、附文件发送、等回复写完再读取、管理项目文件。Voyager CLI
18
+ 把这些带到终端里,每次的回答存成 `response.md`。全程都在你自己的电脑上:命令行只监听 `127.0.0.1`,ChatGPT
19
+ 看到的就是你浏览器里一次普通的对话。[了解本地桥 →](https://voyager.nagi.fun/guide/local-bridge)
20
+
21
+ ## 安装
22
+
23
+ 1. 安装 Voyager CLI(需要 Node.js 20.3 或更高版本):
24
+
25
+ ```sh
26
+ npm install -g @voyager-crew/cli
27
+ ```
28
+
29
+ 2. 安装 Voyager 插件,需要 2.1.0 或更高版本:
30
+ [Chrome](https://chromewebstore.google.com/detail/iifacdnjakkhjjiengaffnegbndgingi) ·
31
+ [Edge](https://microsoftedge.microsoft.com/addons/detail/voyager/gibmkggjijalcjinbdhcpklodjkhhlne) ·
32
+ [Firefox](https://addons.mozilla.org/firefox/addon/gemini-voyager/)。打开插件弹窗,进入
33
+ **插件**,打开 **ChatGPT · 本地桥**,并允许访问 chatgpt.com。
34
+ 3. 配对一次:
35
+
36
+ ```sh
37
+ voyager pair
38
+ ```
39
+
40
+ 在 ChatGPT 标签页上打开 Voyager 弹窗,把它显示的 8 位配对码填进「本地桥接」的设置。
41
+
42
+ ## 提问
43
+
44
+ ```sh
45
+ voyager ask "解释一下这段报错" --attach crash.log
46
+ voyager ask "看看这个仓库" --attach ./src # 文件夹会打包成 zip,自动去掉密钥等凭据
47
+ voyager ask --model high "快速检查一下" # pro(默认)、extra-high、high、medium、instant
48
+ voyager ask --chat <链接|id> "边界情况呢?" # 在已有对话里接着问
49
+ voyager read <链接|id> # 保存某个对话的最新回答
50
+ ```
51
+
52
+ 默认用聊天模式下的 GPT-6 Pro,除非你另选思考强度;问完保持在这个选择上。Voyager 不会把 ChatGPT
53
+ 切到「工作」模式。回答保存在 `~/.voyager/jobs/<id>/output/`,加 `--json` 会输出文件路径和对话链接。
54
+
55
+ ### 很长的回答
56
+
57
+ Pro 可能要想好几个小时。只要 ChatGPT 还在写,`ask` 就一直等;连续 20 分钟完全没动静才算失败。想先拿回终端,就先提交、之后再取:
58
+
59
+ ```sh
60
+ voyager ask --no-wait "…" # 输出一个任务 id
61
+ voyager job wait <id> --timeout 10m # 退出码 4 表示还在跑:接着等,千万别重发问题
62
+ ```
63
+
64
+ ## 项目
65
+
66
+ ChatGPT 的项目可以存放文件,项目里的每个对话都能读到。代码库或论文传一次就行,不用每次提问都附上。
67
+
68
+ ```sh
69
+ voyager project create "论文"
70
+ voyager project upload "论文" ./thesis # 内容变了就替换,没变就跳过
71
+ voyager ask --project "论文" "论证最薄弱的地方在哪?"
72
+ voyager project files "论文"
73
+ voyager project remove "论文" old-notes.md # 立即删除且无法恢复,会先确认
74
+ ```
75
+
76
+ ## 给 agent 用
77
+
78
+ Claude Code、Codex 以及任何能运行终端命令的 agent 都能用 Voyager CLI。先装上教它们怎么用的 skill:
79
+
80
+ ```sh
81
+ npx skills add voyager-crew/voyager-cli
82
+ ```
83
+
84
+ [`skills/voyager/SKILL.md`](skills/voyager/SKILL.md) 就是写给它们看的:JSON 输出、每个退出码的含义、怎么等长任务而不把问题发两遍,以及接着问时用
85
+ `--chat` 加上次拿到的对话 id,而不是 `--continue`。
86
+
87
+ 同一时间只跑一个任务。每次的结果里还会带上你的 ChatGPT 套餐(`Pro Lite ($100)`、`Pro ($200)`
88
+ 等),以页面最近一次报告的为准。
89
+
90
+ ## 须知
91
+
92
+ - `ask`、`read` 和所有 `project` 命令都会自己打开一个 ChatGPT 标签页,结束时关掉,失败了也关;
93
+ 想留着就加 `--keep-tab`。如果 ChatGPT 要求登录或人机验证,Voyager CLI 会停下来、留着那个
94
+ 标签页并告诉你(退出码 3),不会绕过。
95
+ - `voyager update` 把能更新的都更新一遍:命令行本身(用 npm 全局安装时)、`voyager serve`
96
+ (没有任务在跑时重启)和扩展的页面数据(立即重新获取,不等下一次定时检查)。扩展本身由浏览器的
97
+ 扩展商店更新。
98
+ - 全部命令见 `voyager --help`。状态保存在 `~/.voyager`(或 `$VOYAGER_HOME`),只有你的用户能读。
99
+ - 已在 Chrome 中测试。Edge 和 Firefox 版的 Voyager 也带这个桥;Safari 版没有。
100
+
101
+ ## 须知与免责
102
+
103
+ - Voyager 和 Voyager CLI 是社区开源项目,与 OpenAI 无关,也没有得到 OpenAI 的认可。
104
+ - 本地桥会在你自己登录的浏览器里自动操作 ChatGPT 网页版。OpenAI 的[使用条款](https://openai.com/policies/terms-of-use/)限制以自动或程序化的方式提取输出,使用前请自行判断是否符合条款;账号因此受到的任何限制,由你自己承担。
105
+ - 同类工具也是这样处理的:例如 [oracle](https://github.com/steipete/oracle) 把浏览器模式作为需要主动开启的实验功能,并建议在意风险的人改用 API。需要有保障的用法,请使用 OpenAI API。
106
+ - 本地桥是给你在自己电脑上、为自己方便而用的:只连你自己的账号,不要拿它对外提供服务、共享账号或转卖额度,也只用于合法用途。
107
+
108
+ ## 许可证
109
+
110
+ MIT。开发说明见 [CONTRIBUTING.md](CONTRIBUTING.md)。