Skip to content

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

Python
25.0 KB
Raw Blame
//! 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.74.1
    \\  • a provider or model switch expands opaque compaction state from its checkpoint instead of replaying it
    \\
    \\0.302.74
    \\  • rejected compaction state restores exact input when a private checkpoint is available
    \\  • short TLS-construction outages get a longer bounded recovery window
    \\
    \\0.302.71
    \\  • computer use on macOS: graff ships nanocua, an app that lets agents work in other apps
    \\  • graff computer and /computer: status, stop, switches; turning input on takes your click
    \\  • Codex's computer-use plugins are no longer loaded
    \\
    \\0.302.70
    \\  • Claude Agent: a reply that starts during a tool-list refresh no longer fails
    \\  • simulator tests can't overwrite your clipboard; large uploads aren't cut off
    \\  • an empty-reply failure says what happened and how to retry
    \\
    \\0.302.69
    \\  • reading peer mail no longer rewrites history the model was already sent
    \\  • graff login kimi works for kimi.ai (international) accounts; sign-in links are copied
    \\  • workers can use gateway models; graff harness-tree shows the harness as one tree
    \\
    \\0.302.68
    \\  • Claude Agent: compaction writes a summary instead of continuing the task
    \\  • Claude Agent: a prompt after a finished turn keeps its images
    \\
    \\0.302.67
    \\  • Claude Agent: loading a tool no longer drops the call or ends the turn
    \\  • a finished task still hears peers who message it directly
    \\
    \\0.302.66
    \\  • a one-shot answer built on hosted search is kept, not bounced and replaced
    \\
    \\0.302.65
    \\  • Claude Agent models use their full 1M context window (was listed as 200k)
    \\
    \\0.302.64
    \\  • an expired Console sign-in is skipped, and the error says to run graff login console
    \\
    \\0.302.63
    \\  • auth errors say which credential was rejected: the sign-in, or the API key (and when it was the fallback)
    \\
    \\0.302.62
    \\  • rlm's llm_query works on Claude Agent, on a throwaway claude process
    \\
    \\0.302.61
    \\  • Claude Agent: Claude models through your own Claude Code login (graff login claude-agent)
    \\  • subagent requests keep agent_output in lean mode, so the turn waits for its workers
    \\
    \\0.302.60
    \\  • a resumed session keeps its real context size instead of re-estimating compaction state
    \\  • large compaction items work over WebSocket without re-running the turn
    \\
    \\0.302.59
    \\  • steadily arriving partial SSE events no longer trigger false stalls or replay
    \\  • genuine stalls still time out and unfinished events remain bounded
    \\
    \\0.302.58
    \\  • ACP startup and model discovery no longer wait on slow model-catalog hosts
    \\  • note_constraint states its 240-byte limit up front
    \\
    \\0.302.57
    \\  • images are typed by their bytes, so a mislabelled file no longer wedges a chat
    \\  • resending a prompt after a failed request makes a new request
    \\  • stream error events surface the provider's error instead of retrying
    \\  • withdrawn checklist items can be cancelled with a reason
    \\
    \\0.302.56
    \\  • native file tools follow dependency symlinks that stay inside the workspace
    \\  • escaping, dangling, and cyclic links remain blocked
    \\
    \\0.302.55
    \\  • help, release history, and bundled playbooks are compressed until needed
    \\  • long home paths keep the macOS background-launch protection
    \\
    \\0.302.54
    \\  • normal terminal startup is quiet; diagnostics stay opt-in
    \\  • live thinking shows Ctrl+T collapse/expand beside its header
    \\
    \\0.302.53
    \\  • smaller binaries share prompt text and compress runtime resources
    \\  • release builds keep safety checks and leave local learning optional
    \\  • workflow synthesis keeps its catalog at the final report boundary
    \\
    \\0.302.52
    \\  • clearer terminal status, Markdown emphasis, and checklist styling
    \\  • /workers opens a read-only browser of subagent activity and reports
    \\
    \\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 claude-agent         Claude through your own Claude Code login (`claude`)
    \\  graff login kimi                 Kimi Code OAuth login (kimi.ai; kimi.com for China)
    \\  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)
    \\  graff computer [status|stop|off|allow|grant|open]  nanocua's switches (macOS)
    \\
++ 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.
    \\
;