greprag 5.84.0 → 5.85.1
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/dist/commands/agent-doctrine-file.js +5 -128
- package/dist/commands/agents.js +125 -846
- package/dist/commands/init.js +17 -29
- package/dist/commands/load.js +14 -36
- package/dist/commands/parity.js +1 -1
- package/dist/commands/skill-mirror-reminder.js +1 -18
- package/dist/commands/skill.js +137 -566
- package/dist/hook.js +30 -54
- package/dist/index.js +571 -573
- package/dist/native-adapter-refresh.js +15 -18
- package/dist/native-skill-mirror.js +11 -92
- package/dist/opencode-plugin.bundle.js +81 -283
- package/dist/skill-activation-manifest.js +14 -37
- package/dist/skill-git-ingest.js +300 -0
- package/dist/skill-landing.js +7 -173
- package/dist/skill-mirror-client.js +4 -280
- package/dist/skill-staleness.js +3 -6
- package/package.json +1 -1
- package/skill/mechanic/docs/skill-fix-conventions.md +1 -1
- package/skill/templates/os.md +1 -1
- package/skill/templates/prompt-audit.md +26 -49
- package/skill/templates/skill-change.md +15 -13
package/dist/index.js
CHANGED
|
@@ -206,78 +206,78 @@ async function apiDelete(url, apiKey) {
|
|
|
206
206
|
throw new Error(`API ${res.status}: ${await res.text()}`);
|
|
207
207
|
return res.json();
|
|
208
208
|
}
|
|
209
|
-
const INBOX_HELP = `greprag inbox — read + manage your async message inbox.
|
|
210
|
-
|
|
211
|
-
greprag inbox List unread for THIS session: its own lines
|
|
212
|
-
only (sender or recipient). Other sessions'
|
|
213
|
-
private lines AND the front desk are hidden —
|
|
214
|
-
the front desk is opt-in (--front-desk).
|
|
215
|
-
greprag inbox --front-desk Read the front desk: the tenant catch-all
|
|
216
|
-
(cold opens + inbound email). Add --peek to
|
|
217
|
-
survey without marking read.
|
|
218
|
-
greprag inbox --all Audit peek: drop the per-session scope (every
|
|
219
|
-
session's lines) AND include already-read.
|
|
220
|
-
greprag inbox --peek List WITHOUT marking read (non-mutating).
|
|
221
|
-
greprag inbox --session <8hex> Scope to one specific session's view.
|
|
222
|
-
greprag inbox --project <name> Filter to one project's inbox.
|
|
223
|
-
greprag inbox watch [...] Long-lived SSE stream (run under Monitor).
|
|
224
|
-
[--receptionist] Attend the front desk — wake live on a cold
|
|
225
|
-
open / inbound email (else only manual check).
|
|
226
|
-
[--mechanic] Live Mechanic — normal delivery PLUS a wake
|
|
227
|
-
on tenant mechanic_friction events.
|
|
228
|
-
greprag inbox watchers [--json] List live armed GrepRAG/Claude/OpenCode
|
|
229
|
-
watchers under your tenant. Codex task
|
|
230
|
-
discovery, including repo/workspace, uses
|
|
231
|
-
codex_app.list_threads.
|
|
232
|
-
greprag inbox reap Kill orphaned watcher processes (consumer gone)
|
|
233
|
-
+ sweep stale pidfiles. Runs auto at session start.
|
|
234
|
-
greprag inbox claim <id> Receptionist: claim a front-desk record so a
|
|
235
|
-
co-armed receptionist stands down (no dup reply).
|
|
236
|
-
greprag inbox keep <id> Extend a message's TTL.
|
|
237
|
-
greprag inbox delete <id> Delete a message.
|
|
238
|
-
|
|
239
|
-
To SEND or REPLY (top-level command, NOT an inbox subcommand):
|
|
240
|
-
greprag send --to discord:<snowflake> "reply" Reply to a Discord DM.
|
|
241
|
-
greprag send "msg" --to <handle>@greprag.com Cold open (tenant catch-all).
|
|
242
|
-
greprag send "msg" --to <handle>@greprag.com/<session> Message a specific session.
|
|
243
|
-
greprag send "msg" --to <h>@greprag.com/<session> --in-reply-to <front-desk-id>
|
|
244
|
-
Reply that threads a cold open.
|
|
245
|
-
|
|
246
|
-
Codex session-targeted sends are ordinary durable recipient messages. The
|
|
247
|
-
target's Codex turn hooks surface them at SessionStart/UserPromptSubmit
|
|
248
|
-
boundaries. Codex-to-Codex coordination uses
|
|
209
|
+
const INBOX_HELP = `greprag inbox — read + manage your async message inbox.
|
|
210
|
+
|
|
211
|
+
greprag inbox List unread for THIS session: its own lines
|
|
212
|
+
only (sender or recipient). Other sessions'
|
|
213
|
+
private lines AND the front desk are hidden —
|
|
214
|
+
the front desk is opt-in (--front-desk).
|
|
215
|
+
greprag inbox --front-desk Read the front desk: the tenant catch-all
|
|
216
|
+
(cold opens + inbound email). Add --peek to
|
|
217
|
+
survey without marking read.
|
|
218
|
+
greprag inbox --all Audit peek: drop the per-session scope (every
|
|
219
|
+
session's lines) AND include already-read.
|
|
220
|
+
greprag inbox --peek List WITHOUT marking read (non-mutating).
|
|
221
|
+
greprag inbox --session <8hex> Scope to one specific session's view.
|
|
222
|
+
greprag inbox --project <name> Filter to one project's inbox.
|
|
223
|
+
greprag inbox watch [...] Long-lived SSE stream (run under Monitor).
|
|
224
|
+
[--receptionist] Attend the front desk — wake live on a cold
|
|
225
|
+
open / inbound email (else only manual check).
|
|
226
|
+
[--mechanic] Live Mechanic — normal delivery PLUS a wake
|
|
227
|
+
on tenant mechanic_friction events.
|
|
228
|
+
greprag inbox watchers [--json] List live armed GrepRAG/Claude/OpenCode
|
|
229
|
+
watchers under your tenant. Codex task
|
|
230
|
+
discovery, including repo/workspace, uses
|
|
231
|
+
codex_app.list_threads.
|
|
232
|
+
greprag inbox reap Kill orphaned watcher processes (consumer gone)
|
|
233
|
+
+ sweep stale pidfiles. Runs auto at session start.
|
|
234
|
+
greprag inbox claim <id> Receptionist: claim a front-desk record so a
|
|
235
|
+
co-armed receptionist stands down (no dup reply).
|
|
236
|
+
greprag inbox keep <id> Extend a message's TTL.
|
|
237
|
+
greprag inbox delete <id> Delete a message.
|
|
238
|
+
|
|
239
|
+
To SEND or REPLY (top-level command, NOT an inbox subcommand):
|
|
240
|
+
greprag send --to discord:<snowflake> "reply" Reply to a Discord DM.
|
|
241
|
+
greprag send "msg" --to <handle>@greprag.com Cold open (tenant catch-all).
|
|
242
|
+
greprag send "msg" --to <handle>@greprag.com/<session> Message a specific session.
|
|
243
|
+
greprag send "msg" --to <h>@greprag.com/<session> --in-reply-to <front-desk-id>
|
|
244
|
+
Reply that threads a cold open.
|
|
245
|
+
|
|
246
|
+
Codex session-targeted sends are ordinary durable recipient messages. The
|
|
247
|
+
target's Codex turn hooks surface them at SessionStart/UserPromptSubmit
|
|
248
|
+
boundaries. Codex-to-Codex coordination uses
|
|
249
249
|
codex_app.send_message_to_thread.`;
|
|
250
|
-
const INBOX_WATCH_HELP = `greprag inbox watch — long-lived SSE subscriber for live inbox delivery.
|
|
251
|
-
|
|
252
|
-
Run under the Claude Code Monitor tool: each printed line becomes one
|
|
253
|
-
notification, so a parent waiting on a chip report gets it the instant it
|
|
254
|
-
lands instead of polling.
|
|
255
|
-
|
|
256
|
-
greprag inbox watch Tenant-wide stream.
|
|
257
|
-
greprag inbox watch --project <name> Only messages addressed to this project.
|
|
258
|
-
greprag inbox watch --session <id> Only messages targeting this session.
|
|
259
|
-
Strictest — cold opens never wake it
|
|
260
|
-
(use --receptionist for the front desk).
|
|
261
|
-
greprag inbox watch --since <id|iso> Resume from a known cursor.
|
|
262
|
-
greprag inbox watch --json One JSON object per line (preferred under Monitor).
|
|
263
|
-
greprag inbox watch --quiet JSON on stdout only. Auto-on when GROK_SESSION_ID is set.
|
|
264
|
-
greprag inbox watch --receptionist Attend the front desk — wake live on a
|
|
265
|
-
cold open / inbound email.
|
|
266
|
-
greprag inbox watch --mechanic Attend as the live Mechanic — wake on
|
|
267
|
-
mechanic_friction events.
|
|
268
|
-
greprag inbox watch --no-supervise Run the SSE loop directly, skipping the
|
|
269
|
-
in-process supervisor (tests/debugging).
|
|
270
|
-
greprag inbox watch --owner-pid <n> Owning claude.exe PID (stamped by the arm
|
|
271
|
-
directive; the reaper keeps this watcher
|
|
272
|
-
iff that PID is a live claude.exe).
|
|
273
|
-
|
|
274
|
-
Arm it BARE under Monitor (persistent:true) — no "while true ... sleep 1" wrapper
|
|
275
|
-
(removed 2026-06-04; it orphaned and OOM-crashed the host). Resilience by default:
|
|
276
|
-
the watch SUPERVISES itself — a parent spawns the SSE loop as a child (Win32
|
|
277
|
-
CreateProcess, not Cygwin fork) and respawns it on any non-clean exit (crash,
|
|
278
|
-
undici error, OS kill); and it SELF-TERMINATES when its Monitor consumer's pipe
|
|
279
|
-
breaks (session reload/end) so it never orphans. Within-session robustness only;
|
|
280
|
-
a watcher cannot survive session reload / --resume / /compact.
|
|
250
|
+
const INBOX_WATCH_HELP = `greprag inbox watch — long-lived SSE subscriber for live inbox delivery.
|
|
251
|
+
|
|
252
|
+
Run under the Claude Code Monitor tool: each printed line becomes one
|
|
253
|
+
notification, so a parent waiting on a chip report gets it the instant it
|
|
254
|
+
lands instead of polling.
|
|
255
|
+
|
|
256
|
+
greprag inbox watch Tenant-wide stream.
|
|
257
|
+
greprag inbox watch --project <name> Only messages addressed to this project.
|
|
258
|
+
greprag inbox watch --session <id> Only messages targeting this session.
|
|
259
|
+
Strictest — cold opens never wake it
|
|
260
|
+
(use --receptionist for the front desk).
|
|
261
|
+
greprag inbox watch --since <id|iso> Resume from a known cursor.
|
|
262
|
+
greprag inbox watch --json One JSON object per line (preferred under Monitor).
|
|
263
|
+
greprag inbox watch --quiet JSON on stdout only. Auto-on when GROK_SESSION_ID is set.
|
|
264
|
+
greprag inbox watch --receptionist Attend the front desk — wake live on a
|
|
265
|
+
cold open / inbound email.
|
|
266
|
+
greprag inbox watch --mechanic Attend as the live Mechanic — wake on
|
|
267
|
+
mechanic_friction events.
|
|
268
|
+
greprag inbox watch --no-supervise Run the SSE loop directly, skipping the
|
|
269
|
+
in-process supervisor (tests/debugging).
|
|
270
|
+
greprag inbox watch --owner-pid <n> Owning claude.exe PID (stamped by the arm
|
|
271
|
+
directive; the reaper keeps this watcher
|
|
272
|
+
iff that PID is a live claude.exe).
|
|
273
|
+
|
|
274
|
+
Arm it BARE under Monitor (persistent:true) — no "while true ... sleep 1" wrapper
|
|
275
|
+
(removed 2026-06-04; it orphaned and OOM-crashed the host). Resilience by default:
|
|
276
|
+
the watch SUPERVISES itself — a parent spawns the SSE loop as a child (Win32
|
|
277
|
+
CreateProcess, not Cygwin fork) and respawns it on any non-clean exit (crash,
|
|
278
|
+
undici error, OS kill); and it SELF-TERMINATES when its Monitor consumer's pipe
|
|
279
|
+
breaks (session reload/end) so it never orphans. Within-session robustness only;
|
|
280
|
+
a watcher cannot survive session reload / --resume / /compact.
|
|
281
281
|
adr: adr/monitor-resilience.md`;
|
|
282
282
|
function readProjectRegistry() {
|
|
283
283
|
try {
|
|
@@ -1131,390 +1131,388 @@ async function retract(args) {
|
|
|
1131
1131
|
console.log((0, inbox_retract_1.formatRetractResult)(result.status));
|
|
1132
1132
|
}
|
|
1133
1133
|
// -- Main ------------------------------------------------------------------
|
|
1134
|
-
const INIT_HELP = `greprag init — configure GrepRAG for an agent client.
|
|
1135
|
-
|
|
1136
|
-
greprag init
|
|
1137
|
-
greprag init --codex [--api-key <existing-key>]
|
|
1138
|
-
greprag init --claude [--api-key <existing-key>]
|
|
1139
|
-
greprag init --opencode [--api-key <existing-key>]
|
|
1140
|
-
greprag init --grok [--api-key <existing-key>]
|
|
1141
|
-
greprag init --all [--root <path>]
|
|
1142
|
-
greprag init --global [--name <name>]
|
|
1143
|
-
|
|
1144
|
-
Options:
|
|
1145
|
-
--api-key <key> Use an existing GrepRAG API key. New accounts are closed.
|
|
1146
|
-
--codex Configure Codex hooks + /greprag skill.
|
|
1147
|
-
--claude Configure Claude Code hooks + /greprag skill.
|
|
1148
|
-
--opencode Configure OpenCode plugin.
|
|
1149
|
-
--grok Configure Grok Build hooks + skill + rules.
|
|
1150
|
-
|
|
1151
|
-
Codex Desktop trust step:
|
|
1152
|
-
After init, start a fresh Codex session, then open Settings -> Settings -> Hooks
|
|
1134
|
+
const INIT_HELP = `greprag init — configure GrepRAG for an agent client.
|
|
1135
|
+
|
|
1136
|
+
greprag init
|
|
1137
|
+
greprag init --codex [--api-key <existing-key>]
|
|
1138
|
+
greprag init --claude [--api-key <existing-key>]
|
|
1139
|
+
greprag init --opencode [--api-key <existing-key>]
|
|
1140
|
+
greprag init --grok [--api-key <existing-key>]
|
|
1141
|
+
greprag init --all [--root <path>]
|
|
1142
|
+
greprag init --global [--name <name>]
|
|
1143
|
+
|
|
1144
|
+
Options:
|
|
1145
|
+
--api-key <key> Use an existing GrepRAG API key. New accounts are closed.
|
|
1146
|
+
--codex Configure Codex hooks + /greprag skill.
|
|
1147
|
+
--claude Configure Claude Code hooks + /greprag skill.
|
|
1148
|
+
--opencode Configure OpenCode plugin.
|
|
1149
|
+
--grok Configure Grok Build hooks + skill + rules.
|
|
1150
|
+
|
|
1151
|
+
Codex Desktop trust step:
|
|
1152
|
+
After init, start a fresh Codex session, then open Settings -> Settings -> Hooks
|
|
1153
1153
|
and trust the GrepRAG hooks.`;
|
|
1154
|
-
const HELP = `
|
|
1155
|
-
greprag — agent memory for Claude Code, Codex, OpenCode, and Grok Build
|
|
1156
|
-
|
|
1157
|
-
Commands:
|
|
1158
|
-
(no command) Open the local GrepRAG app
|
|
1159
|
-
app | dashboard [--port N] Open the local app (use --no-open on remote machines)
|
|
1160
|
-
init [--api-key <existing-key>]
|
|
1161
|
-
Auto-detect/ask for Codex, Claude Code, or OpenCode
|
|
1162
|
-
init --claude [--api-key <existing-key>]
|
|
1163
|
-
Configure hooks + API key for Claude Code
|
|
1164
|
-
init --global [--name <name>] Create ~/.greprag/project.json (global anchor)
|
|
1165
|
-
init --opencode [--api-key <existing-key>]
|
|
1166
|
-
Configure plugin + anchor for OpenCode
|
|
1167
|
-
init --codex [--api-key <existing-key>]
|
|
1168
|
-
Configure lifecycle hooks + anchor for Codex
|
|
1169
|
-
init --grok [--api-key <existing-key>]
|
|
1170
|
-
Configure Grok Build hooks + skill + rules
|
|
1171
|
-
grok spawn [--cwd <path>] [--prompt "<text>"]
|
|
1172
|
-
Open a fresh Grok TUI in a new terminal
|
|
1173
|
-
(Windows schtasks bootloader — survives the
|
|
1174
|
-
tool Job Object; child arms its own watch)
|
|
1175
|
-
init --all [--root <path>] Standard init for cwd, then bulk-register every
|
|
1176
|
-
other git repo at depth 1 under <path> (default:
|
|
1177
|
-
parent of repo root). Each becomes inbox-addressable.
|
|
1178
|
-
status [--json] [--claude|--codex|--opencode|--grok]
|
|
1179
|
-
Installation, auth, platform hooks/plugins, and project state
|
|
1180
|
-
announce [--session <8hex>] [--path]
|
|
1181
|
-
Print the full SessionStart announce (the harness
|
|
1182
|
-
inlines only ~2KB; the rest is parked on disk)
|
|
1183
|
-
codex doctor Diagnose Codex hooks, trust setup, and current thread
|
|
1184
|
-
project-id Print the current project_id
|
|
1185
|
-
session-id [--full] Print this session's id (8-hex, 16-hex for UUIDv7, or full UUID with --full).
|
|
1186
|
-
discover [--json] Tenant-wide structure: every project, per-shape row counts,
|
|
1187
|
-
activity ranges. For cross-project advisors.
|
|
1188
|
-
doc <command> Mirror, search, and read project Markdown docs.
|
|
1189
|
-
docptr <command> Document-pointer registry and reference backfill.
|
|
1190
|
-
parity [seed] Doctrine drift-from-canon: the parity table (unit ·
|
|
1191
|
-
lead · stale followers), plus the operator-run seed.
|
|
1192
|
-
repodoc <index|status> Stable identity for a repo's own Markdown: blocks keep
|
|
1193
|
-
their ids through edits, splits, merges and renames.
|
|
1194
|
-
|
|
1195
|
-
|
|
1196
|
-
doctor [--inspect] [--yes] Diagnose + repair orphan project_ids and identity drift
|
|
1197
|
-
desk <run|ensure|status> The desk line: this machine answers which sessions
|
|
1198
|
-
are live when the cloud asks.
|
|
1199
|
-
smell "<text>" Shortcut for \`greprag fix log "<text>"\`.
|
|
1200
|
-
context status [--session <id>] Context-size governor readout: live tokens, threshold,
|
|
1201
|
-
% consumed, turns since the crossover advisory last fired.
|
|
1202
|
-
"context --help" for config (threshold + off-switch).
|
|
1203
|
-
delivery <command> Resolve and inspect repo delivery profiles.
|
|
1204
|
-
deploy-gate [--target <id>] Repo-independent deploy pre-flight: may a deploy run
|
|
1205
|
-
from here, is one already running, what is shipping.
|
|
1206
|
-
Read-only; the artifact proof stays with the repo.
|
|
1207
|
-
merge-lock <acquire|release|status> Serialise merges into a shared canonical
|
|
1208
|
-
checkout. Take it before you merge, release after.
|
|
1209
|
-
deploy-lock <acquire|release|status> --target <id>
|
|
1210
|
-
One deploy at a time per target. Pass --pid so the
|
|
1211
|
-
lock names the deploying process, not this command.
|
|
1212
|
-
deploy-record --target <id> Remember what this checkout last shipped, so the
|
|
1213
|
-
gate can say what a deploy is about to ship.
|
|
1214
|
-
deploy-verify --origin <url> --sha <commit>
|
|
1215
|
-
Prove production is serving the commit you shipped.
|
|
1216
|
-
Refuses if the build stamp is edge-cacheable.
|
|
1217
|
-
procedure <command> Governed operational procedure watches and runs.
|
|
1218
|
-
skillgain <command> Skill-learning queue and installation helpers.
|
|
1219
|
-
|
|
1220
|
-
Inbox (email-style messaging across tenants):
|
|
1221
|
-
inbox [--all] [--front-desk] [--session <id>] [--project <name>] [--peek]
|
|
1222
|
-
List unread, auto-scoped to THIS session: its own
|
|
1223
|
-
lines (sender OR recipient) only. Other sessions'
|
|
1224
|
-
private lines AND the front desk are hidden by
|
|
1225
|
-
default — the front desk (cold opens + inbound
|
|
1226
|
-
email) is opt-in via --front-desk.
|
|
1227
|
-
--all = audit peek: drop the per-session scope
|
|
1228
|
-
(every session's lines) AND include read history.
|
|
1229
|
-
--session scopes to one specific session's view.
|
|
1230
|
-
--project filters by project name.
|
|
1231
|
-
--peek: NON-MUTATING — does not mark any message read.
|
|
1232
|
-
inbox watchers [--json] List currently-attached live watchers
|
|
1233
|
-
(Claude / Codex / OpenCode / Grok). Each row:
|
|
1234
|
-
project · title (session_id) [platform] repo —
|
|
1235
|
-
project + nano title from session memory, repo
|
|
1236
|
-
from ~/.greprag/projects.json. Codex task
|
|
1237
|
-
discovery also uses codex_app.list_threads.
|
|
1238
|
-
inbox watch Long-lived SSE stream — prints each message as it lands.
|
|
1239
|
-
Self-supervising by default: a parent process
|
|
1240
|
-
respawns the SSE loop (via CreateProcess) on any
|
|
1241
|
-
non-clean exit — within-session robustness, not
|
|
1242
|
-
reload-survival. "inbox watch --help" for details.
|
|
1243
|
-
[--project <name>] Filter to one project inbox (default: tenant-wide).
|
|
1244
|
-
[--session <id>] Filter to messages targeting this session
|
|
1245
|
-
(cold opens never wake it — use --receptionist).
|
|
1246
|
-
[--receptionist] Attend the front desk — wake live on a tenant
|
|
1247
|
-
catch-all (cold open / inbound email). Without it,
|
|
1248
|
-
cold opens surface only on a manual inbox check.
|
|
1249
|
-
[--mechanic] Live Mechanic — keep normal session/project
|
|
1250
|
-
delivery AND wake on tenant mechanic_friction events.
|
|
1251
|
-
[--since <id|iso>] Resume after a message id or timestamp.
|
|
1252
|
-
[--json] Emit raw JSON per line (for piping to Monitor).
|
|
1253
|
-
[--quiet] JSON on stdout only (Grok monitor). Auto-on under GROK_SESSION_ID.
|
|
1254
|
-
[--no-supervise] Run the SSE loop directly (no supervisor) — tests/debug.
|
|
1255
|
-
inbox claim <id> Receptionist: claim a front-desk record (cold open /
|
|
1256
|
-
inbound email). First claimant wins; a co-armed
|
|
1257
|
-
receptionist stands down — no double-reply.
|
|
1258
|
-
inbox keep <id> Extend a read message's TTL (default delete after 14 days)
|
|
1259
|
-
inbox delete <id> Permanently delete a message
|
|
1260
|
-
send "body" --to <addr> Send a message. Body is markdown.
|
|
1261
|
-
<addr> is a bare handle (tenant catch-all) or
|
|
1262
|
-
handle/<target> — see Addresses below.
|
|
1263
|
-
send --body-file <path> --to <addr>
|
|
1264
|
-
Send a long/multiline body from a file.
|
|
1265
|
-
send --stdin --to <addr> Read message body from stdin.
|
|
1266
|
-
--from-session <id> Sender's session — denormalized so the recipient can
|
|
1267
|
-
reply by session without re-discovery.
|
|
1268
|
-
--memory <uuid> (repeatable) back-pointer to a memory row
|
|
1269
|
-
--artifact <type:id> (repeatable) e.g. commit:abc123, pr:#42, deploy:def
|
|
1270
|
-
--file <path[:lines]> (repeatable) e.g. src/auth.ts, src/auth.ts:42, src/x.ts:10-15
|
|
1271
|
-
--ref-json '<json>' escape hatch — full references object
|
|
1272
|
-
--in-reply-to <id> Thread a reply back to a front-desk record (cold open /
|
|
1273
|
-
inbound email) — sets references.in_reply_to so the
|
|
1274
|
-
ensuing private line continues that conversation.
|
|
1275
|
-
--to-desk Self-addressed internal mail — posts to THIS project's own
|
|
1276
|
-
desk (no recipient; omit --to). Requires --type.
|
|
1277
|
-
--type <internal-type> Internal messageType for --to-desk (e.g. lore_smell). Queue
|
|
1278
|
-
item drained by its consumer — never wakes a watcher and is
|
|
1279
|
-
hidden from the default inbox (audit via 'inbox --all').
|
|
1280
|
-
retract <code> Pull back a previously-sent message (code is printed on send).
|
|
1281
|
-
discord pair Pair Discord DMs to this project — generates a code to DM the bot.
|
|
1282
|
-
discord unpair Remove the Discord pairing.
|
|
1283
|
-
discord me Show current Discord pairing state.
|
|
1284
|
-
discord typing Refresh the "typing…" indicator on the paired DM thread.
|
|
1285
|
-
send "body" --to discord:<snowflake>
|
|
1286
|
-
Outbound DM to a paired Discord user from any session.
|
|
1287
|
-
Unread → hard delete. Read → body replaced with a retracted notice.
|
|
1288
|
-
Idempotent: double-retract is a no-op.
|
|
1289
|
-
|
|
1290
|
-
Addresses:
|
|
1291
|
-
Cold open: <handle>@greprag.com tenant catch-all — first contact when
|
|
1292
|
-
you don't know their session. Lands in
|
|
1293
|
-
their inbox for a manual check; silent
|
|
1294
|
-
(no session wake, no operator ping).
|
|
1295
|
-
Session: <handle>@greprag.com/<session-uuid> session-to-session (normal, live)
|
|
1296
|
-
Self-desk: --to-desk --type <internal-type> internal queue item on your own project
|
|
1297
|
-
desk — no recipient, no wake; drained by
|
|
1298
|
-
its typed consumer (e.g. lore_smell).
|
|
1299
|
-
--session and --project flags were removed; the address carries the target.
|
|
1300
|
-
Project broadcasts (<handle>@greprag.com/<project-name>) were removed.
|
|
1301
|
-
|
|
1302
|
-
Email (agent-email front desk — drain inbound attachments to local disk):
|
|
1303
|
-
email [pending] List pending front-desk email (envelope only).
|
|
1304
|
-
email pull --id <record> Pull ONE record's attachments to local disk.
|
|
1305
|
-
email pull --all-pending Pull EVERY pending record's attachments.
|
|
1306
|
-
[--to <dir>] Save dir. Default: --to > $GREPRAG_EMAIL_DIR >
|
|
1307
|
-
anchor email_dir > ~/.greprag/email/<project>.
|
|
1308
|
-
[--quiet] Only print the one-line summary.
|
|
1309
|
-
Saved as <subject-slug>-<index>.<ext>; re-pulls
|
|
1310
|
-
are idempotent. Auto-save: set email_autosave=true
|
|
1311
|
-
in .greprag/project.json so the mail hook pulls
|
|
1312
|
-
new attachments each turn.
|
|
1313
|
-
|
|
1314
|
-
Memory (episodic project memory — turn/hourly/daily/ship-event):
|
|
1315
|
-
memory search "<query>" Lexical retrieval over the project's memory.
|
|
1316
|
-
Same v5 RRF + adjacency pipeline as 'corpus
|
|
1317
|
-
search'. Use when looking up a specific
|
|
1318
|
-
problem, bug, or topic.
|
|
1319
|
-
[--limit N=5] [--shape <name>] [--project <name>] [--format markdown|json]
|
|
1320
|
-
memory recap Recent daily summaries (SessionStart shape).
|
|
1321
|
-
[--daily-last N=7] [--project <name>] [--format markdown|json]
|
|
1322
|
-
memory daily [--last N=7] Most-recent daily summaries.
|
|
1323
|
-
memory hourly [--last N=24] Most-recent hourly summaries.
|
|
1324
|
-
memory turns [--last N=20] Raw per-turn envelopes (21-day TTL).
|
|
1325
|
-
memory ships [--last N=50] Ship-event rows (commits/PRs/deploys/releases).
|
|
1326
|
-
Common flags: [--project <name>] [--from ISO --to ISO] [--format markdown|json]
|
|
1327
|
-
memory compact <hour|day|week> [--now ISO]
|
|
1328
|
-
Manual compaction trigger (backfill / admin use).
|
|
1329
|
-
memory delete Bulk-delete nodes by filters (combinable). DRY
|
|
1330
|
-
RUN by default; pass --yes to execute. ≥1 filter
|
|
1331
|
-
required.
|
|
1332
|
-
[--project <name>] [--shape <name>] [--from ISO] [--to ISO] [--session <id>] [--yes]
|
|
1333
|
-
(Aliases: 'briefing' → 'recap' (renamed v5.16.0); 'odyssey' → 'memory'
|
|
1334
|
-
top-level verb (kept for v5.8.0 scripts).)
|
|
1335
|
-
|
|
1336
|
-
Project fixes (emergent friction → fix → repair):
|
|
1337
|
-
fix spawn --type <harness|doctrine|injection|env|code> "<one unit>"
|
|
1338
|
-
[--parent-session <id>]
|
|
1339
|
-
THE friction reflex: emit a FIX CHIP mission for
|
|
1340
|
-
exactly this typed friction, now; the chip investigates,
|
|
1341
|
-
then >=90 repairs autonomously, <90 parks findings.
|
|
1342
|
-
fix log "<text>" [--scope <S>] [--repaired] [--project <name>] [--source-session <id>]
|
|
1343
|
-
Audit/design-input note only, NOT the friction reflex.
|
|
1344
|
-
--repaired records a known durable rule directly
|
|
1345
|
-
(requires --scope).
|
|
1346
|
-
Top-level alias: greprag smell "<text>".
|
|
1347
|
-
fix list [--all] [--repaired] [--project <name>] [--format json]
|
|
1348
|
-
Open queue by default; --repaired = resolved durable
|
|
1349
|
-
rules grouped by scope; --all = tenant-wide census.
|
|
1350
|
-
fix repair <id> "<rule>" [--scope <S>] [--project <name>]
|
|
1351
|
-
Resolve a fix: record the durable rule, close the entry.
|
|
1352
|
-
fix land <id> --commits <h1,h2> --summary "..." [--files <f,..>] [--units <u,..>] [--harness <h,..>]
|
|
1353
|
-
Close a fix with repair-ledger write-back.
|
|
1354
|
-
fix ledger [--limit N] [--project <name>] [--format json]
|
|
1355
|
-
Fleet-activity digest: what chips repaired, when.
|
|
1356
|
-
fix delete <nodeId> [--project <name>]
|
|
1357
|
-
Hard-remove a fix (noise / cleanup).
|
|
1358
|
-
fix search "<query>" [--scope <S>] [--limit N=10] [--project <name>] [--format markdown|json]
|
|
1359
|
-
Lexical search across the project's fixes.
|
|
1360
|
-
fix scopes [--project <name>] Distinct scope labels present in this project.
|
|
1361
|
-
|
|
1362
|
-
Mechanic control plane (repairs as data — 'greprag mechanic --help'):
|
|
1363
|
-
mechanic status [--format json] Inventory of live repairs; ⚑ = ready to graduate.
|
|
1364
|
-
mechanic set | unset Mark / unmark THIS project as the live Mechanic role.
|
|
1365
|
-
mechanic role [status] Show whether THIS project is the live Mechanic.
|
|
1366
|
-
mechanic friction "<summary>" RETIRED: use 'greprag fix spawn --type <type> "<unit>"'.
|
|
1367
|
-
mechanic reply --to <8hex> "<msg>" Reply on the typed mechanic rail.
|
|
1368
|
-
mechanic attest <nodeId> ... Record operator-attested regression evidence.
|
|
1369
|
-
mechanic enable <nodeId> Ratify a shadow repair → active.
|
|
1370
|
-
mechanic disable <nodeId> [--retire] active → shadow (default) or terminal retire.
|
|
1371
|
-
mechanic why <nodeId> Provenance: friction → fix → repair chain.
|
|
1372
|
-
mechanic off | on Panic switch — suspend/resume ALL repairs (local file).
|
|
1373
|
-
|
|
1374
|
-
Corpus (upload + search arbitrary text — books, codebases, references):
|
|
1375
|
-
corpus upload <file|url> --raw|--enriched Create a store + ingest. Mode REQUIRED:
|
|
1376
|
-
[--name <N>] [--kind <K>] --raw (lexical — docs/code) | --enriched (per-node
|
|
1377
|
-
[--refresh hourly|daily|manual|off] LLM vocab bridge — prose/voice). K: docs|
|
|
1378
|
-
prose|transcript|codebase|voice|generic (default docs). html/pdf/docx/
|
|
1379
|
-
xlsx/csv convert server-side. --refresh tracks a URL
|
|
1380
|
-
for the freshness loop (URLs only; default off).
|
|
1381
|
-
search "<query>" [--limit 8] [--kind K] [--store <ref>] [--section "<h>"] [--json]
|
|
1382
|
-
One search across EVERYTHING greprag holds —
|
|
1383
|
-
reference banks, repo markdown, skills, memory.
|
|
1384
|
-
Start here; the corpus forms below are narrower.
|
|
1385
|
-
corpus search <store> "<intent>" [--limit 5] [--section "<h>"] [--shape S]
|
|
1386
|
-
Single-store search. <store> is a UUID or name.
|
|
1387
|
-
corpus search "<intent>" --all|--store <ref>... [--kind K] [--limit 8]
|
|
1388
|
-
Multistore search (RRF-fused). --all = every store.
|
|
1389
|
-
corpus section <store> "<heading>" [--max-chars N]
|
|
1390
|
-
Every node under a heading (forgiving: any depth,
|
|
1391
|
-
dash/case-insensitive).
|
|
1392
|
-
corpus walk <store> <nodeId> [--before 2 --after 2] [--max-chars N]
|
|
1393
|
-
Show a node and its surrounding context. Both
|
|
1394
|
-
print full node text; --max-chars N cuts each node.
|
|
1395
|
-
corpus status <store> Write-side enrichment progress (per-node vocab bridge).
|
|
1396
|
-
corpus refresh <store> Manually re-check a tracked source (re-ingest changed blocks).
|
|
1397
|
-
corpus sources <store> Freshness state: source, policy, last change, next check.
|
|
1398
|
-
corpus list [--kind K] List stores under this tenant.
|
|
1399
|
-
corpus delete <store> [--yes] Delete a store and its nodes.
|
|
1400
|
-
|
|
1401
|
-
Crush (pre-LLM tool-output compression — safe inside pipes, always exits 0):
|
|
1402
|
-
crush --type <log|search|json> [--ccr] [--query "words"]
|
|
1403
|
-
Read stdin, write the crushed version to stdout.
|
|
1404
|
-
log = build/test output (keep errors/traces/summaries),
|
|
1405
|
-
search = grep/rg output (keep scored top matches),
|
|
1406
|
-
json = large arrays (keep errors/outliers/first+last).
|
|
1407
|
-
--ccr stashes the ORIGINAL locally and appends a
|
|
1408
|
-
trailing <<ccr:HASH>> marker. If compression wouldn't
|
|
1409
|
-
save tokens (or input is tiny), stdin passes through
|
|
1410
|
-
verbatim — never breaks the pipe.
|
|
1411
|
-
crush stats Totals + ratios from the pipe-wrap stats log
|
|
1412
|
-
(~/.greprag/crush-stats.jsonl — one record per
|
|
1413
|
-
--stats invocation; the PreToolUse pipe-wrap
|
|
1414
|
-
hook passes --stats on every rewrite).
|
|
1415
|
-
retrieve <hash> Print a CCR-stashed original back to stdout.
|
|
1416
|
-
Store: ~/.greprag/ccr.db (override GREPRAG_CCR_DB).
|
|
1417
|
-
ccr put --type <t> Internal: stash stdin byte-exact in the CCR store,
|
|
1418
|
-
print its 16-hex hash (the opencode inline crusher
|
|
1419
|
-
uses this to persist originals it crushed in-process).
|
|
1420
|
-
|
|
1421
|
-
Archive (governed compact — lossless PNG snapshot of the pre-compact transcript):
|
|
1422
|
-
archive render --transcript <path> [--out-dir <dir>] [--session <8hex>]
|
|
1423
|
-
Render the transcript main chain to pixel-font
|
|
1424
|
-
PNGs (~30K chars/page, pixel round-trip verified)
|
|
1425
|
-
and index pages in the CCR store. The PreCompact
|
|
1426
|
-
hook runs this automatically before compaction.
|
|
1427
|
-
archive list [--session <id>] Indexed archives with page -> turn ranges.
|
|
1428
|
-
archive snippet [--session <id>]
|
|
1429
|
-
Print the documented /compact instruction block
|
|
1430
|
-
(preserve/compress rules + archive pointer line).
|
|
1431
|
-
|
|
1432
|
-
Identity (public handle + vanity alias — real email is auth-only, never a routing address):
|
|
1433
|
-
identity show | whoami Print numeric handle + claimed aliases.
|
|
1434
|
-
identity claim <alias> Claim a vanity alias (e.g. "travis" → travis@greprag.com).
|
|
1435
|
-
identity release <alias> Drop a claimed alias.
|
|
1436
|
-
|
|
1437
|
-
Skills (opt-in advisor skills bundled with the CLI):
|
|
1438
|
-
skill list Show bundled skills and install status
|
|
1439
|
-
skill install <name> Install a bundled advisor (e.g. discord, content-advisor)
|
|
1440
|
-
skill uninstall <name> Remove a previously-installed advisor
|
|
1441
|
-
skill source stamp <name> --project <p> --path <rel> [--path <rel>...] [--baseline <ref>]
|
|
1442
|
-
Stamp a skill-staleness baseline against local Git
|
|
1443
|
-
skill history <name> Every revision of a mirrored skill: date, author, reason, changes
|
|
1444
|
-
skill diff <name> <revA> [<revB>]
|
|
1445
|
-
Unified diff between two revisions (revB defaults to current)
|
|
1446
|
-
|
|
1447
|
-
|
|
1448
|
-
|
|
1449
|
-
|
|
1450
|
-
|
|
1451
|
-
|
|
1452
|
-
|
|
1453
|
-
|
|
1454
|
-
|
|
1455
|
-
|
|
1456
|
-
|
|
1457
|
-
|
|
1458
|
-
loadout
|
|
1459
|
-
|
|
1460
|
-
loadout
|
|
1461
|
-
|
|
1462
|
-
loadout
|
|
1463
|
-
|
|
1464
|
-
|
|
1465
|
-
|
|
1466
|
-
|
|
1467
|
-
|
|
1468
|
-
persona
|
|
1469
|
-
|
|
1470
|
-
persona
|
|
1471
|
-
|
|
1472
|
-
|
|
1473
|
-
|
|
1474
|
-
|
|
1475
|
-
|
|
1476
|
-
|
|
1477
|
-
|
|
1478
|
-
|
|
1479
|
-
|
|
1480
|
-
|
|
1481
|
-
|
|
1482
|
-
|
|
1483
|
-
|
|
1484
|
-
|
|
1485
|
-
|
|
1486
|
-
|
|
1487
|
-
|
|
1488
|
-
|
|
1489
|
-
|
|
1490
|
-
|
|
1491
|
-
|
|
1492
|
-
|
|
1493
|
-
|
|
1494
|
-
|
|
1495
|
-
|
|
1496
|
-
|
|
1497
|
-
|
|
1498
|
-
|
|
1499
|
-
|
|
1500
|
-
|
|
1501
|
-
|
|
1502
|
-
|
|
1503
|
-
|
|
1504
|
-
|
|
1505
|
-
|
|
1506
|
-
greprag
|
|
1507
|
-
greprag init
|
|
1508
|
-
greprag init --
|
|
1509
|
-
greprag
|
|
1510
|
-
greprag
|
|
1511
|
-
|
|
1512
|
-
greprag send "
|
|
1513
|
-
#
|
|
1514
|
-
greprag send "
|
|
1515
|
-
|
|
1516
|
-
greprag send "Bug in auth flow — repro at line 42" --to alice@greprag.com/abc12345 \
|
|
1517
|
-
--file src/auth.ts:42 --artifact commit:abc123
|
|
1154
|
+
const HELP = `
|
|
1155
|
+
greprag — agent memory for Claude Code, Codex, OpenCode, and Grok Build
|
|
1156
|
+
|
|
1157
|
+
Commands:
|
|
1158
|
+
(no command) Open the local GrepRAG app
|
|
1159
|
+
app | dashboard [--port N] Open the local app (use --no-open on remote machines)
|
|
1160
|
+
init [--api-key <existing-key>]
|
|
1161
|
+
Auto-detect/ask for Codex, Claude Code, or OpenCode
|
|
1162
|
+
init --claude [--api-key <existing-key>]
|
|
1163
|
+
Configure hooks + API key for Claude Code
|
|
1164
|
+
init --global [--name <name>] Create ~/.greprag/project.json (global anchor)
|
|
1165
|
+
init --opencode [--api-key <existing-key>]
|
|
1166
|
+
Configure plugin + anchor for OpenCode
|
|
1167
|
+
init --codex [--api-key <existing-key>]
|
|
1168
|
+
Configure lifecycle hooks + anchor for Codex
|
|
1169
|
+
init --grok [--api-key <existing-key>]
|
|
1170
|
+
Configure Grok Build hooks + skill + rules
|
|
1171
|
+
grok spawn [--cwd <path>] [--prompt "<text>"]
|
|
1172
|
+
Open a fresh Grok TUI in a new terminal
|
|
1173
|
+
(Windows schtasks bootloader — survives the
|
|
1174
|
+
tool Job Object; child arms its own watch)
|
|
1175
|
+
init --all [--root <path>] Standard init for cwd, then bulk-register every
|
|
1176
|
+
other git repo at depth 1 under <path> (default:
|
|
1177
|
+
parent of repo root). Each becomes inbox-addressable.
|
|
1178
|
+
status [--json] [--claude|--codex|--opencode|--grok]
|
|
1179
|
+
Installation, auth, platform hooks/plugins, and project state
|
|
1180
|
+
announce [--session <8hex>] [--path]
|
|
1181
|
+
Print the full SessionStart announce (the harness
|
|
1182
|
+
inlines only ~2KB; the rest is parked on disk)
|
|
1183
|
+
codex doctor Diagnose Codex hooks, trust setup, and current thread
|
|
1184
|
+
project-id Print the current project_id
|
|
1185
|
+
session-id [--full] Print this session's id (8-hex, 16-hex for UUIDv7, or full UUID with --full).
|
|
1186
|
+
discover [--json] Tenant-wide structure: every project, per-shape row counts,
|
|
1187
|
+
activity ranges. For cross-project advisors.
|
|
1188
|
+
doc <command> Mirror, search, and read project Markdown docs.
|
|
1189
|
+
docptr <command> Document-pointer registry and reference backfill.
|
|
1190
|
+
parity [seed] Doctrine drift-from-canon: the parity table (unit ·
|
|
1191
|
+
lead · stale followers), plus the operator-run seed.
|
|
1192
|
+
repodoc <index|status> Stable identity for a repo's own Markdown: blocks keep
|
|
1193
|
+
their ids through edits, splits, merges and renames.
|
|
1194
|
+
instructions <render|status>
|
|
1195
|
+
Render Codex/OpenCode AGENTS.md from the git CLAUDE.md.
|
|
1196
|
+
doctor [--inspect] [--yes] Diagnose + repair orphan project_ids and identity drift
|
|
1197
|
+
desk <run|ensure|status> The desk line: this machine answers which sessions
|
|
1198
|
+
are live when the cloud asks.
|
|
1199
|
+
smell "<text>" Shortcut for \`greprag fix log "<text>"\`.
|
|
1200
|
+
context status [--session <id>] Context-size governor readout: live tokens, threshold,
|
|
1201
|
+
% consumed, turns since the crossover advisory last fired.
|
|
1202
|
+
"context --help" for config (threshold + off-switch).
|
|
1203
|
+
delivery <command> Resolve and inspect repo delivery profiles.
|
|
1204
|
+
deploy-gate [--target <id>] Repo-independent deploy pre-flight: may a deploy run
|
|
1205
|
+
from here, is one already running, what is shipping.
|
|
1206
|
+
Read-only; the artifact proof stays with the repo.
|
|
1207
|
+
merge-lock <acquire|release|status> Serialise merges into a shared canonical
|
|
1208
|
+
checkout. Take it before you merge, release after.
|
|
1209
|
+
deploy-lock <acquire|release|status> --target <id>
|
|
1210
|
+
One deploy at a time per target. Pass --pid so the
|
|
1211
|
+
lock names the deploying process, not this command.
|
|
1212
|
+
deploy-record --target <id> Remember what this checkout last shipped, so the
|
|
1213
|
+
gate can say what a deploy is about to ship.
|
|
1214
|
+
deploy-verify --origin <url> --sha <commit>
|
|
1215
|
+
Prove production is serving the commit you shipped.
|
|
1216
|
+
Refuses if the build stamp is edge-cacheable.
|
|
1217
|
+
procedure <command> Governed operational procedure watches and runs.
|
|
1218
|
+
skillgain <command> Skill-learning queue and installation helpers.
|
|
1219
|
+
|
|
1220
|
+
Inbox (email-style messaging across tenants):
|
|
1221
|
+
inbox [--all] [--front-desk] [--session <id>] [--project <name>] [--peek]
|
|
1222
|
+
List unread, auto-scoped to THIS session: its own
|
|
1223
|
+
lines (sender OR recipient) only. Other sessions'
|
|
1224
|
+
private lines AND the front desk are hidden by
|
|
1225
|
+
default — the front desk (cold opens + inbound
|
|
1226
|
+
email) is opt-in via --front-desk.
|
|
1227
|
+
--all = audit peek: drop the per-session scope
|
|
1228
|
+
(every session's lines) AND include read history.
|
|
1229
|
+
--session scopes to one specific session's view.
|
|
1230
|
+
--project filters by project name.
|
|
1231
|
+
--peek: NON-MUTATING — does not mark any message read.
|
|
1232
|
+
inbox watchers [--json] List currently-attached live watchers
|
|
1233
|
+
(Claude / Codex / OpenCode / Grok). Each row:
|
|
1234
|
+
project · title (session_id) [platform] repo —
|
|
1235
|
+
project + nano title from session memory, repo
|
|
1236
|
+
from ~/.greprag/projects.json. Codex task
|
|
1237
|
+
discovery also uses codex_app.list_threads.
|
|
1238
|
+
inbox watch Long-lived SSE stream — prints each message as it lands.
|
|
1239
|
+
Self-supervising by default: a parent process
|
|
1240
|
+
respawns the SSE loop (via CreateProcess) on any
|
|
1241
|
+
non-clean exit — within-session robustness, not
|
|
1242
|
+
reload-survival. "inbox watch --help" for details.
|
|
1243
|
+
[--project <name>] Filter to one project inbox (default: tenant-wide).
|
|
1244
|
+
[--session <id>] Filter to messages targeting this session
|
|
1245
|
+
(cold opens never wake it — use --receptionist).
|
|
1246
|
+
[--receptionist] Attend the front desk — wake live on a tenant
|
|
1247
|
+
catch-all (cold open / inbound email). Without it,
|
|
1248
|
+
cold opens surface only on a manual inbox check.
|
|
1249
|
+
[--mechanic] Live Mechanic — keep normal session/project
|
|
1250
|
+
delivery AND wake on tenant mechanic_friction events.
|
|
1251
|
+
[--since <id|iso>] Resume after a message id or timestamp.
|
|
1252
|
+
[--json] Emit raw JSON per line (for piping to Monitor).
|
|
1253
|
+
[--quiet] JSON on stdout only (Grok monitor). Auto-on under GROK_SESSION_ID.
|
|
1254
|
+
[--no-supervise] Run the SSE loop directly (no supervisor) — tests/debug.
|
|
1255
|
+
inbox claim <id> Receptionist: claim a front-desk record (cold open /
|
|
1256
|
+
inbound email). First claimant wins; a co-armed
|
|
1257
|
+
receptionist stands down — no double-reply.
|
|
1258
|
+
inbox keep <id> Extend a read message's TTL (default delete after 14 days)
|
|
1259
|
+
inbox delete <id> Permanently delete a message
|
|
1260
|
+
send "body" --to <addr> Send a message. Body is markdown.
|
|
1261
|
+
<addr> is a bare handle (tenant catch-all) or
|
|
1262
|
+
handle/<target> — see Addresses below.
|
|
1263
|
+
send --body-file <path> --to <addr>
|
|
1264
|
+
Send a long/multiline body from a file.
|
|
1265
|
+
send --stdin --to <addr> Read message body from stdin.
|
|
1266
|
+
--from-session <id> Sender's session — denormalized so the recipient can
|
|
1267
|
+
reply by session without re-discovery.
|
|
1268
|
+
--memory <uuid> (repeatable) back-pointer to a memory row
|
|
1269
|
+
--artifact <type:id> (repeatable) e.g. commit:abc123, pr:#42, deploy:def
|
|
1270
|
+
--file <path[:lines]> (repeatable) e.g. src/auth.ts, src/auth.ts:42, src/x.ts:10-15
|
|
1271
|
+
--ref-json '<json>' escape hatch — full references object
|
|
1272
|
+
--in-reply-to <id> Thread a reply back to a front-desk record (cold open /
|
|
1273
|
+
inbound email) — sets references.in_reply_to so the
|
|
1274
|
+
ensuing private line continues that conversation.
|
|
1275
|
+
--to-desk Self-addressed internal mail — posts to THIS project's own
|
|
1276
|
+
desk (no recipient; omit --to). Requires --type.
|
|
1277
|
+
--type <internal-type> Internal messageType for --to-desk (e.g. lore_smell). Queue
|
|
1278
|
+
item drained by its consumer — never wakes a watcher and is
|
|
1279
|
+
hidden from the default inbox (audit via 'inbox --all').
|
|
1280
|
+
retract <code> Pull back a previously-sent message (code is printed on send).
|
|
1281
|
+
discord pair Pair Discord DMs to this project — generates a code to DM the bot.
|
|
1282
|
+
discord unpair Remove the Discord pairing.
|
|
1283
|
+
discord me Show current Discord pairing state.
|
|
1284
|
+
discord typing Refresh the "typing…" indicator on the paired DM thread.
|
|
1285
|
+
send "body" --to discord:<snowflake>
|
|
1286
|
+
Outbound DM to a paired Discord user from any session.
|
|
1287
|
+
Unread → hard delete. Read → body replaced with a retracted notice.
|
|
1288
|
+
Idempotent: double-retract is a no-op.
|
|
1289
|
+
|
|
1290
|
+
Addresses:
|
|
1291
|
+
Cold open: <handle>@greprag.com tenant catch-all — first contact when
|
|
1292
|
+
you don't know their session. Lands in
|
|
1293
|
+
their inbox for a manual check; silent
|
|
1294
|
+
(no session wake, no operator ping).
|
|
1295
|
+
Session: <handle>@greprag.com/<session-uuid> session-to-session (normal, live)
|
|
1296
|
+
Self-desk: --to-desk --type <internal-type> internal queue item on your own project
|
|
1297
|
+
desk — no recipient, no wake; drained by
|
|
1298
|
+
its typed consumer (e.g. lore_smell).
|
|
1299
|
+
--session and --project flags were removed; the address carries the target.
|
|
1300
|
+
Project broadcasts (<handle>@greprag.com/<project-name>) were removed.
|
|
1301
|
+
|
|
1302
|
+
Email (agent-email front desk — drain inbound attachments to local disk):
|
|
1303
|
+
email [pending] List pending front-desk email (envelope only).
|
|
1304
|
+
email pull --id <record> Pull ONE record's attachments to local disk.
|
|
1305
|
+
email pull --all-pending Pull EVERY pending record's attachments.
|
|
1306
|
+
[--to <dir>] Save dir. Default: --to > $GREPRAG_EMAIL_DIR >
|
|
1307
|
+
anchor email_dir > ~/.greprag/email/<project>.
|
|
1308
|
+
[--quiet] Only print the one-line summary.
|
|
1309
|
+
Saved as <subject-slug>-<index>.<ext>; re-pulls
|
|
1310
|
+
are idempotent. Auto-save: set email_autosave=true
|
|
1311
|
+
in .greprag/project.json so the mail hook pulls
|
|
1312
|
+
new attachments each turn.
|
|
1313
|
+
|
|
1314
|
+
Memory (episodic project memory — turn/hourly/daily/ship-event):
|
|
1315
|
+
memory search "<query>" Lexical retrieval over the project's memory.
|
|
1316
|
+
Same v5 RRF + adjacency pipeline as 'corpus
|
|
1317
|
+
search'. Use when looking up a specific
|
|
1318
|
+
problem, bug, or topic.
|
|
1319
|
+
[--limit N=5] [--shape <name>] [--project <name>] [--format markdown|json]
|
|
1320
|
+
memory recap Recent daily summaries (SessionStart shape).
|
|
1321
|
+
[--daily-last N=7] [--project <name>] [--format markdown|json]
|
|
1322
|
+
memory daily [--last N=7] Most-recent daily summaries.
|
|
1323
|
+
memory hourly [--last N=24] Most-recent hourly summaries.
|
|
1324
|
+
memory turns [--last N=20] Raw per-turn envelopes (21-day TTL).
|
|
1325
|
+
memory ships [--last N=50] Ship-event rows (commits/PRs/deploys/releases).
|
|
1326
|
+
Common flags: [--project <name>] [--from ISO --to ISO] [--format markdown|json]
|
|
1327
|
+
memory compact <hour|day|week> [--now ISO]
|
|
1328
|
+
Manual compaction trigger (backfill / admin use).
|
|
1329
|
+
memory delete Bulk-delete nodes by filters (combinable). DRY
|
|
1330
|
+
RUN by default; pass --yes to execute. ≥1 filter
|
|
1331
|
+
required.
|
|
1332
|
+
[--project <name>] [--shape <name>] [--from ISO] [--to ISO] [--session <id>] [--yes]
|
|
1333
|
+
(Aliases: 'briefing' → 'recap' (renamed v5.16.0); 'odyssey' → 'memory'
|
|
1334
|
+
top-level verb (kept for v5.8.0 scripts).)
|
|
1335
|
+
|
|
1336
|
+
Project fixes (emergent friction → fix → repair):
|
|
1337
|
+
fix spawn --type <harness|doctrine|injection|env|code> "<one unit>"
|
|
1338
|
+
[--parent-session <id>]
|
|
1339
|
+
THE friction reflex: emit a FIX CHIP mission for
|
|
1340
|
+
exactly this typed friction, now; the chip investigates,
|
|
1341
|
+
then >=90 repairs autonomously, <90 parks findings.
|
|
1342
|
+
fix log "<text>" [--scope <S>] [--repaired] [--project <name>] [--source-session <id>]
|
|
1343
|
+
Audit/design-input note only, NOT the friction reflex.
|
|
1344
|
+
--repaired records a known durable rule directly
|
|
1345
|
+
(requires --scope).
|
|
1346
|
+
Top-level alias: greprag smell "<text>".
|
|
1347
|
+
fix list [--all] [--repaired] [--project <name>] [--format json]
|
|
1348
|
+
Open queue by default; --repaired = resolved durable
|
|
1349
|
+
rules grouped by scope; --all = tenant-wide census.
|
|
1350
|
+
fix repair <id> "<rule>" [--scope <S>] [--project <name>]
|
|
1351
|
+
Resolve a fix: record the durable rule, close the entry.
|
|
1352
|
+
fix land <id> --commits <h1,h2> --summary "..." [--files <f,..>] [--units <u,..>] [--harness <h,..>]
|
|
1353
|
+
Close a fix with repair-ledger write-back.
|
|
1354
|
+
fix ledger [--limit N] [--project <name>] [--format json]
|
|
1355
|
+
Fleet-activity digest: what chips repaired, when.
|
|
1356
|
+
fix delete <nodeId> [--project <name>]
|
|
1357
|
+
Hard-remove a fix (noise / cleanup).
|
|
1358
|
+
fix search "<query>" [--scope <S>] [--limit N=10] [--project <name>] [--format markdown|json]
|
|
1359
|
+
Lexical search across the project's fixes.
|
|
1360
|
+
fix scopes [--project <name>] Distinct scope labels present in this project.
|
|
1361
|
+
|
|
1362
|
+
Mechanic control plane (repairs as data — 'greprag mechanic --help'):
|
|
1363
|
+
mechanic status [--format json] Inventory of live repairs; ⚑ = ready to graduate.
|
|
1364
|
+
mechanic set | unset Mark / unmark THIS project as the live Mechanic role.
|
|
1365
|
+
mechanic role [status] Show whether THIS project is the live Mechanic.
|
|
1366
|
+
mechanic friction "<summary>" RETIRED: use 'greprag fix spawn --type <type> "<unit>"'.
|
|
1367
|
+
mechanic reply --to <8hex> "<msg>" Reply on the typed mechanic rail.
|
|
1368
|
+
mechanic attest <nodeId> ... Record operator-attested regression evidence.
|
|
1369
|
+
mechanic enable <nodeId> Ratify a shadow repair → active.
|
|
1370
|
+
mechanic disable <nodeId> [--retire] active → shadow (default) or terminal retire.
|
|
1371
|
+
mechanic why <nodeId> Provenance: friction → fix → repair chain.
|
|
1372
|
+
mechanic off | on Panic switch — suspend/resume ALL repairs (local file).
|
|
1373
|
+
|
|
1374
|
+
Corpus (upload + search arbitrary text — books, codebases, references):
|
|
1375
|
+
corpus upload <file|url> --raw|--enriched Create a store + ingest. Mode REQUIRED:
|
|
1376
|
+
[--name <N>] [--kind <K>] --raw (lexical — docs/code) | --enriched (per-node
|
|
1377
|
+
[--refresh hourly|daily|manual|off] LLM vocab bridge — prose/voice). K: docs|
|
|
1378
|
+
prose|transcript|codebase|voice|generic (default docs). html/pdf/docx/
|
|
1379
|
+
xlsx/csv convert server-side. --refresh tracks a URL
|
|
1380
|
+
for the freshness loop (URLs only; default off).
|
|
1381
|
+
search "<query>" [--limit 8] [--kind K] [--store <ref>] [--section "<h>"] [--json]
|
|
1382
|
+
One search across EVERYTHING greprag holds —
|
|
1383
|
+
reference banks, repo markdown, skills, memory.
|
|
1384
|
+
Start here; the corpus forms below are narrower.
|
|
1385
|
+
corpus search <store> "<intent>" [--limit 5] [--section "<h>"] [--shape S]
|
|
1386
|
+
Single-store search. <store> is a UUID or name.
|
|
1387
|
+
corpus search "<intent>" --all|--store <ref>... [--kind K] [--limit 8]
|
|
1388
|
+
Multistore search (RRF-fused). --all = every store.
|
|
1389
|
+
corpus section <store> "<heading>" [--max-chars N]
|
|
1390
|
+
Every node under a heading (forgiving: any depth,
|
|
1391
|
+
dash/case-insensitive).
|
|
1392
|
+
corpus walk <store> <nodeId> [--before 2 --after 2] [--max-chars N]
|
|
1393
|
+
Show a node and its surrounding context. Both
|
|
1394
|
+
print full node text; --max-chars N cuts each node.
|
|
1395
|
+
corpus status <store> Write-side enrichment progress (per-node vocab bridge).
|
|
1396
|
+
corpus refresh <store> Manually re-check a tracked source (re-ingest changed blocks).
|
|
1397
|
+
corpus sources <store> Freshness state: source, policy, last change, next check.
|
|
1398
|
+
corpus list [--kind K] List stores under this tenant.
|
|
1399
|
+
corpus delete <store> [--yes] Delete a store and its nodes.
|
|
1400
|
+
|
|
1401
|
+
Crush (pre-LLM tool-output compression — safe inside pipes, always exits 0):
|
|
1402
|
+
crush --type <log|search|json> [--ccr] [--query "words"]
|
|
1403
|
+
Read stdin, write the crushed version to stdout.
|
|
1404
|
+
log = build/test output (keep errors/traces/summaries),
|
|
1405
|
+
search = grep/rg output (keep scored top matches),
|
|
1406
|
+
json = large arrays (keep errors/outliers/first+last).
|
|
1407
|
+
--ccr stashes the ORIGINAL locally and appends a
|
|
1408
|
+
trailing <<ccr:HASH>> marker. If compression wouldn't
|
|
1409
|
+
save tokens (or input is tiny), stdin passes through
|
|
1410
|
+
verbatim — never breaks the pipe.
|
|
1411
|
+
crush stats Totals + ratios from the pipe-wrap stats log
|
|
1412
|
+
(~/.greprag/crush-stats.jsonl — one record per
|
|
1413
|
+
--stats invocation; the PreToolUse pipe-wrap
|
|
1414
|
+
hook passes --stats on every rewrite).
|
|
1415
|
+
retrieve <hash> Print a CCR-stashed original back to stdout.
|
|
1416
|
+
Store: ~/.greprag/ccr.db (override GREPRAG_CCR_DB).
|
|
1417
|
+
ccr put --type <t> Internal: stash stdin byte-exact in the CCR store,
|
|
1418
|
+
print its 16-hex hash (the opencode inline crusher
|
|
1419
|
+
uses this to persist originals it crushed in-process).
|
|
1420
|
+
|
|
1421
|
+
Archive (governed compact — lossless PNG snapshot of the pre-compact transcript):
|
|
1422
|
+
archive render --transcript <path> [--out-dir <dir>] [--session <8hex>]
|
|
1423
|
+
Render the transcript main chain to pixel-font
|
|
1424
|
+
PNGs (~30K chars/page, pixel round-trip verified)
|
|
1425
|
+
and index pages in the CCR store. The PreCompact
|
|
1426
|
+
hook runs this automatically before compaction.
|
|
1427
|
+
archive list [--session <id>] Indexed archives with page -> turn ranges.
|
|
1428
|
+
archive snippet [--session <id>]
|
|
1429
|
+
Print the documented /compact instruction block
|
|
1430
|
+
(preserve/compress rules + archive pointer line).
|
|
1431
|
+
|
|
1432
|
+
Identity (public handle + vanity alias — real email is auth-only, never a routing address):
|
|
1433
|
+
identity show | whoami Print numeric handle + claimed aliases.
|
|
1434
|
+
identity claim <alias> Claim a vanity alias (e.g. "travis" → travis@greprag.com).
|
|
1435
|
+
identity release <alias> Drop a claimed alias.
|
|
1436
|
+
|
|
1437
|
+
Skills (opt-in advisor skills bundled with the CLI):
|
|
1438
|
+
skill list Show bundled skills and install status
|
|
1439
|
+
skill install <name> Install a bundled advisor (e.g. discord, content-advisor)
|
|
1440
|
+
skill uninstall <name> Remove a previously-installed advisor
|
|
1441
|
+
skill source stamp <name> --project <p> --path <rel> [--path <rel>...] [--baseline <ref>]
|
|
1442
|
+
Stamp a skill-staleness baseline against local Git
|
|
1443
|
+
skill history <name> Every revision of a mirrored skill: date, author, reason, changes
|
|
1444
|
+
skill diff <name> <revA> [<revB>]
|
|
1445
|
+
Unified diff between two revisions (revB defaults to current)
|
|
1446
|
+
|
|
1447
|
+
Load (on-demand doctrine — the CLI is the payload, no .md files):
|
|
1448
|
+
load Browse the catalog (chip-spawn, codex chips, mechanic, …)
|
|
1449
|
+
load <name> Print that entry's full method inline
|
|
1450
|
+
|
|
1451
|
+
Loadout (gift a skill bundle to another tenant — offer, never auto-install):
|
|
1452
|
+
loadout send --to <handle>@greprag.com --skill <name> [--skill <n> …]
|
|
1453
|
+
[--dir <path>] [--advisor <name>] [--note "…"]
|
|
1454
|
+
Freeze + send a loadout. --skill pulls from your
|
|
1455
|
+
mirror; --dir snapshots a skill dir from disk.
|
|
1456
|
+
loadout list Offered loadouts waiting at your front desk.
|
|
1457
|
+
loadout open <id> Manifest + a bounded content preview (never ingests).
|
|
1458
|
+
loadout equip <id> Equip it (alias: accept) — copies skills to your load
|
|
1459
|
+
store + self-inflates via 'greprag load'.
|
|
1460
|
+
loadout decline <id> Decline — GCs the snapshot.
|
|
1461
|
+
loadout status Loadouts you've sent (offered/equipped/declined).
|
|
1462
|
+
loadout unequip <name> [--delete-skills]
|
|
1463
|
+
Stop a loadout's auto-inflate.
|
|
1464
|
+
|
|
1465
|
+
Persona (tenant-scoped speaking instructions):
|
|
1466
|
+
persona list List built-in Persona templates.
|
|
1467
|
+
persona use <template> Activate a built-in Persona template.
|
|
1468
|
+
persona set <text>|--file <f>|--stdin
|
|
1469
|
+
Save and activate a custom Persona verbatim.
|
|
1470
|
+
persona show Show the active Persona.
|
|
1471
|
+
persona clear Remove the active Persona.
|
|
1472
|
+
|
|
1473
|
+
Instructions (~/.claude/CLAUDE.md in the dotclaude git repo is the source):
|
|
1474
|
+
instructions render [--check] Write ~/.codex/AGENTS.md and
|
|
1475
|
+
~/.config/opencode/AGENTS.md from the git CLAUDE.md
|
|
1476
|
+
plus ~/.claude/instructions/<harness>.md.
|
|
1477
|
+
instructions status Show whether each rendered file is current.
|
|
1478
|
+
agents ... Deprecated alias for instructions.
|
|
1479
|
+
|
|
1480
|
+
Project metadata (rename / merge / list):
|
|
1481
|
+
project rename <new-name> [--yes]
|
|
1482
|
+
Rename the project at cwd (anchor + registry + API
|
|
1483
|
+
+ store metadata). Confirms before writing.
|
|
1484
|
+
project merge --from <X> --into <Y> [--apply] [--name <override>] [--json]
|
|
1485
|
+
Consolidate one project into another. Defaults to
|
|
1486
|
+
dry-run. --from/--into accept a UUID or project_name.
|
|
1487
|
+
--name renames the target in the same step.
|
|
1488
|
+
project list [--json] Every project under this tenant, with anchor + rows.
|
|
1489
|
+
|
|
1490
|
+
Opencode (bridge inbox SSE into a running opencode desktop session — the
|
|
1491
|
+
Monitor equivalent, since opencode is turn-based by default):
|
|
1492
|
+
opencode relay --session <id> [options]
|
|
1493
|
+
Subscribe to /v1/inbox/stream and inject each
|
|
1494
|
+
message as a fresh turn in the named opencode
|
|
1495
|
+
desktop session via /session/{id}/prompt_async.
|
|
1496
|
+
See \`greprag opencode --help\` for flags.
|
|
1497
|
+
|
|
1498
|
+
Other:
|
|
1499
|
+
expand --chunk <id> Expand a memory cluster (siblings, adjacent, linked)
|
|
1500
|
+
help [--all] Show this overview. --all appends every command's
|
|
1501
|
+
full --help — the complete, always-current guide.
|
|
1502
|
+
|
|
1503
|
+
Examples:
|
|
1504
|
+
greprag # open the local customer app
|
|
1505
|
+
greprag init # standard repo setup
|
|
1506
|
+
greprag init --global # Cowork / unanchored sessions
|
|
1507
|
+
greprag init --all # register every sibling repo for inbox
|
|
1508
|
+
greprag init --all --root C:\\ # scan a specific directory
|
|
1509
|
+
greprag inbox
|
|
1510
|
+
greprag send "done with migration" --to alice@greprag.com/abc12345
|
|
1511
|
+
# session-targeted (normal)
|
|
1512
|
+
greprag send "deploy approved" --to alice@greprag.com
|
|
1513
|
+
# cold open — alice's front desk
|
|
1514
|
+
greprag send "Bug in auth flow — repro at line 42" --to alice@greprag.com/abc12345 \
|
|
1515
|
+
--file src/auth.ts:42 --artifact commit:abc123
|
|
1518
1516
|
`.trim();
|
|
1519
1517
|
/** Groups that ship their own detailed `--help`. A help flag anywhere after one
|
|
1520
1518
|
* of these prints it (printCommandHelp), and `help --all` invokes each one
|
|
@@ -1561,125 +1559,125 @@ const HELP_GROUPS = [
|
|
|
1561
1559
|
['loadout', loadout_1.runLoadout],
|
|
1562
1560
|
['skillgain', skillgain_1.runSkillGain],
|
|
1563
1561
|
];
|
|
1564
|
-
const OPENCODE_HELP = `greprag opencode — bridge greprag inbox into a running opencode desktop
|
|
1565
|
-
session, plus a file-watching capture pipeline for episodic memory.
|
|
1566
|
-
|
|
1567
|
-
Two subcommands:
|
|
1568
|
-
|
|
1569
|
-
greprag opencode relay Bridge greprag inbox into a running opencode
|
|
1570
|
-
desktop session. Single POST to
|
|
1571
|
-
/session/{id}/prompt_async enqueues a fresh turn;
|
|
1572
|
-
the desktop app renders it into the conversation
|
|
1573
|
-
feed via the same SSE channel the engine uses.
|
|
1574
|
-
Desktop-only by design — the TUI control plane
|
|
1575
|
-
is deprecated.
|
|
1576
|
-
|
|
1577
|
-
Session-to-session by default: the relay derives
|
|
1578
|
-
the greprag 8-hex from the opencode session UUID
|
|
1579
|
-
and filters the inbox stream to only messages
|
|
1580
|
-
addressed to THIS session. Use --tenant-wide to
|
|
1581
|
-
opt into the noisy debug mode (every message in
|
|
1582
|
-
the tenant, including messages for other
|
|
1583
|
-
sessions).
|
|
1584
|
-
|
|
1585
|
-
greprag opencode chip Spawn OpenCode Desktop chips (session.create + prompt_async).
|
|
1586
|
-
greprag opencode watch Long-lived SQLite poller on opencode's local DB.
|
|
1587
|
-
Captures every (user, assistant) turn pair to
|
|
1588
|
-
greprag memory. Bypasses opencode's event bus
|
|
1589
|
-
entirely — reads the same rows the engine writes
|
|
1590
|
-
the moment a turn completes.
|
|
1591
|
-
|
|
1592
|
-
opencode is turn-based: it has no built-in "Monitor" tool like Claude Code.
|
|
1593
|
-
\`relay\` is the bridge for live inbox delivery. \`watch\` is the capture
|
|
1594
|
-
pipeline. Run both, in separate processes, as long-lived siblings.
|
|
1595
|
-
|
|
1596
|
-
opencode relay — bridge greprag inbox into a running opencode desktop
|
|
1597
|
-
session.
|
|
1598
|
-
|
|
1599
|
-
This command subscribes to /v1/inbox/stream (same SSE channel inbox watch
|
|
1600
|
-
uses) and POSTs every inbound message to /session/{id}/prompt_async on
|
|
1601
|
-
the running opencode server. The receiving desktop session renders the
|
|
1602
|
-
injected prompt as a fresh turn in its conversation feed.
|
|
1603
|
-
|
|
1604
|
-
Usage:
|
|
1605
|
-
greprag opencode relay --session <opencode-session-id> [options]
|
|
1606
|
-
|
|
1607
|
-
Required:
|
|
1608
|
-
--session <id> opencode session id (UUID). Find via
|
|
1609
|
-
\`opencode session list\` or the session header in
|
|
1610
|
-
the opencode UI.
|
|
1611
|
-
|
|
1612
|
-
Options:
|
|
1613
|
-
--opencode-url <u> opencode server base URL.
|
|
1614
|
-
Default http://127.0.0.1:4096.
|
|
1615
|
-
Env override: OPENCODE_URL.
|
|
1616
|
-
--project <name> Filter the inbox stream to one project.
|
|
1617
|
-
--inbox-session <8hex> Filter to one greprag session (8-hex id). Default
|
|
1618
|
-
is auto-derived from --session (truncateSessionId)
|
|
1619
|
-
so the relay only sees messages addressed to THIS
|
|
1620
|
-
opencode session. Pass explicitly to override
|
|
1621
|
-
(e.g. share one greprag session across multiple
|
|
1622
|
-
opencode sessions).
|
|
1623
|
-
--tenant-wide See every message in the tenant's inbox stream,
|
|
1624
|
-
including messages addressed to other sessions.
|
|
1625
|
-
Debug flag — noisy, usually wrong.
|
|
1626
|
-
--since <id-or-iso> Resume cursor.
|
|
1627
|
-
--print Pretty-print each message to stdout.
|
|
1628
|
-
--dry-run Resolve + format, do not POST.
|
|
1629
|
-
|
|
1630
|
-
Resilience mirrors inbox-watch: exponential backoff, idle timeout,
|
|
1631
|
-
cursor-preserving reconnect. Production wraps this in a \`while true\` shell
|
|
1632
|
-
loop so process death auto-restarts:
|
|
1633
|
-
|
|
1634
|
-
while true; do greprag opencode relay --session <id>; \\
|
|
1635
|
-
echo "[restart]" >&2; sleep 1; done
|
|
1636
|
-
|
|
1637
|
-
Senders reach THIS session by addressing
|
|
1638
|
-
\`<handle>@greprag.com/<8hex>\` where <8hex> is the first 8 hex chars of the
|
|
1639
|
-
opencode session id (or pass \`--from-session <8hex>\` so the recipient can
|
|
1640
|
-
reply back by session without re-discovering it).
|
|
1641
|
-
|
|
1642
|
-
|
|
1643
|
-
opencode watch — SQLite-polling turn capture for episodic memory.
|
|
1644
|
-
|
|
1645
|
-
opencode persists every message + part as a row in
|
|
1646
|
-
%USERPROFILE%\\.local\\share\\opencode\\opencode.db (SQLite, WAL mode)
|
|
1647
|
-
the moment the AI finishes streaming. This command polls that DB every
|
|
1648
|
-
1-2s, joins \`message\` to \`session\` to recover the working directory,
|
|
1649
|
-
walks up to the greprag anchor, and POSTs the (user, assistant) pair to
|
|
1650
|
-
/v1/memory/turn. No event bus. No sidecar auth. No plugin loader.
|
|
1651
|
-
|
|
1652
|
-
Why this exists: opencode Desktop's event bus does not reliably emit
|
|
1653
|
-
\`message.updated\` for the user's active session, so a plugin hook is
|
|
1654
|
-
unreliable for capture. The on-disk DB is the source of truth — it is
|
|
1655
|
-
written by the engine itself the moment a turn completes.
|
|
1656
|
-
|
|
1657
|
-
Usage:
|
|
1658
|
-
greprag opencode watch [options]
|
|
1659
|
-
|
|
1660
|
-
Options:
|
|
1661
|
-
--interval <ms> Poll interval. Default 1500.
|
|
1662
|
-
--db <path> Override DB path. Default
|
|
1663
|
-
%USERPROFILE%\\.local\\share\\opencode\\opencode.db
|
|
1664
|
-
--project <dir> Only capture turns whose session.directory
|
|
1665
|
-
resolves to this directory (anchor walk-up
|
|
1666
|
-
target). Useful when running this once per
|
|
1667
|
-
worktree.
|
|
1668
|
-
--since <ms> Resume from this epoch ms. Default reads the
|
|
1669
|
-
cursor (~/.greprag/opencode-watch.cursor).
|
|
1670
|
-
On first run, captures every historical turn.
|
|
1671
|
-
--cursor <file> Override the cursor file path.
|
|
1672
|
-
--reset-cursor Delete the cursor file before starting. Use
|
|
1673
|
-
with --since <ms> to re-capture from a point.
|
|
1674
|
-
--json Print one JSON object per captured turn to
|
|
1675
|
-
stdout, instead of human-readable status to
|
|
1676
|
-
stderr.
|
|
1677
|
-
--dry-run Print the would-be POST body, do not send.
|
|
1678
|
-
|
|
1679
|
-
Run under a long-lived shell loop or as a Windows service:
|
|
1680
|
-
|
|
1681
|
-
while true; do greprag opencode watch; \\
|
|
1682
|
-
echo "[restart]" >&2; sleep 1; done
|
|
1562
|
+
const OPENCODE_HELP = `greprag opencode — bridge greprag inbox into a running opencode desktop
|
|
1563
|
+
session, plus a file-watching capture pipeline for episodic memory.
|
|
1564
|
+
|
|
1565
|
+
Two subcommands:
|
|
1566
|
+
|
|
1567
|
+
greprag opencode relay Bridge greprag inbox into a running opencode
|
|
1568
|
+
desktop session. Single POST to
|
|
1569
|
+
/session/{id}/prompt_async enqueues a fresh turn;
|
|
1570
|
+
the desktop app renders it into the conversation
|
|
1571
|
+
feed via the same SSE channel the engine uses.
|
|
1572
|
+
Desktop-only by design — the TUI control plane
|
|
1573
|
+
is deprecated.
|
|
1574
|
+
|
|
1575
|
+
Session-to-session by default: the relay derives
|
|
1576
|
+
the greprag 8-hex from the opencode session UUID
|
|
1577
|
+
and filters the inbox stream to only messages
|
|
1578
|
+
addressed to THIS session. Use --tenant-wide to
|
|
1579
|
+
opt into the noisy debug mode (every message in
|
|
1580
|
+
the tenant, including messages for other
|
|
1581
|
+
sessions).
|
|
1582
|
+
|
|
1583
|
+
greprag opencode chip Spawn OpenCode Desktop chips (session.create + prompt_async).
|
|
1584
|
+
greprag opencode watch Long-lived SQLite poller on opencode's local DB.
|
|
1585
|
+
Captures every (user, assistant) turn pair to
|
|
1586
|
+
greprag memory. Bypasses opencode's event bus
|
|
1587
|
+
entirely — reads the same rows the engine writes
|
|
1588
|
+
the moment a turn completes.
|
|
1589
|
+
|
|
1590
|
+
opencode is turn-based: it has no built-in "Monitor" tool like Claude Code.
|
|
1591
|
+
\`relay\` is the bridge for live inbox delivery. \`watch\` is the capture
|
|
1592
|
+
pipeline. Run both, in separate processes, as long-lived siblings.
|
|
1593
|
+
|
|
1594
|
+
opencode relay — bridge greprag inbox into a running opencode desktop
|
|
1595
|
+
session.
|
|
1596
|
+
|
|
1597
|
+
This command subscribes to /v1/inbox/stream (same SSE channel inbox watch
|
|
1598
|
+
uses) and POSTs every inbound message to /session/{id}/prompt_async on
|
|
1599
|
+
the running opencode server. The receiving desktop session renders the
|
|
1600
|
+
injected prompt as a fresh turn in its conversation feed.
|
|
1601
|
+
|
|
1602
|
+
Usage:
|
|
1603
|
+
greprag opencode relay --session <opencode-session-id> [options]
|
|
1604
|
+
|
|
1605
|
+
Required:
|
|
1606
|
+
--session <id> opencode session id (UUID). Find via
|
|
1607
|
+
\`opencode session list\` or the session header in
|
|
1608
|
+
the opencode UI.
|
|
1609
|
+
|
|
1610
|
+
Options:
|
|
1611
|
+
--opencode-url <u> opencode server base URL.
|
|
1612
|
+
Default http://127.0.0.1:4096.
|
|
1613
|
+
Env override: OPENCODE_URL.
|
|
1614
|
+
--project <name> Filter the inbox stream to one project.
|
|
1615
|
+
--inbox-session <8hex> Filter to one greprag session (8-hex id). Default
|
|
1616
|
+
is auto-derived from --session (truncateSessionId)
|
|
1617
|
+
so the relay only sees messages addressed to THIS
|
|
1618
|
+
opencode session. Pass explicitly to override
|
|
1619
|
+
(e.g. share one greprag session across multiple
|
|
1620
|
+
opencode sessions).
|
|
1621
|
+
--tenant-wide See every message in the tenant's inbox stream,
|
|
1622
|
+
including messages addressed to other sessions.
|
|
1623
|
+
Debug flag — noisy, usually wrong.
|
|
1624
|
+
--since <id-or-iso> Resume cursor.
|
|
1625
|
+
--print Pretty-print each message to stdout.
|
|
1626
|
+
--dry-run Resolve + format, do not POST.
|
|
1627
|
+
|
|
1628
|
+
Resilience mirrors inbox-watch: exponential backoff, idle timeout,
|
|
1629
|
+
cursor-preserving reconnect. Production wraps this in a \`while true\` shell
|
|
1630
|
+
loop so process death auto-restarts:
|
|
1631
|
+
|
|
1632
|
+
while true; do greprag opencode relay --session <id>; \\
|
|
1633
|
+
echo "[restart]" >&2; sleep 1; done
|
|
1634
|
+
|
|
1635
|
+
Senders reach THIS session by addressing
|
|
1636
|
+
\`<handle>@greprag.com/<8hex>\` where <8hex> is the first 8 hex chars of the
|
|
1637
|
+
opencode session id (or pass \`--from-session <8hex>\` so the recipient can
|
|
1638
|
+
reply back by session without re-discovering it).
|
|
1639
|
+
|
|
1640
|
+
|
|
1641
|
+
opencode watch — SQLite-polling turn capture for episodic memory.
|
|
1642
|
+
|
|
1643
|
+
opencode persists every message + part as a row in
|
|
1644
|
+
%USERPROFILE%\\.local\\share\\opencode\\opencode.db (SQLite, WAL mode)
|
|
1645
|
+
the moment the AI finishes streaming. This command polls that DB every
|
|
1646
|
+
1-2s, joins \`message\` to \`session\` to recover the working directory,
|
|
1647
|
+
walks up to the greprag anchor, and POSTs the (user, assistant) pair to
|
|
1648
|
+
/v1/memory/turn. No event bus. No sidecar auth. No plugin loader.
|
|
1649
|
+
|
|
1650
|
+
Why this exists: opencode Desktop's event bus does not reliably emit
|
|
1651
|
+
\`message.updated\` for the user's active session, so a plugin hook is
|
|
1652
|
+
unreliable for capture. The on-disk DB is the source of truth — it is
|
|
1653
|
+
written by the engine itself the moment a turn completes.
|
|
1654
|
+
|
|
1655
|
+
Usage:
|
|
1656
|
+
greprag opencode watch [options]
|
|
1657
|
+
|
|
1658
|
+
Options:
|
|
1659
|
+
--interval <ms> Poll interval. Default 1500.
|
|
1660
|
+
--db <path> Override DB path. Default
|
|
1661
|
+
%USERPROFILE%\\.local\\share\\opencode\\opencode.db
|
|
1662
|
+
--project <dir> Only capture turns whose session.directory
|
|
1663
|
+
resolves to this directory (anchor walk-up
|
|
1664
|
+
target). Useful when running this once per
|
|
1665
|
+
worktree.
|
|
1666
|
+
--since <ms> Resume from this epoch ms. Default reads the
|
|
1667
|
+
cursor (~/.greprag/opencode-watch.cursor).
|
|
1668
|
+
On first run, captures every historical turn.
|
|
1669
|
+
--cursor <file> Override the cursor file path.
|
|
1670
|
+
--reset-cursor Delete the cursor file before starting. Use
|
|
1671
|
+
with --since <ms> to re-capture from a point.
|
|
1672
|
+
--json Print one JSON object per captured turn to
|
|
1673
|
+
stdout, instead of human-readable status to
|
|
1674
|
+
stderr.
|
|
1675
|
+
--dry-run Print the would-be POST body, do not send.
|
|
1676
|
+
|
|
1677
|
+
Run under a long-lived shell loop or as a Windows service:
|
|
1678
|
+
|
|
1679
|
+
while true; do greprag opencode watch; \\
|
|
1680
|
+
echo "[restart]" >&2; sleep 1; done
|
|
1683
1681
|
`;
|
|
1684
1682
|
/** greprag opencode <subcommand> — TUI bridge + capture watcher. */
|
|
1685
1683
|
async function opencode(args) {
|