Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Compress CLI text to reduce embedded release data

Rach Pradhand175dc103eea
diff --git a/build.zig b/build.zig
index 7057ae67..63c86187 100644
--- a/build.zig
+++ b/build.zig
@@ -315,6 +315,35 @@ pub fn build(b: *std.Build) void {
unit_tests.root_module.addAnonymousImport(asset.import, .{ .root_source_file = gz });
}
+ // Evaluate the CLI's Zig text constants on the host, including the learn
+ // conditional, then reuse the same compressor as the other runtime assets.
+ const cli_source = b.createModule(.{
+ .root_source_file = b.path("src/cli_text_source.zig"),
+ .target = b.graph.host,
+ });
+ cli_source.addOptions("build_options", opts);
+ const cli_text = b.addExecutable(.{
+ .name = "cli_text",
+ .root_module = b.createModule(.{
+ .root_source_file = b.path("scripts/cli_text.zig"),
+ .target = b.graph.host,
+ }),
+ });
+ cli_text.root_module.addImport("cli_text_source", cli_source);
+ const text_run = b.addRunArtifact(cli_text);
+ const help_text = text_run.addOutputFileArg("cli_help.txt");
+ const changelog_text = text_run.addOutputFileArg("cli_changelog.txt");
+ for ([_]struct { name: []const u8, text: std.Build.LazyPath }{
+ .{ .name = "cli_help.gz", .text = help_text },
+ .{ .name = "cli_changelog.gz", .text = changelog_text },
+ }) |asset| {
+ const gzip_run = b.addRunArtifact(gzip_asset);
+ gzip_run.addFileArg(asset.text);
+ const gz = gzip_run.addOutputFileArg(asset.name);
+ app_mod.addAnonymousImport(asset.name, .{ .root_source_file = gz });
+ unit_tests.root_module.addAnonymousImport(asset.name, .{ .root_source_file = gz });
+ }
+
// Bundled skills: SKILL.md playbooks compiled into every binary (embedded
// by name in src/skill_docs.zig), so a fresh install already knows how to
// author more skills and how to change this workspace's MCP servers.
diff --git a/scripts/cli_text.zig b/scripts/cli_text.zig
new file mode 100644
index 00000000..dc2a7747
--- /dev/null
+++ b/scripts/cli_text.zig
@@ -0,0 +1,11 @@
+//! Materialize the configured CLI text for the shared gzip build helper.
+const std = @import("std");
+const source = @import("cli_text_source");
+
+pub fn main(init: std.process.Init) !void {
+ const args = try init.minimal.args.toSlice(init.arena.allocator());
+ if (args.len != 3) std.process.fatal("usage: cli_text <help> <changelog>", .{});
+ const cwd = std.Io.Dir.cwd();
+ try cwd.writeFile(init.io, .{ .sub_path = args[1], .data = source.usage_text });
+ try cwd.writeFile(init.io, .{ .sub_path = args[2], .data = source.changelog_text });
+}
diff --git a/src/cli.zig b/src/cli.zig
index f2b915f0..51e11991 100644
--- a/src/cli.zig
+++ b/src/cli.zig
@@ -4,9 +4,7 @@
//! install.sh. Split out of main.zig (600-line goal). Back-imports main for
//! harness_version. main aliases updateCommand back.
//!
-//! changelog_text/usage_text (the `--version`/`--help` text blocks) also live
-//! here (600-line goal, #123) — pure string consts, aliased back in main.zig
-//! since they're only ever printed from within main().
+//! The --help/--version text is built separately by cli_text_source.zig.
const std = @import("std");
const builtin = @import("builtin");
@@ -19,354 +17,6 @@ const version_status = @import("version_status.zig");
const update_service = @import("update_service.zig");
const update_target = @import("update_target.zig");
-/// Shown under `graff --version` — a terse "what's new" for recent releases.
-/// Keep it short and current; bump alongside the version each release.
-pub const changelog_text =
- \\What's new
- \\──────────
- \\0.302.51
- \\ • Kimi API keys and logins work again (no more RstStream)
- \\ • a used-up Kimi plan window stops instead of retrying
- \\ • retrying a prompt after a connection failure works again
- \\ • subagents and workflows can fork the conversation
- \\
- \\0.302.48
- \\ • oMLX is a built-in local provider: --model omlx
- \\ • compaction counts opaque state by the provider's own measure
- \\ • a stopped local server is named in the failed turn
- \\
- \\0.302.47
- \\ • compaction waits instead of repeating when it can't make room
- \\ • the shared-tree checkpoint lets a re-issued call through
- \\ • fyi peer mail stays in the inbox without starting a turn
- \\
- \\0.302.46
- \\ • images over ACP reach the hosted default models
- \\ • a worker keeps its report when its state can't be saved
- \\ • a client's own cancel isn't called the user's
- \\
- \\0.302.45
- \\ • ACP context meter reports what graff kept out of context
- \\ • render_html says a page is saved, not displayed
- \\ • workspace use: instructions follow the tree you switch to
- \\
- \\0.302.43
- \\ • updated subscription context capacity avoids premature compaction
- \\ • model catalog and ACP usage updates report the same window
- \\
- \\0.302.42
- \\ • output-limit recovery keeps later requests and saved history valid
- \\ • ACP subagent activity shows the resolved worker model
- \\ • current main plus session, MCP, compaction and parked-command fixes
- \\
- \\0.302.41
- \\ • native subscription sign-in across terminal and ACP clients
- \\ • MCP structured results, resource content and inbound ping handling
- \\ • request-local loopback deadlines and repeatable fixture comparisons
- \\
- \\0.302.40
- \\ • stream recovery preserves partial replies across ACP and resume
- \\ • workspace skills in headless runs; actionable claim inventory
- \\ • MCP off-lists and JSON configuration listing; atomic companion updates
- \\ • stored conversation continuation and typed sign-in recovery
- \\
- \\0.302.39
- \\ • unattended runs recover from output limits and empty replies
- \\ • one-shot stream-json reports a resume handle, outcome and usage
- \\ • exhausted budgets and account limits stop with distinct exit codes
- \\
- \\0.302.38
- \\ • Windows: faster start, and the companion is found on PATH
- \\
- \\0.302.37
- \\ • ChatGPT sign-in keeps your saved token out of the sign-in URL and always prints it
- \\
- \\0.302.36
- \\ • new worktrees link .agents/linked files and run .agents/prepare
- \\
- \\0.302.35
- \\ • gateway models are priced from the gateway itself; new models show their cost
- \\ • graff models shows each gateway model's real rate
- \\ • a model without its provider's login names --model codegraff/<model>
- \\
- \\0.302.34
- \\ • Gemini API key sign-in works again
- \\ • Gemini 4 Argon shows its cost; /effort minimal runs as low on Gemini
- \\ • a gateway timeout mid-answer is retried instead of ending the turn
- \\
- \\0.302.33
- \\ • Claude: a new repo reads graff's tools and instructions from the prompt cache
- \\
- \\0.302.32
- \\ • a yield_turn handoff shows once in ACP clients
- \\ • graff login anthropic works from the desktop app, SSH and servers
- \\ • graff tui installs its client on first use
- \\
- \\0.302.31
- \\ • tool rows for todo_write, peer_message and schema loads finish in ACP clients
- \\ • graff update works on Windows
- \\
- \\0.302.30
- \\ • graff mcp status / reconnect / enable / disable, and /mcp reconnect in a session
- \\ • graff login anthropic: use an Anthropic Console account
- \\ • Claude Haiku 5.5 replaces Haiku 4.5
- \\
- \\0.0.302.29
- \\ • streamed requests to the Codegraff gateway carry graff's version too
- \\
- \\0.0.302.28
- \\ • the Codegraff usage page shows which graff version and device sent each request
- \\
- \\0.0.302.27
- \\ • choose where compaction starts: /compact-at 70, --compact-at, or the desktop setting
- \\
- \\0.0.302.26
- \\ • compaction replies no longer show up in the desktop chat
- \\ • a question no longer restarts an earlier task's checklist
- \\ • a model switch across providers keeps the conversation
- \\ • computer-use and closed stdio MCP servers recover
- \\
- \\0.0.302.25
- \\ • ChatGPT/OpenAI sessions no longer compact before every tool call
- \\ • OpenAI routes compact only with the provider's own compaction
- \\ • fewer hosted-model requests per task; empty tool results no longer break a chat
- \\
- \\0.0.302.24
- \\ • Codegraff sign-in: models on the Messages wire use it natively
- \\ • goals set from the desktop app start immediately; unfinished work survives a question
- \\
- \\0.0.302.23
- \\ • ChatGPT-plan sign-in caches the prompt again, on every model
- \\
- \\0.0.302.22
- \\ • /import-claude brings this project's Claude Code conversations to /resume
- \\ • imported conversations continue on your graff provider and credentials
- \\
- \\0.0.302.21
- \\ • Windows: irm https://codegraff.com/install.ps1 | iex installs graff natively
- \\ • graff login prints the link with your code; Windows opens the browser
- \\ • an expired ChatGPT sign-in reopens in the browser and the request continues
- \\
- \\0.0.302.20
- \\ • includes everything from 0.0.302.19 (not published on its own)
- \\ • one oversized MCP message no longer breaks every later call to that server
- \\ • Windows: an empty HOME no longer hides your profile directory
- \\ • GRAFF_COMPACT_MIX=1: experimental two-pass compaction
- \\
- \\0.0.302.19
- \\ • tool results inline up to 64 KiB: large files read in one piece
- \\ • no false stalls while the model composes a batch of tool calls
- \\ • parked work is named above the prompt; graff says it will continue
- \\ • PR commands run like any other command (no readiness gate)
- \\ • logged in, Jev picks each turn's effort alongside the first request
- \\
- \\0.0.302.18
- \\ • graff tui launches the separate fullscreen client; terminals get the line REPL
- \\ • shorter turns: one-line heads-ups, no recomputed answers, fewer false stalls
- \\ • instructions cache across repos; the shell names python3's version
- \\ • clearer session lists and cross-project resume
- \\ • paste warnings, MCP recovery, and catalog-tolerant model selection
- \\
- \\0.0.302.17
- \\ • rlm scripts keep whole MCP results; print() still shows the slim view
- \\
- \\0.0.302.16
- \\ • license: companies that raised over US$500k need a commercial license
- \\
- \\0.0.302.15
- \\ • DeepSeek's default effort thinks at its low level (/effort high for more)
- \\
- \\0.0.302.14
- \\ • MiMo answers without thinking unless effort is high (/effort high)
- \\ • MCP servers connect in the background; the first message never waits
- \\ • sub-agents start with your prompts and their parent's effort
- \\ • the shell tool names the OS; small reads and sed -i pass the guard
- \\ • rlm takes JSON literals; todo_write replies with counts
- \\
- \\0.0.302.13
- \\ • fewer round trips: named MCP servers and subagents load up front
- \\ • write_file won't replace an unread file and says what it did
- \\ • sub-agents call inherited MCP tools from their first request
- \\ • piped repl: a bracketed paste is one prompt
- \\
- \\0.0.302.12
- \\ • every ChatGPT login (chatgpt, codex) is the new ChatGPT sign-in
- \\ • browser sign-ins survive stray connections and old tabs
- \\ • sub-agents get the MCP tools their root loaded
- \\ • codex follows the model's default effort and verbosity
- \\
- \\0.0.302.11
- \\ • codex prompt cache is per account: a new repo starts warm
- \\ • tool loads keep the cached prefix; rare tools load on demand
- \\ • MCP says how it slims results and keeps the full result
- \\ • GPT-6 follow-ups steer the running reply; graff login chatgpt
- \\ • scripted repl sends the prompt once and waits for background work
- \\
- \\0.0.302.10
- \\ • a tool call cut off mid-response is refused with its cause, not run
- \\ • /loop waits for its background work; resends never start a second turn
- \\ • slow Anthropic calls keep their prompt cache; OpenRouter caches Claude
- \\
- \\0.0.302.9
- \\ • macOS CLI signed and notarized by the release workflow
- \\ • local MCP servers start on first use; "shared": true runs one per machine
- \\ • the desktop app is Harness; the in-repo desktop apps are removed
- \\ • graff mcp add --everywhere saves to the user-level MCP config
- \\ • Harness room messages from other agents arrive framed as advisory
- \\
- \\0.0.302.8
- \\ • instruction-file edits reach the model without busting the prompt cache
- \\ • no more /pr-acceptance: a draft PR completes as an unverified handoff
- \\ • PR review budget fits small edits in large files; finite jobs stay awaitable
- \\ • MCP client: pagination, list_changed, progress, cancellation, MRTR
- \\ • graff mcp add infers, checks and hot-joins a server; desktop computer use removed
- \\
- \\0.0.302.7
- \\ • tool shells: provider keys stay out, git and NUL-byte commands are safer
- \\ • tool calls left as <tool_call> markup in a reply now run
- \\ • ACP: diffs and locations on tool calls, richer approvals, faster session/new offline
- \\ • graff mcp serve speaks MCP 2026-07-28
- \\
- \\0.0.302.6
- \\ • ask_user over ACP uses standard elicitation and never freezes a client
- \\ • ACP subagents stream their work onto the parent tool call
- \\ • ACP v2 draft preview (GRAFF_ACP_V2=1)
- \\ • graff peer: message other agents on this device; graff keys: sync logins
- \\
- \\0.0.302.5
- \\ • WebSocket turns stream live, with automatic HTTPS fallback
- \\ • ACP sessions use the client's folder and report their worktree
- \\ • openai/codex models and ACP image blocks accept images
- \\ • the old browser companion is retired; webfetch uses built-in HTTP
- \\
- \\Full release history: https://github.com/justrach/codegraff/releases
- \\
-;
-
-/// Release builds leave `graff learn` out (build option `learn`).
-const learn_usage = if (@import("build_options").learn)
- " graff learn [help] local mutate/evaluate/promote/rollback engine\n"
-else
- "";
-
-pub const usage_text =
- \\graff — a minimal agentic coding harness in Zig (zero deps)
- \\
- \\usage:
- \\ graff [flags] start the line REPL
- \\ graff repl line REPL (scripted when stdin is piped)
- \\ graff tui [--yes] [args...] launch graff-tui; installs it from the Harness release on first use
- \\ graff [-p] "prompt" one-shot: run the prompt, print the answer, exit
- \\ graff login get a codegraff key (device-code OAuth)
- \\ graff login chatgpt ChatGPT sign-in (also: codex, openai)
- \\ graff login anthropic Claude subscription browser sign-in (also: ant)
- \\ graff login console metered Console sign-in through the `ant` CLI
- \\ graff login kimi Kimi Code OAuth login (device-code)
- \\ graff login xai Grok/SuperGrok OAuth login (device-code)
- \\ graff login zai Z.AI Coding Plan OAuth login
- \\ graff key set <provider> <key> store a key (Keychain; POSIX 0600 file; Windows home ACL)
- \\ graff key list show which providers have keys
- \\ graff refresh pull live catalogs (same as `graff models refresh`)
- \\ graff models [refresh] list the live catalog; refresh Codex + provider lists + models.dev
- \\ graff route <model>… dry-run which provider/billing a model lands on (no API call)
- \\ graff mcp add <name> -- <cmd> add a stdio MCP server to .mcp.json
- \\ graff mcp add <name> --url <url> add a Streamable HTTP MCP server
- \\ graff mcp login <name> OAuth login for a remote MCP server
- \\ graff mcp list configured MCP servers
- \\ graff mcp install configure local HTTP service and MCP clients
- \\ graff mcp serve [--http] [--port N] expose run_task to MCP clients
- \\ graff plugins [load <name>] list Claude/Cursor/Grok/Codex plugin trees (in place)
- \\
-++ learn_usage ++
- \\ graff worktree list list -w tabs and experiment-pool trees (tagged)
- \\ graff worktree create <name> [base] mint a task workspace from the remote base (origin/main after fetch; optional base)
- \\ graff worktree run <name> run the workspace run script from that checkout
- \\ graff worktree archive <name> remove a clean duplicate checkout; dirty or unique-commit trees stay
- \\ graff worktree merge <name> squash-land worktree-<name> onto the current branch + clean up
- \\ graff worktree land <name> same as merge
- \\ graff worktree update <name> merge the remote base into that workspace
- \\ graff worktree gc drop dead session trees and clean merged-PR trees
- \\ graff worktree remove <name> discard worktree-<name> (drops its scratch work) + delete the branch
- \\ graff worktree prune drop git registrations for worktrees whose dirs were deleted
- \\ graff servers background servers graff started (this session's or older): pid, port, age
- \\ graff servers stop <pid> end one (its whole process tree); `prune` drops records of dead ones
- \\ graff peer list|send|inbox talk with other agents on this device (Claude Code, Codex, graff)
- \\ graff sandboxes list your gateway sandboxes (what's burning credits)
- \\ graff sandboxes stop <id> spin a sandbox down (stops it + settles the meter)
- \\ graff cube new spin up a cloud graff (sandbox + serve + preview URL)
- \\ graff cube [status|stop] inspect the running cube or spin it down
- \\ graff --schema print the machine-readable interface (SDK codegen)
- \\ graff serve HTTP/NDJSON bridge over the --json protocol
- \\ (--host/--port/--token; sessions are --json children)
- \\ graff remote-control [--name n] serve with no listener: dial out to your Codegraff account so
- \\ `graff remote` anywhere can drive sessions on this machine
- \\ graff remote [new|send|tail|…] list and drive the sessions of machines running remote-control
- \\ graff acp Agent Client Protocol agent on stdio (Zed and other ACP editors)
- \\ graff update [--force|--check] update graff to the latest stable release
- \\ graff update --beta [--check] install the newest beta for the next launch
- \\ graff title <prompt> print the AI tab-title for a prompt (test title styles)
- \\
- \\flags:
- \\ --model <name> start on this model (same fuzzy resolution as /model)
- \\ --subagent-model <name> pin children/workflows/judges on the root provider
- \\ --subagent-provider <id> route pinned workers through this provider
- \\ --allow-cross-provider-subagents confirm prompts/code may go to the worker provider
- \\ --no-subagent-tier opt out of the default worker tier ladder (inherit the root model)
- \\ --resume <name> resume/autosave <name>.session.json
- \\ --branch <name> clone --resume into an independent autosave target
- \\ --new start a fresh autosaved session (default)
- \\ --no-resume ignore --resume and start fresh
- \\ --system-prompt <text> replace the built-in system prompt
- \\ --append-system-prompt <text> append extra text to the system prompt
- \\ --goal <text> seed a standing objective (tracked as a todo checklist) for every turn; persists across completions
- \\ --eval <cmd> scoring command for an eval-driven loop (the `eval` tool runs it)
- \\ --until <0-100> eval-loop target score; stop when reached (default 90)
- \\ --niche <name> fleet niche this eval optimizes (reviewer/researcher/implementer/skeptic or a custom agent); tags submitted scores so the DGM can promote a champion for that role
- \\ -w, --worktree <name> isolate this session in a git worktree (.graff/worktrees/<name>) so parallel agents don't collide on files. A second session in a claimed checkout auto-isolates.
- \\ --experiment N pre-mint N child worktrees (1-16) under .graff/worktrees/exp-<id>/; next spawns claim a seat
- \\ --add-dir <path> extra file-tool root (repeatable, max 16). Not a cwd switch; no skills/sessions from it
- \\ --context-limit name=N cap a named prefix: skill_catalog_bytes|mcp_schema_bytes|agents_md_bytes
- \\ --no-autocommit with -w, don't auto-commit each turn (default on; land work with `graff worktree merge`)
- \\ --yolo skip all permission prompts for the session
- \\ --rlm advertise the rlm REPL (default; persistent binds, subagent(), llm_query, mid-stream spec-ptc; GRAFF_RLM=1)
- \\ --old, --no-rlm restore the pre-rlm structured-only catalog (GRAFF_OLD=1 or GRAFF_RLM=0)
- \\ --lean slim tool surface (8 core tools) + MCP schemas folded behind load_tool_schemas — the DEFAULT for -p one-shots (GRAFF_LEAN=1). `.mcp.json` still connects.
- \\ --no-lean opt a one-shot out of the implied --lean: full tool surface + eager MCP schemas, the pre-default -p behavior
- \\ --no-local-tools embedder mode: hard-disable the built-in bash/bash_output/bash_kill/read_file/edit_file/write_file/codedb tools for the whole process (subagents included), so graff can run outside the sandbox and get its coding tools from an MCP server instead; webfetch, orchestration and MCP tools still work (GRAFF_NO_LOCAL_TOOLS=1)
- \\ -p, --print one-shot print mode (answer on stdout, progress on stderr)
- \\ --output-format text|stream-json one-shot output; stream-json emits run_started and result
- \\ --timing show per-tool wall-clock on result lines
- \\ --cost show running session spend in the prompt
- \\ --json structured stdio protocol (JSON in, JSONL events out)
- \\ --max-run-tool-calls N aggregate root/descendant tool ceiling for this invocation
- \\ --max-tool-calls N reject root tool calls after N per turn (JSON-safe budget)
- \\ --compact-at PCT start automatic compaction at PCT% of the context window (10-95, default 80)
- \\ --max-model-calls N total provider calls allowed across this run (default 0 = unlimited; includes children/title/judges)
- \\ --dedupe-tool-calls reject duplicate root tool name+input calls per turn
- \\ --no-telemetry disable anonymous usage telemetry for this run
- \\ --learning-privacy <mode> learning egress ceiling: local|aggregate|templates|examples (default aggregate)
- \\ -h, --help this help
- \\ -V, --version print version
- \\
- \\keys: <PROVIDER>_API_KEY env vars, `graff key set`, or `graff login`;
- \\a Codex CLI login is picked up automatically.
- \\inside the REPL: /help lists commands, a bare "/" opens the command menu,
- \\"@" opens a fuzzy file picker (a drag-and-dropped image attaches as a
- \\native vision block on vision models; other files paste as their path),
- \\esc interrupts a streaming response, "always allow" persists to
- \\.harness/settings.json.
- \\telemetry: /debug is a local content-free HUD (session/turn/tool
- \\decisions). Anonymous OTLP usage stats leave the process only when
- \\OTEL_EXPORTER_OTLP_ENDPOINT (or GRAFF_OTEL_ENDPOINT) is set; opt out
- \\with --no-telemetry or GRAFF_NO_TELEMETRY=1. GRAFF_TELEMETRY_KEY sends
- \\an optional x-harness-key token to the configured collector.
- \\learning privacy: local learning trials publish prompt-free aggregate grades
- \\by default, announced once per machine; /privacy local (or
- \\GRAFF_LEARNING_PRIVACY=local, GRAFF_FLEET=off, --no-telemetry) sends nothing.
- \\/privacy changes the session ceiling; template text still needs exact approval.
- \\
-;
-
/// Dim REPL/TUI line when GitHub has a newer release. Null if current, newer,
/// offline, or GRAFF_NO_UPDATE_CHECK is set.
pub fn updateAvailableLine(io: Io, gpa: Allocator, arena: Allocator, skip: bool) ?[]const u8 {
diff --git a/src/cli_text.zig b/src/cli_text.zig
new file mode 100644
index 00000000..fae0b2e0
--- /dev/null
+++ b/src/cli_text.zig
@@ -0,0 +1,29 @@
+//! Runtime-only CLI text; decompression is confined to --help/--version.
+const std = @import("std");
+const archive = @import("update_archive.zig");
+
+pub fn print(gpa: std.mem.Allocator, out: *std.Io.Writer, help: bool, version: []const u8) !void {
+ const text = try archive.gunzip(gpa, if (help) @embedFile("cli_help.gz") else @embedFile("cli_changelog.gz"));
+ defer gpa.free(text);
+ if (!help) try out.print("graff {s}\n\n", .{version});
+ try out.writeAll(text);
+}
+
+test "compressed CLI text preserves help and version output" {
+ const source = @import("cli_text_source.zig");
+ var out: std.Io.Writer.Allocating = .init(std.testing.allocator);
+ defer out.deinit();
+ try print(std.testing.allocator, &out.writer, true, "test-version");
+ try std.testing.expectEqualStrings(source.usage_text, out.written());
+ out.clearRetainingCapacity();
+ try print(std.testing.allocator, &out.writer, false, "test-version");
+ try std.testing.expectEqualStrings("graff test-version\n\n" ++ source.changelog_text, out.written());
+}
+
+test "compressed CLI help respects the learn configuration" {
+ var out: std.Io.Writer.Allocating = .init(std.testing.allocator);
+ defer out.deinit();
+ try print(std.testing.allocator, &out.writer, true, "unused");
+ const learn_line = " graff learn [help] local mutate/evaluate/promote/rollback engine\n";
+ try std.testing.expectEqual(@import("build_options").learn, std.mem.indexOf(u8, out.written(), learn_line) != null);
+}
diff --git a/src/cli_text_source.zig b/src/cli_text_source.zig
new file mode 100644
index 00000000..8c35691a
--- /dev/null
+++ b/src/cli_text_source.zig
@@ -0,0 +1,349 @@
+//! Build-time source for --help and --version. Keep all release notes intact.
+
+/// Shown under `graff --version` — a terse "what's new" for recent releases.
+/// Keep it short and current; bump alongside the version each release.
+pub const changelog_text =
+ \\What's new
+ \\──────────
+ \\0.302.51
+ \\ • Kimi API keys and logins work again (no more RstStream)
+ \\ • a used-up Kimi plan window stops instead of retrying
+ \\ • retrying a prompt after a connection failure works again
+ \\ • subagents and workflows can fork the conversation
+ \\
+ \\0.302.48
+ \\ • oMLX is a built-in local provider: --model omlx
+ \\ • compaction counts opaque state by the provider's own measure
+ \\ • a stopped local server is named in the failed turn
+ \\
+ \\0.302.47
+ \\ • compaction waits instead of repeating when it can't make room
+ \\ • the shared-tree checkpoint lets a re-issued call through
+ \\ • fyi peer mail stays in the inbox without starting a turn
+ \\
+ \\0.302.46
+ \\ • images over ACP reach the hosted default models
+ \\ • a worker keeps its report when its state can't be saved
+ \\ • a client's own cancel isn't called the user's
+ \\
+ \\0.302.45
+ \\ • ACP context meter reports what graff kept out of context
+ \\ • render_html says a page is saved, not displayed
+ \\ • workspace use: instructions follow the tree you switch to
+ \\
+ \\0.302.43
+ \\ • updated subscription context capacity avoids premature compaction
+ \\ • model catalog and ACP usage updates report the same window
+ \\
+ \\0.302.42
+ \\ • output-limit recovery keeps later requests and saved history valid
+ \\ • ACP subagent activity shows the resolved worker model
+ \\ • current main plus session, MCP, compaction and parked-command fixes
+ \\
+ \\0.302.41
+ \\ • native subscription sign-in across terminal and ACP clients
+ \\ • MCP structured results, resource content and inbound ping handling
+ \\ • request-local loopback deadlines and repeatable fixture comparisons
+ \\
+ \\0.302.40
+ \\ • stream recovery preserves partial replies across ACP and resume
+ \\ • workspace skills in headless runs; actionable claim inventory
+ \\ • MCP off-lists and JSON configuration listing; atomic companion updates
+ \\ • stored conversation continuation and typed sign-in recovery
+ \\
+ \\0.302.39
+ \\ • unattended runs recover from output limits and empty replies
+ \\ • one-shot stream-json reports a resume handle, outcome and usage
+ \\ • exhausted budgets and account limits stop with distinct exit codes
+ \\
+ \\0.302.38
+ \\ • Windows: faster start, and the companion is found on PATH
+ \\
+ \\0.302.37
+ \\ • ChatGPT sign-in keeps your saved token out of the sign-in URL and always prints it
+ \\
+ \\0.302.36
+ \\ • new worktrees link .agents/linked files and run .agents/prepare
+ \\
+ \\0.302.35
+ \\ • gateway models are priced from the gateway itself; new models show their cost
+ \\ • graff models shows each gateway model's real rate
+ \\ • a model without its provider's login names --model codegraff/<model>
+ \\
+ \\0.302.34
+ \\ • Gemini API key sign-in works again
+ \\ • Gemini 4 Argon shows its cost; /effort minimal runs as low on Gemini
+ \\ • a gateway timeout mid-answer is retried instead of ending the turn
+ \\
+ \\0.302.33
+ \\ • Claude: a new repo reads graff's tools and instructions from the prompt cache
+ \\
+ \\0.302.32
+ \\ • a yield_turn handoff shows once in ACP clients
+ \\ • graff login anthropic works from the desktop app, SSH and servers
+ \\ • graff tui installs its client on first use
+ \\
+ \\0.302.31
+ \\ • tool rows for todo_write, peer_message and schema loads finish in ACP clients
+ \\ • graff update works on Windows
+ \\
+ \\0.302.30
+ \\ • graff mcp status / reconnect / enable / disable, and /mcp reconnect in a session
+ \\ • graff login anthropic: use an Anthropic Console account
+ \\ • Claude Haiku 5.5 replaces Haiku 4.5
+ \\
+ \\0.0.302.29
+ \\ • streamed requests to the Codegraff gateway carry graff's version too
+ \\
+ \\0.0.302.28
+ \\ • the Codegraff usage page shows which graff version and device sent each request
+ \\
+ \\0.0.302.27
+ \\ • choose where compaction starts: /compact-at 70, --compact-at, or the desktop setting
+ \\
+ \\0.0.302.26
+ \\ • compaction replies no longer show up in the desktop chat
+ \\ • a question no longer restarts an earlier task's checklist
+ \\ • a model switch across providers keeps the conversation
+ \\ • computer-use and closed stdio MCP servers recover
+ \\
+ \\0.0.302.25
+ \\ • ChatGPT/OpenAI sessions no longer compact before every tool call
+ \\ • OpenAI routes compact only with the provider's own compaction
+ \\ • fewer hosted-model requests per task; empty tool results no longer break a chat
+ \\
+ \\0.0.302.24
+ \\ • Codegraff sign-in: models on the Messages wire use it natively
+ \\ • goals set from the desktop app start immediately; unfinished work survives a question
+ \\
+ \\0.0.302.23
+ \\ • ChatGPT-plan sign-in caches the prompt again, on every model
+ \\
+ \\0.0.302.22
+ \\ • /import-claude brings this project's Claude Code conversations to /resume
+ \\ • imported conversations continue on your graff provider and credentials
+ \\
+ \\0.0.302.21
+ \\ • Windows: irm https://codegraff.com/install.ps1 | iex installs graff natively
+ \\ • graff login prints the link with your code; Windows opens the browser
+ \\ • an expired ChatGPT sign-in reopens in the browser and the request continues
+ \\
+ \\0.0.302.20
+ \\ • includes everything from 0.0.302.19 (not published on its own)
+ \\ • one oversized MCP message no longer breaks every later call to that server
+ \\ • Windows: an empty HOME no longer hides your profile directory
+ \\ • GRAFF_COMPACT_MIX=1: experimental two-pass compaction
+ \\
+ \\0.0.302.19
+ \\ • tool results inline up to 64 KiB: large files read in one piece
+ \\ • no false stalls while the model composes a batch of tool calls
+ \\ • parked work is named above the prompt; graff says it will continue
+ \\ • PR commands run like any other command (no readiness gate)
+ \\ • logged in, Jev picks each turn's effort alongside the first request
+ \\
+ \\0.0.302.18
+ \\ • graff tui launches the separate fullscreen client; terminals get the line REPL
+ \\ • shorter turns: one-line heads-ups, no recomputed answers, fewer false stalls
+ \\ • instructions cache across repos; the shell names python3's version
+ \\ • clearer session lists and cross-project resume
+ \\ • paste warnings, MCP recovery, and catalog-tolerant model selection
+ \\
+ \\0.0.302.17
+ \\ • rlm scripts keep whole MCP results; print() still shows the slim view
+ \\
+ \\0.0.302.16
+ \\ • license: companies that raised over US$500k need a commercial license
+ \\
+ \\0.0.302.15
+ \\ • DeepSeek's default effort thinks at its low level (/effort high for more)
+ \\
+ \\0.0.302.14
+ \\ • MiMo answers without thinking unless effort is high (/effort high)
+ \\ • MCP servers connect in the background; the first message never waits
+ \\ • sub-agents start with your prompts and their parent's effort
+ \\ • the shell tool names the OS; small reads and sed -i pass the guard
+ \\ • rlm takes JSON literals; todo_write replies with counts
+ \\
+ \\0.0.302.13
+ \\ • fewer round trips: named MCP servers and subagents load up front
+ \\ • write_file won't replace an unread file and says what it did
+ \\ • sub-agents call inherited MCP tools from their first request
+ \\ • piped repl: a bracketed paste is one prompt
+ \\
+ \\0.0.302.12
+ \\ • every ChatGPT login (chatgpt, codex) is the new ChatGPT sign-in
+ \\ • browser sign-ins survive stray connections and old tabs
+ \\ • sub-agents get the MCP tools their root loaded
+ \\ • codex follows the model's default effort and verbosity
+ \\
+ \\0.0.302.11
+ \\ • codex prompt cache is per account: a new repo starts warm
+ \\ • tool loads keep the cached prefix; rare tools load on demand
+ \\ • MCP says how it slims results and keeps the full result
+ \\ • GPT-6 follow-ups steer the running reply; graff login chatgpt
+ \\ • scripted repl sends the prompt once and waits for background work
+ \\
+ \\0.0.302.10
+ \\ • a tool call cut off mid-response is refused with its cause, not run
+ \\ • /loop waits for its background work; resends never start a second turn
+ \\ • slow Anthropic calls keep their prompt cache; OpenRouter caches Claude
+ \\
+ \\0.0.302.9
+ \\ • macOS CLI signed and notarized by the release workflow
+ \\ • local MCP servers start on first use; "shared": true runs one per machine
+ \\ • the desktop app is Harness; the in-repo desktop apps are removed
+ \\ • graff mcp add --everywhere saves to the user-level MCP config
+ \\ • Harness room messages from other agents arrive framed as advisory
+ \\
+ \\0.0.302.8
+ \\ • instruction-file edits reach the model without busting the prompt cache
+ \\ • no more /pr-acceptance: a draft PR completes as an unverified handoff
+ \\ • PR review budget fits small edits in large files; finite jobs stay awaitable
+ \\ • MCP client: pagination, list_changed, progress, cancellation, MRTR
+ \\ • graff mcp add infers, checks and hot-joins a server; desktop computer use removed
+ \\
+ \\0.0.302.7
+ \\ • tool shells: provider keys stay out, git and NUL-byte commands are safer
+ \\ • tool calls left as <tool_call> markup in a reply now run
+ \\ • ACP: diffs and locations on tool calls, richer approvals, faster session/new offline
+ \\ • graff mcp serve speaks MCP 2026-07-28
+ \\
+ \\0.0.302.6
+ \\ • ask_user over ACP uses standard elicitation and never freezes a client
+ \\ • ACP subagents stream their work onto the parent tool call
+ \\ • ACP v2 draft preview (GRAFF_ACP_V2=1)
+ \\ • graff peer: message other agents on this device; graff keys: sync logins
+ \\
+ \\0.0.302.5
+ \\ • WebSocket turns stream live, with automatic HTTPS fallback
+ \\ • ACP sessions use the client's folder and report their worktree
+ \\ • openai/codex models and ACP image blocks accept images
+ \\ • the old browser companion is retired; webfetch uses built-in HTTP
+ \\
+ \\Full release history: https://github.com/justrach/codegraff/releases
+ \\
+;
+
+/// Release builds leave `graff learn` out (build option `learn`).
+const learn_usage = if (@import("build_options").learn)
+ " graff learn [help] local mutate/evaluate/promote/rollback engine\n"
+else
+ "";
+
+pub const usage_text =
+ \\graff — a minimal agentic coding harness in Zig (zero deps)
+ \\
+ \\usage:
+ \\ graff [flags] start the line REPL
+ \\ graff repl line REPL (scripted when stdin is piped)
+ \\ graff tui [--yes] [args...] launch graff-tui; installs it from the Harness release on first use
+ \\ graff [-p] "prompt" one-shot: run the prompt, print the answer, exit
+ \\ graff login get a codegraff key (device-code OAuth)
+ \\ graff login chatgpt ChatGPT sign-in (also: codex, openai)
+ \\ graff login anthropic Claude subscription browser sign-in (also: ant)
+ \\ graff login console metered Console sign-in through the `ant` CLI
+ \\ graff login kimi Kimi Code OAuth login (device-code)
+ \\ graff login xai Grok/SuperGrok OAuth login (device-code)
+ \\ graff login zai Z.AI Coding Plan OAuth login
+ \\ graff key set <provider> <key> store a key (Keychain; POSIX 0600 file; Windows home ACL)
+ \\ graff key list show which providers have keys
+ \\ graff refresh pull live catalogs (same as `graff models refresh`)
+ \\ graff models [refresh] list the live catalog; refresh Codex + provider lists + models.dev
+ \\ graff route <model>… dry-run which provider/billing a model lands on (no API call)
+ \\ graff mcp add <name> -- <cmd> add a stdio MCP server to .mcp.json
+ \\ graff mcp add <name> --url <url> add a Streamable HTTP MCP server
+ \\ graff mcp login <name> OAuth login for a remote MCP server
+ \\ graff mcp list configured MCP servers
+ \\ graff mcp install configure local HTTP service and MCP clients
+ \\ graff mcp serve [--http] [--port N] expose run_task to MCP clients
+ \\ graff plugins [load <name>] list Claude/Cursor/Grok/Codex plugin trees (in place)
+ \\
+++ learn_usage ++
+ \\ graff worktree list list -w tabs and experiment-pool trees (tagged)
+ \\ graff worktree create <name> [base] mint a task workspace from the remote base (origin/main after fetch; optional base)
+ \\ graff worktree run <name> run the workspace run script from that checkout
+ \\ graff worktree archive <name> remove a clean duplicate checkout; dirty or unique-commit trees stay
+ \\ graff worktree merge <name> squash-land worktree-<name> onto the current branch + clean up
+ \\ graff worktree land <name> same as merge
+ \\ graff worktree update <name> merge the remote base into that workspace
+ \\ graff worktree gc drop dead session trees and clean merged-PR trees
+ \\ graff worktree remove <name> discard worktree-<name> (drops its scratch work) + delete the branch
+ \\ graff worktree prune drop git registrations for worktrees whose dirs were deleted
+ \\ graff servers background servers graff started (this session's or older): pid, port, age
+ \\ graff servers stop <pid> end one (its whole process tree); `prune` drops records of dead ones
+ \\ graff peer list|send|inbox talk with other agents on this device (Claude Code, Codex, graff)
+ \\ graff sandboxes list your gateway sandboxes (what's burning credits)
+ \\ graff sandboxes stop <id> spin a sandbox down (stops it + settles the meter)
+ \\ graff cube new spin up a cloud graff (sandbox + serve + preview URL)
+ \\ graff cube [status|stop] inspect the running cube or spin it down
+ \\ graff --schema print the machine-readable interface (SDK codegen)
+ \\ graff serve HTTP/NDJSON bridge over the --json protocol
+ \\ (--host/--port/--token; sessions are --json children)
+ \\ graff remote-control [--name n] serve with no listener: dial out to your Codegraff account so
+ \\ `graff remote` anywhere can drive sessions on this machine
+ \\ graff remote [new|send|tail|…] list and drive the sessions of machines running remote-control
+ \\ graff acp Agent Client Protocol agent on stdio (Zed and other ACP editors)
+ \\ graff update [--force|--check] update graff to the latest stable release
+ \\ graff update --beta [--check] install the newest beta for the next launch
+ \\ graff title <prompt> print the AI tab-title for a prompt (test title styles)
+ \\
+ \\flags:
+ \\ --model <name> start on this model (same fuzzy resolution as /model)
+ \\ --subagent-model <name> pin children/workflows/judges on the root provider
+ \\ --subagent-provider <id> route pinned workers through this provider
+ \\ --allow-cross-provider-subagents confirm prompts/code may go to the worker provider
+ \\ --no-subagent-tier opt out of the default worker tier ladder (inherit the root model)
+ \\ --resume <name> resume/autosave <name>.session.json
+ \\ --branch <name> clone --resume into an independent autosave target
+ \\ --new start a fresh autosaved session (default)
+ \\ --no-resume ignore --resume and start fresh
+ \\ --system-prompt <text> replace the built-in system prompt
+ \\ --append-system-prompt <text> append extra text to the system prompt
+ \\ --goal <text> seed a standing objective (tracked as a todo checklist) for every turn; persists across completions
+ \\ --eval <cmd> scoring command for an eval-driven loop (the `eval` tool runs it)
+ \\ --until <0-100> eval-loop target score; stop when reached (default 90)
+ \\ --niche <name> fleet niche this eval optimizes (reviewer/researcher/implementer/skeptic or a custom agent); tags submitted scores so the DGM can promote a champion for that role
+ \\ -w, --worktree <name> isolate this session in a git worktree (.graff/worktrees/<name>) so parallel agents don't collide on files. A second session in a claimed checkout auto-isolates.
+ \\ --experiment N pre-mint N child worktrees (1-16) under .graff/worktrees/exp-<id>/; next spawns claim a seat
+ \\ --add-dir <path> extra file-tool root (repeatable, max 16). Not a cwd switch; no skills/sessions from it
+ \\ --context-limit name=N cap a named prefix: skill_catalog_bytes|mcp_schema_bytes|agents_md_bytes
+ \\ --no-autocommit with -w, don't auto-commit each turn (default on; land work with `graff worktree merge`)
+ \\ --yolo skip all permission prompts for the session
+ \\ --rlm advertise the rlm REPL (default; persistent binds, subagent(), llm_query, mid-stream spec-ptc; GRAFF_RLM=1)
+ \\ --old, --no-rlm restore the pre-rlm structured-only catalog (GRAFF_OLD=1 or GRAFF_RLM=0)
+ \\ --lean slim tool surface (8 core tools) + MCP schemas folded behind load_tool_schemas — the DEFAULT for -p one-shots (GRAFF_LEAN=1). `.mcp.json` still connects.
+ \\ --no-lean opt a one-shot out of the implied --lean: full tool surface + eager MCP schemas, the pre-default -p behavior
+ \\ --no-local-tools embedder mode: hard-disable the built-in bash/bash_output/bash_kill/read_file/edit_file/write_file/codedb tools for the whole process (subagents included), so graff can run outside the sandbox and get its coding tools from an MCP server instead; webfetch, orchestration and MCP tools still work (GRAFF_NO_LOCAL_TOOLS=1)
+ \\ -p, --print one-shot print mode (answer on stdout, progress on stderr)
+ \\ --output-format text|stream-json one-shot output; stream-json emits run_started and result
+ \\ --timing show per-tool wall-clock on result lines
+ \\ --cost show running session spend in the prompt
+ \\ --json structured stdio protocol (JSON in, JSONL events out)
+ \\ --max-run-tool-calls N aggregate root/descendant tool ceiling for this invocation
+ \\ --max-tool-calls N reject root tool calls after N per turn (JSON-safe budget)
+ \\ --compact-at PCT start automatic compaction at PCT% of the context window (10-95, default 80)
+ \\ --max-model-calls N total provider calls allowed across this run (default 0 = unlimited; includes children/title/judges)
+ \\ --dedupe-tool-calls reject duplicate root tool name+input calls per turn
+ \\ --no-telemetry disable anonymous usage telemetry for this run
+ \\ --learning-privacy <mode> learning egress ceiling: local|aggregate|templates|examples (default aggregate)
+ \\ -h, --help this help
+ \\ -V, --version print version
+ \\
+ \\keys: <PROVIDER>_API_KEY env vars, `graff key set`, or `graff login`;
+ \\a Codex CLI login is picked up automatically.
+ \\inside the REPL: /help lists commands, a bare "/" opens the command menu,
+ \\"@" opens a fuzzy file picker (a drag-and-dropped image attaches as a
+ \\native vision block on vision models; other files paste as their path),
+ \\esc interrupts a streaming response, "always allow" persists to
+ \\.harness/settings.json.
+ \\telemetry: /debug is a local content-free HUD (session/turn/tool
+ \\decisions). Anonymous OTLP usage stats leave the process only when
+ \\OTEL_EXPORTER_OTLP_ENDPOINT (or GRAFF_OTEL_ENDPOINT) is set; opt out
+ \\with --no-telemetry or GRAFF_NO_TELEMETRY=1. GRAFF_TELEMETRY_KEY sends
+ \\an optional x-harness-key token to the configured collector.
+ \\learning privacy: local learning trials publish prompt-free aggregate grades
+ \\by default, announced once per machine; /privacy local (or
+ \\GRAFF_LEARNING_PRIVACY=local, GRAFF_FLEET=off, --no-telemetry) sends nothing.
+ \\/privacy changes the session ceiling; template text still needs exact approval.
+ \\
+;
diff --git a/src/learning_privacy.zig b/src/learning_privacy.zig
index 079f7425..3843b060 100644
--- a/src/learning_privacy.zig
+++ b/src/learning_privacy.zig
@@ -222,7 +222,7 @@ test "--help and --schema state the default ceiling the binary actually applies"
// Every mode name is checked, not just the current one, so flipping
// default_mode without moving the text fails here rather than in a user's
// reading of the docs.
- const usage_text = @import("cli.zig").usage_text;
+ const usage_text = @import("cli_text_source.zig").usage_text;
const schema_flags_json = @import("schema.zig").schema_flags_json;
const documented = "default " ++ @tagName(default_mode);
try std.testing.expect(std.mem.indexOf(u8, usage_text, documented) != null);
diff --git a/src/main.zig b/src/main.zig
index 64eac159..4fdf3ea3 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -565,7 +565,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = .{ @import("agent_empty_completion.zig"), @import("agent_length_cutoff.zig"), @import("agent_model_loop.zig"), @import("publication_policy_tests.zig"), @import("jobs_completion_tests.zig"), @import("headless_result.zig"), @import("oneshot.zig"), @import("agent_length.zig"), @import("agent_length_tests.zig") };
_ = .{ @import("provider_routing_tests.zig"), @import("codegraff_messages_tests.zig"), @import("tool_result_empty_tests.zig"), @import("history_wire.zig"), @import("path_lookup.zig"), @import("agents_prepare.zig"), @import("catalog_price.zig"), @import("readline_paste_number_tests.zig"), @import("test_hooks.zig"), @import("peer_wake_loop.zig") };
_ = .{ @import("list_dir_nearmiss.zig"), @import("tool_preview_tests.zig"), @import("stream_reconnect.zig") };
- _ = @import("repo_map.zig");
+ _ = .{ @import("repo_map.zig"), @import("cli_text.zig") };
_ = @import("agent_overflow_tests.zig"); // #414: and, through it, agent_overflow.zig's table tests
_ = @import("agent_gateway_retry.zig"); // #1019: flake vs overflow classification must stay reachable
_ = @import("agent_responses.zig"); // #1019: type:error frame message extraction
diff --git a/src/startup.zig b/src/startup.zig
index 1015527b..b6492fb7 100644
--- a/src/startup.zig
+++ b/src/startup.zig
@@ -266,7 +266,7 @@ pub fn runSubcommand(io: Io, gpa: Allocator, arena: Allocator, init: std.process
if (flags.help_flag or flags.version_flag) {
var hbuf: [4096]u8 = undefined;
var hw = Io.File.stdout().writer(io, &hbuf);
- if (flags.help_flag) try hw.interface.writeAll(cli.usage_text) else try hw.interface.print("graff {s}\n\n{s}", .{ main_mod.harness_version, cli.changelog_text });
+ try @import("cli_text.zig").print(gpa, &hw.interface, flags.help_flag, main_mod.harness_version);
try hw.interface.flush();
return true;
}