CLI command
jeden hillclimb
Improve a repository, or every repository of an organization, round after round without end: choose the next improvement, pursue it to an independently accepted result, record it, and choose again.
Exact invocation#
jeden hillclimb ["focus"] [--scope repository|organization [--only repo]...] [--rounds n] [--ledger path] [--deliver "text"] --allow-write --allow-command [--json] [--cwd path] [--model name] [--max-steps n]Inputs and options#
--scope repository(the default) climbs the repository--cwdnames;--scope organizationclimbs every repository directly under--cwd, each a directory holding.git.--only NAME, given once per repository, keeps an organization's climb to the repositories named; a name the directory does not hold, or--onlywith the repository scope, is an invocation refusal.- Words that are not options are the focus: what the operator wants the climb to favour (
"onboarding and error messages"). Without them the climb chooses freely. --rounds nstops after n rounds of this invocation; without it the climb runs until stopped.--ledger pathselects a ledger instead of~/.jeden/hillclimb/<sha256 of the scope's canonical path>.jsonl. Relative ledger paths resolve against the canonical--cwdworkspace, not the transport process's working directory.--deliver "text"says, in the operator's words, what a round does with its change before it is finished: commit it, queue it to land, open a request. Each round's objective carries it after what the chooser proposed, so the round's contract holds it, a round that changed the code and did not deliver it is not accepted, and its acceptance cites the evidence of delivery. The ledger keeps the objective as the chooser proposed it. Without--delivera round's change stays where the round left it. A blank value is an invocation refusal.- Default ledger identities preserve canonical path units, not a replacement-character label. Unicode scopes keep their existing UTF-8 key; non-Unicode Unix scopes hash exact native bytes, and non-Unicode Windows scopes hash a NUL-separated windows-wide domain followed by little-endian UTF-16 units. Symlinks to one canonical scope share its identity; distinct native paths do not share a ledger or writer lock merely because their lossy labels match. If the new lossless ledger does not exist but the former lossy ledger or its lock sidecar has an entry, selection refuses with the observed entry and available paths rather than silently adopting or abandoning ambiguous history. A sidecar alone does not prove a live worker. Select the intended file explicitly with --ledger; nothing is automatically migrated or rewritten. Upgrade readers and writers together for non-Unicode scopes: older versions cannot participate in the new identity/lock. Identity metadata probes retain their actual failures. Human labels and filesystem/JSON path refusals preserve native escaped units and the actual cause rather than a replacement path; ordinary Unicode labels remain unchanged. CLI, RPC and Desktop use this same resolver; rendered Desktop qualification remains separate.
- The native-byte identity reader journey is
JEDEN_BIN=… JEDEN_TEST_SOURCE_REVISION=… JEDEN_TEST_OPAQUE_WORKSPACE_A=… JEDEN_TEST_OPAQUE_WORKSPACE_B=… node tests/hillclimb/identity/journey.mjs. The declared UTF-8-addressable aliases must resolve to distinct real directories inside this checkout's ignored .build whose native bytes are invalid UTF-8 but have the same lossy label. Ordinary Unicode substitutes cannot qualify the case; unavailable filesystem fixtures are blocked, not passed. The journey only reads those scopes, creates its own UTF-8 aliases/home and legacy ledger artifact, and exercises real CLI/RPC identity separation, canonical alias equivalence, unchanged Unicode keys, ambiguous-history refusal, explicit ledger selection and native path-encoding refusals. It retains actual canonical path bytes as hex, source patch/revision, binary identity, commands, frames and reports under .build. This POSIX-byte fixture does not qualify Windows native UTF-16 or rendered GUI behavior. - The model route, maximum steps and workspace use the same options as
run. Write and command grants are required, because every round changes code and runs its checks. - An organization proposal must name exactly one immediate checkout admitted by
--only. Pursuit starts with that checkout as its working directory, not the organization parent. Repository scope accepts the same checkout only; the chooser may name.or omitrepository. - Organization discovery keeps exact Unicode checkout names, including a genuine replacement character; it never replaces invalid native name units to invent a selectable name. A repository name that the JSON chooser cannot represent is refused with its escaped native units before ledger ownership or model execution. Explicit
--onlynames are compared to native entries before inspection, so an unadmitted opaque or unreadable neighbour does not prevent an admitted checkout from being selected. For example,jeden hillclimb --scope organization --only my-project --cwd /path/to/organization --allow-write --allow-commandadmits only that exact immediate name. - The chooser's organization description and rejected-admission diagnostics render repository names as individually quoted, escaped strings rather than joining names with an ambiguous comma separator. A comma or newline inside one name therefore does not advertise additional checkout identities. Missing names are quoted as well, so an empty or whitespace-bearing input remains visible in the actual refusal.
- The native-byte identity journey also runs the real CLI and RPC organization discovery boundary against aliases to the one existing checkout, without creating another checkout. Its colliding native components come from the declared measured scopes. It checks distinct escaped-name failures at one unchanged organization/ledger location, excluded neighbours, explicit Unicode admission and an independently observed filesystem inspection refusal. A directory selected as the ledger safely prevents these refusal cases from reaching model execution even if discovery regresses; lock-sidecar observations distinguish discovery refusal from reaching that ledger boundary. Reports retain actual errors, native name bytes and request release. This diagnostic journey does not qualify a model-backed successful climb or rendered Desktop behavior.
- Desktop Only repositories uses Admit checkout and individually removable literal-name entries, not a line-separated list. Leading/trailing spaces, tabs, commas and embedded newlines belong to the selected name and are not trimmed or split. No entries explicitly admits every immediate checkout in Organization scope; an empty entry refuses before requesting a run instead of silently widening scope. Nonempty entries in Repository scope refuse with the scope correction. Start captures the exact names; later draft edits do not retarget the submitted request. CLI parity is repeated
--only NAMEarguments: quote a name containing spaces, for example--only ' sales '. - The maintained desktop admission journey is
node tests/hillclimb/journey.mjsinjeden-desktop. DeclareJEDEN_BIN,JEDEN_TEST_SOURCE_CHECKOUT,JEDEN_TEST_SOURCE_REVISIONandJEDEN_DESKTOP_TEST_SOURCE_REVISION. It requires clean committed native/desktop sources and a development native binary carrying that source's generated revision identity; an unrelated, dirty or opaque version refuses qualification. Its registered native test uses the actual retained desktop model and actual RPC process, real checkout aliases with whitespace/newline names, real filesystem refusals and an actual directory-ledger safety barrier. It observes exact captured admission, newer missing-name refusal, identified removal, empty-entry refusal and explicit return to unrestricted discovery without allowing model execution. It retains frames, process exit statuses, source and executable identities, unchanged-source inspections and receipts beneath Desktop's ignored .build. Missing native evidence or a disabled test cannot pass the runner. This boundary journey does not qualify Stado attachment, model-backed improvements or rendered controls; those remain separate real journeys, and uncompiled/unexecuted source is not a qualification result. - Jeden Desktop's Hillclimb screen reads and starts climbs through a Stado RPC attachment placed for the selected workspace. Its scope, focus, admitted repositories, model, round and execution limits, custom ledger and explicit write/command grants use the same native execution loop as the CLI. Recorded repository offers all identities, an exact recorded string, or no recorded identity; exact empty/whitespace names remain data and absent identity is never guessed as the current checkout. Ending selects All endings, Accepted or Failed. Recorded round selects an unsigned UInt64 ledger identity, not a row index or execution limit; empty selects every identity. Last rounds accepts a positive count and empty retains all matches. Read ledger identifies selections returned by that read and retained rows separately from whole-ledger counts; later form edits never relabel earlier observations. An older unfiltered response omitting repository selection is explicitly not reported. No matches in a nonempty ledger is distinct from no history. Invalid counts/identities fail before a request. Every required host capability is checked when ledger, count, ending, round and repository selectors are combined; unsupported selection is refused rather than changed. Request stop addresses only this connection's owned request; acknowledgement is not completion. Changing workspace or leaving the screen does not retarget or terminate an active climb.
jeden hillclimb --status [--ledger path] [--last n] [--ending accepted|failed] [--round id] [--repository name | --without-repository] [--json] [--cwd path]reads history without a model or mutation grants. JSON returns{ledger,rounds,accepted,total,ending,round,repository,withoutRepository}: total and accepted count the complete ledger, while rounds retains matching records in original order. Ending/round are null when unrestricted; repository is the exact selected string or null, and withoutRepository distinguishes absent-only from unrestricted repository selection. Repository, round and ending intersect before last-n retention; omitted --last retains every match without assuming identity equals physical row position. n must be a positive whole count supported on this host; round must be an unsigned whole u64 value. Missing, negative, fractional or unrepresentable values and unknown/missing endings refuse invocation; zero is a valid round representation, not a last-count. For example,jeden hillclimb --status --repository=my-project --ending failed --json --cwd /path/to/organizationinspects that recorded project's failed rounds; add--round <recorded-id>for one identity. An absent ledger is empty without being created; no matches preserves whole-ledger totals. Every physical record is decoded and validated before/after and outside any selection: malformed JSON/UTF-8 never becomes a successful prefix. Errors name physical line/path, count earlier blanks and preserve bytes. Memory retains only the selected suffix, current record and reusable buffer; this remains a full-file scan. Human output identifies the actual selection without floating-point conversion. History and a persistent lock sidecar do not establish worker liveness.- A repository selector compares the recorded optional string exactly, without trimming, path resolution, canonicalization or case folding.
--without-repositoryselects only omitted/null identities, not an empty recorded string. A literalallis an ordinary name, not a clearing token. Empty and option-like names use--repository=VALUE; the inline empty form is--repository=. Repository and without-repository selectors conflict rather than overwriting each other. This is historical metadata selection, not execution scope, target admission or--only. - The native
/hillclimb [--ledger path] [--last n] [--ending accepted|failed] [--round id] [--repository name | --without-repository] [--json]command uses the same typed selection in the TUI and native run interface without starting a model or climb. Quote paths/names containing spaces using native command syntax; use inline--repository=for an empty name. Its workspace is the current conversation's; CLI run selects it with its ordinary external --cwd option. Unknown options, invalid endings/identifiers and conflicting repository modes refuse. The built-in catalog declares this identity so history is handled locally rather than forwarded as a model prompt. - A climb owns
<ledger>.lockfrom before it reads history until it exits, so another invocation using that ledger cannot choose work from the same stale round number. The operating system releases ownership on exit; the sidecar remains and is not evidence of a running process. Do not unlink it to bypass a live owner. Status reads remain available while the climb owns it. - The real model-backed journey is
JEDEN_BIN=… JEDEN_TEST_SOURCE_REVISION=… node tests/hillclimb/climb.mjs. It uses isolated real checkouts, pauses only its own spawned climber to observe actual kernel-held ownership, verifies the competing CLI refusal and unchanged source/history, resumes the owner to independent acceptance, then reuses the ledger for an accepted organization round. Commands, exit statuses, source patch, source and binary hashes, and model-backed receipts are retained under.build/hillclimb. - The native control journey is
JEDEN_BIN=… JEDEN_TEST_MODEL=… JEDEN_TEST_SOURCE_REVISION=… node tests/hillclimb/control.mjs. It uses the actual RPC/CLI processes and Brama route: grant refusals, a bounded independently accepted improvement, workspace-relative ledger readback, cooperative cancellation, EOF cleanup, then a subsequent accepted CLI round using the released ledger. It retains raw frames, commands, exit statuses, source and binary identity, and receipts beneath.build. These journeys must actually pass against the candidate binary; source changes and capability advertisements do not qualify execution or the rendered Desktop screen. - Both model-backed journeys also require
JEDEN_TEST_REPOSITORY, its declaredJEDEN_TEST_REPOSITORY_ORIGIN, andJEDEN_TEST_HOME. Reserve one existing qualification checkout exclusively, directly beside Jeden's canonical checkout on main; its clean baseline must track exactly thetests/hillclimb/fixtures/README.mdandgreet.mjstemplates. The test neither clones nor initializes a nested repository. The home is a dedicated prepared real Brama profile inside Jeden's ignored.build, never the operator's home. Run the journeys serially. They retain changes before restoring their generated fixture work for reuse, refuse to rewind a changed HEAD/branch/origin, and keep both execution and restoration failures.
Output and state effect#
Each round a fresh read-only conversation reads the product's documentation, code, tests and the ledger of earlier rounds and answers one proposal: an objective, the repository it belongs in, whether it is a new capability or an improvement of one, and why. Earlier delivered choices are not chosen again; a failed one only with a different approach. The objective is then run exactly as jeden pursue runs one: contract, execution, independent acceptance, verdict and receipt. The round is appended to the ledger as one JSON line with its number, times, proposal, ending (accepted or failed), the verdict summary or the failure, and the receipt, before the next round chooses, so a climb stopped and started again goes on from where it stood. Standard error names each round's objective and ending as it happens; the result lists this invocation's rounds and how many were accepted (--json: scope, ledger, rounds, accepted). In the terminal, /hillclimb shows the workspace's ledger.
Refusals and boundaries#
- Without both grants:
hillclimb changes the code it improves and runs its checks: it needs --allow-write and --allow-command, or --yolo, an invocation refusal. - A repository scope whose directory has no
.git, or an organization scope with no repository directly under it, is an invocation refusal naming the directory; so is an unknown scope, a--roundsthat is not a whole number above zero, and an option hillclimb does not take. - A ledger line that is not a round is refused as
line <n> of the hill-climb ledger <path> is not a round; it is never skipped. A record read or invalid UTF-8 isline <n> of the hill-climb ledger <path> cannot be read: <cause>. The physical line, path and observed cause reach CLI, RPC and Desktop diagnostics; neither refusal returns partial history as success. - A live owner is refused before choosing or executing:
another hill-climb owns ledger <path> (lock <path>); this climb has not chosen or executed a round. A directory, open or lock failure names the failed operation, affected path and operating-system cause; it is not reported as another owner. - A chooser answer without a JSON proposal or without an objective stops the climb naming the answer.
- A missing organization repository, an absolute or nested checkout name, an unadmitted
--onlychoice, an unresolved path, a symlink escaping the immediate organization checkouts, or a target without.gitstops before execution with the proposed repository and observed cause. - Repository directory and
.gitmetadata inspection failures retain their failed operation, native path and operating-system cause through CLI and the Desktop RPC result; only actual not-found evidence means absence. An unrepresentable admitted organization name is a named Unicode encoding refusal, not a replacement-character name, a missing repository or a successful empty organization. Discovery refusals occur before ledger locking or choosing a round. No checkout, ledger or name is rewritten to repair either condition. - A round that fails exactly as the round before it failed stops the climb:
hillclimb stopped after round <n>: it failed as the round before it did, so another round would fail again: <cause>. A single failed round is recorded and the climb chooses again. - A command line of the wrong form (an unknown command or option, a missing, unexpected or invalid argument, a missing confirmation) prints the error and the usage and exits
2; a refusal that retrying unchanged can help (a dependency down or not answering, a rate limit) exits69; any other refusal or failure exits1. A refusal a functionality declares ends withfix: …andcause: <operation>.<cause>, andjeden errors show <operation>lists every cause of that functionality.