@k-leumas/queque-cli 0.6.0 → 0.7.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/README.md +88 -17
- package/dist/cli/app.js +1376 -150
- package/dist/cli/app.js.map +1 -1
- package/package.json +1 -1
- package/shell/zsh/queque.zsh +1 -1
package/README.md
CHANGED
|
@@ -16,7 +16,7 @@ Welcome to the **future** –
|
|
|
16
16
|

|
|
17
17
|
|
|
18
18
|
> [!NOTE]
|
|
19
|
-
> After install, run `qq init zsh
|
|
19
|
+
> After install, run `qq init zsh && source ~/.zshrc` to wire up the `??` keybinding. `qq init zsh` adds the QueQue source line to the end of `~/.zshrc` itself, so do not redirect its output into the file.
|
|
20
20
|
|
|
21
21
|
|
|
22
22
|
<details>
|
|
@@ -25,28 +25,87 @@ Welcome to the **future** –
|
|
|
25
25
|
## Requirements
|
|
26
26
|
|
|
27
27
|
- zsh
|
|
28
|
-
- Node.js
|
|
28
|
+
- Node.js 24 or newer
|
|
29
29
|
- [jq](https://jqlang.github.io/jq/)
|
|
30
|
+
- Claude Code signed in, an Anthropic API key, an OpenAI API key, or Ollama (see [Choose a provider](#choose-a-provider))
|
|
30
31
|
|
|
31
32
|
|
|
32
33
|
```shell
|
|
33
34
|
npm install -g @k-leumas/queque-cli
|
|
34
|
-
qq init zsh
|
|
35
|
+
qq init zsh && source ~/.zshrc
|
|
35
36
|
```
|
|
36
37
|
|
|
37
38
|
</details>
|
|
38
39
|
|
|
39
|
-
##
|
|
40
|
+
## Choose a provider
|
|
40
41
|
|
|
41
|
-
|
|
42
|
+
Claude is the default. If you already use Claude Code or have an Anthropic API key, there is nothing to set up. To use OpenAI or a local Ollama model instead (both in beta), run `qq init provider` once.
|
|
42
43
|
|
|
43
|
-
|
|
44
|
-
2. **`.env.local` file** — place a `.env.local` in your project directory (or any parent). QueQue searches upward from the current working directory:
|
|
45
|
-
```shell
|
|
46
|
-
ANTHROPIC_API_KEY=sk-ant-...
|
|
47
|
-
```
|
|
44
|
+
### Claude (default)
|
|
48
45
|
|
|
49
|
-
|
|
46
|
+
QueQue talks to Claude in one of two ways. You only need one.
|
|
47
|
+
|
|
48
|
+
**Claude Code login (no API key needed).** If you already use Claude Code, QueQue runs `claude -p` on your existing login whenever no API key is set. Sign in once through Claude Code's `/login`:
|
|
49
|
+
|
|
50
|
+
```shell
|
|
51
|
+
claude /login
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
On this route QueQue uses whatever account and default model Claude Code is set to; it passes no model flag. `claude -p` runs with its tools disabled and session persistence off, so it only answers the query. If `claude` is not signed in, `??` shows this message and puts back what you typed:
|
|
55
|
+
|
|
56
|
+
```text
|
|
57
|
+
QueQue: Claude is not authenticated. Run `claude /login`, or set ANTHROPIC_API_KEY in the environment or ~/.env.local. To use OpenAI or Ollama instead, run `qq init provider`.
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
If `claude` is not on your `PATH` at all, the message starts with `QueQue: No AI provider is ready.` and lists the same three options. Any other `claude -p` failure, such as an overloaded API or a usage limit, shows `QueQue: Claude Code could not answer (claude -p failed).`; run `claude -p "hi"` to see the underlying error.
|
|
61
|
+
|
|
62
|
+
**Anthropic API key.** QueQue looks for `ANTHROPIC_API_KEY` in this order:
|
|
63
|
+
|
|
64
|
+
1. **Environment variable**: `export ANTHROPIC_API_KEY="sk-ant-..."` in `~/.zshrc`, above the QueQue source line.
|
|
65
|
+
2. **`.env.local` file**: a line `ANTHROPIC_API_KEY=sk-ant-...` in `~/.env.local`. QueQue reads only `~/.env.local` itself: never the directory you run `??` from and never a directory above your home directory, so a `.env.local` inside a project (or in `/tmp`) is not used. The background daemon reads the file once, when it starts.
|
|
66
|
+
|
|
67
|
+
An empty or whitespace-only value counts as unset.
|
|
68
|
+
|
|
69
|
+
**Which route wins.** A non-empty `ANTHROPIC_API_KEY` always wins: QueQue calls Claude through the Anthropic SDK and never runs `claude -p`. There is no automatic fallback in either direction. If the API-key request fails, QueQue shows that error instead of trying your Claude Code login, and a failed `claude -p` run never falls back to a key. To switch to your Claude Code login, remove the key from your environment and `~/.env.local`, then restart the daemon.
|
|
70
|
+
|
|
71
|
+
`QQ_MODEL` picks the model on the API-key route only. The default is `claude-sonnet-5`.
|
|
72
|
+
|
|
73
|
+
### OpenAI or Ollama (beta)
|
|
74
|
+
|
|
75
|
+
Run the picker in a terminal:
|
|
76
|
+
|
|
77
|
+
```shell
|
|
78
|
+
qq init provider
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
It asks one question (Claude, OpenAI or Ollama), saves your answer to `~/.config/qq/provider.json`, and restarts the background daemon. Nothing is probed until you answer, and `??` never asks you to choose.
|
|
82
|
+
|
|
83
|
+
- **OpenAI (beta)** needs `OPENAI_API_KEY` in your environment (`export OPENAI_API_KEY="sk-..."` in `~/.zshrc`, above the QueQue source line) or in `~/.env.local`. Set the key first, open a new terminal, then run `qq init provider`. QueQue never asks for the key and never stores it: `provider.json` only records that you chose OpenAI. The default model is `gpt-5.5`.
|
|
84
|
+
- **Ollama (beta)** lists the models you have already pulled and pins the one you pick. If Ollama is not running, the picker prints the download link and `ollama serve`. If it has no models, the picker tells you to run `ollama pull`. When `provider.json` has a `baseUrl` (a remote server), the picker lists and keeps that server; to go back to Ollama on this machine, remove `baseUrl` from `provider.json`.
|
|
85
|
+
|
|
86
|
+
Your choice sticks. If the chosen provider fails, `??` shows that provider's error; QueQue never switches to a different provider on its own. Run `qq init provider` again to switch, including back to Claude.
|
|
87
|
+
|
|
88
|
+
`provider.json` is plain JSON you can edit by hand, and QueQue reads it again on every `??`:
|
|
89
|
+
|
|
90
|
+
```json
|
|
91
|
+
{"version":1,"provider":"ollama","model":"gemma4"}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Add `"model"` to an OpenAI pin to change the model, or `"baseUrl"` to an Ollama pin to use a server other than `http://localhost:11434`. Keys are not allowed in this file: an extra field such as `"apiKey"` makes it invalid, and `??` then tells you to fix the file or run `qq init provider`. Set `QQ_PROVIDER_FILE` to an absolute path to keep the file somewhere else; a relative path makes the pin invalid.
|
|
95
|
+
|
|
96
|
+
### After changing your key or settings
|
|
97
|
+
|
|
98
|
+
A background daemon answers `??` for every terminal. It starts with your first interactive shell (and again on the next `??` if it is not running) and inherits that shell's environment. It reads `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `QQ_MODEL`, `~/.env.local` and `~/.config/qq/config.json` once, when it starts. `provider.json` is the exception: it is read on every `??`.
|
|
99
|
+
|
|
100
|
+
- `qq init provider` restarts the daemon for you, so running it after exporting a new key is enough.
|
|
101
|
+
|
|
102
|
+
- Put your `export` lines in `~/.zshrc` above the `# queque shell integration` block that `qq init zsh` appended, so the daemon started during shell startup sees them.
|
|
103
|
+
- After changing any of them, restart the daemon from a shell that has the new values:
|
|
104
|
+
|
|
105
|
+
```shell
|
|
106
|
+
pkill -f 'daemon --socket /tmp/qq-'
|
|
107
|
+
qq daemon --ensure
|
|
108
|
+
```
|
|
50
109
|
|
|
51
110
|
## Usage
|
|
52
111
|
|
|
@@ -58,9 +117,17 @@ find docker containers using port 3000??
|
|
|
58
117
|
git undo last commit but keep changes??
|
|
59
118
|
```
|
|
60
119
|
|
|
61
|
-
A selection UI opens in-terminal.
|
|
120
|
+
A selection UI opens in-terminal. Rows appear as the provider answers. Only Claude streams them today, so with Claude you can pick one before the rest have arrived; OpenAI and Ollama show the whole list at once. What you typed stays in the dim `queque ›` header, and the FILTER box opens empty: type to narrow the list, even while `thinking…` is still showing. Move with the arrow keys and press `Enter`. The command lands in your buffer exactly as shown, ready to run or edit. QueQue never runs it for you.
|
|
121
|
+
|
|
122
|
+
Press `Esc` to cancel. It stops the request to the provider and restores what you were typing, so you can tweak your intent and hit `??` again.
|
|
62
123
|
|
|
63
|
-
|
|
124
|
+
A command that matches a destructive pattern (`rm`, `sudo` and similar) is marked `⚠ review carefully — this command may be destructive`. The mark is a warning only; the row stays selectable.
|
|
125
|
+
|
|
126
|
+
### Installed-tool awareness
|
|
127
|
+
|
|
128
|
+
QueQue checks each suggestion against the commands zsh can find on your machine. A row that needs a tool zsh cannot find gets `ⓘ` before its explanation, and the legend reads `ⓘ not installed`. The row stays selectable. When QueQue knows how to install that tool with brew, apt, dnf or pacman, the legend adds `tab prepends the install command`: press `Tab` (or `Shift+Tab`) on the row to switch it to the install form, and again to switch back. The install form is inserted like any other command, never run.
|
|
129
|
+
|
|
130
|
+
Set `QQ_TOOL_AWARENESS=0` in your shell to turn this off.
|
|
64
131
|
|
|
65
132
|
### Inside Zellij
|
|
66
133
|
|
|
@@ -74,18 +141,22 @@ Without Zellij, QueQue falls back to an inline TUI in your current terminal sess
|
|
|
74
141
|
|
|
75
142
|
QueQue is **insertion-only**: it writes commands into your shell buffer — you press Enter to run them. QueQue never auto-executes suggestions.
|
|
76
143
|
|
|
77
|
-
**What leaves your machine (
|
|
144
|
+
**What leaves your machine (Claude and OpenAI, hosted).** The provider you chose receives the same context, whichever it is: Claude (through `claude -p` or the API key) or OpenAI (through `OPENAI_API_KEY`). Only that one provider receives it:
|
|
78
145
|
|
|
79
146
|
- Your query text and current working directory
|
|
147
|
+
- Your OS platform name (for example `darwin` or `linux`) and shell name (`zsh`)
|
|
80
148
|
- Git metadata (branch, dirty flag, changed file *names* — not file contents)
|
|
81
149
|
- Parsed filename hints from your query (no disk reads)
|
|
150
|
+
- The names of installed tools that appear in QueQue's public tool catalog. Your full `PATH` inventory, functions and aliases stay on your machine. `QQ_TOOL_AWARENESS=0` stops even the catalog names.
|
|
151
|
+
|
|
152
|
+
**With Ollama**, the same context goes only to your Ollama server (`http://localhost:11434` by default, or the `baseUrl` in `provider.json`). With the default setting, nothing leaves your machine. A `baseUrl` that starts with `http://` and names another machine sends that context across the network unencrypted; for a remote server, use an `https://` URL (for example behind a reverse proxy).
|
|
82
153
|
|
|
83
154
|
**What QueQue never sends:**
|
|
84
155
|
|
|
85
156
|
- File contents (unless you explicitly opt in later with `QQ_ALLOW_FILE_READ=1`)
|
|
86
157
|
- Paths matching sensitive patterns (`.env`, credentials, `.pem`, `id_rsa`, etc.) are stripped from git context
|
|
87
158
|
|
|
88
|
-
**Debug logging:**
|
|
159
|
+
**Debug logging:** The client and daemon append short diagnostics to `/tmp/qq-<uid>-debug.log`, or to the file named by `QQ_DEBUG_LOG_FILE`. Shell buffer and query text are redacted unless `QQ_DEBUG_VERBOSE=1`. The zsh widget adds its own lines only when `QQ_DEBUG_LOG_FILE` is set. The log stays on your machine.
|
|
89
160
|
|
|
90
161
|
**User config:** Copy [docs/config.example.json](docs/config.example.json) to `~/.config/qq/config.json` to add extra sensitive path patterns, log redaction keys, or destructive-command warnings. Built-in defaults always apply — your patterns are merged on top. Override the file path with `QQ_CONFIG_FILE`. Malformed `config.json` is ignored with a warning; QueQue falls back to built-in defaults (fail-closed).
|
|
91
162
|
|
|
@@ -97,13 +168,13 @@ Copy [docs/config.example.json](docs/config.example.json) to `~/.config/qq/confi
|
|
|
97
168
|
|
|
98
169
|
| Field | Type | Purpose |
|
|
99
170
|
|-------|------|---------|
|
|
100
|
-
| `effort` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` | Claude effort for `claude -p` (`--effort`) and for the API-key SDK path, which sends it as `output_config.effort`. The SDK path omits it when `QQ_MODEL` names a model without effort support (Haiku 4.5, Sonnet 4.5 or older); a level that a `QQ_MODEL` model does not support (for example `xhigh` on Opus 4.5) is your responsibility. Default `low`. Trimmed and case-insensitive; invalid values fall back to `low` without affecting the rest of the file. Takes effect after
|
|
171
|
+
| `effort` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` | Claude effort for `claude -p` (`--effort`) and for the API-key SDK path, which sends it as `output_config.effort`. The SDK path omits it when `QQ_MODEL` names a model without effort support (Haiku 4.5, Sonnet 4.5 or older); a level that a `QQ_MODEL` model does not support (for example `xhigh` on Opus 4.5) is your responsibility. Default `low`. Trimmed and case-insensitive; invalid values fall back to `low` without affecting the rest of the file. Takes effect after a [daemon restart](#after-changing-your-key-or-settings), because the daemon reads config.json once. |
|
|
101
172
|
| `privacy.sensitivePathPatterns` | `string[]` | Extra regex patterns merged onto built-in defaults (`.env`, credentials, keys, etc.). Built-in patterns are never removed. |
|
|
102
173
|
| `privacy.redactLogKeys` | `string[]` | Extra JSON keys to redact in debug logs (merged with defaults: `lbuffer`, `rbuffer`, `queryText`, `request`). |
|
|
103
174
|
| `privacy.allowFileRead` | `boolean` | Opt-in gate for future file-content context. Env `QQ_ALLOW_FILE_READ=1` overrides this. No file reads in v1. |
|
|
104
175
|
| `privacy.useGitignore` | `boolean` | Reserved for future gitignore-based filtering. Ignored today. |
|
|
105
176
|
| `safety.destructiveCommandPatterns` | `string[]` | Extra warn-only UI patterns merged onto built-in defaults (`rm`, `sudo`, etc.). |
|
|
106
177
|
|
|
107
|
-
See [docs/SYSTEM_DESIGN.md](docs/SYSTEM_DESIGN.md) for architecture
|
|
178
|
+
See [docs/SYSTEM_DESIGN.md](docs/SYSTEM_DESIGN.md) for architecture.
|
|
108
179
|
|
|
109
180
|
|