Liking cljdoc? Tell your friends :D

hive-tmux.claude.compact

Compact a Claude Code pane and bring it back to work: wait until it is idle, remember its /goal, send /compact, re-seed it with a prompt, then set the goal again.

The goal step exists because /compact clears an active /goal: a peer that is re-seeded with catchup alone finishes catchup, finds no task and stops.

WAITING FOR REST. A job must not type into a working turn, so every step waits for rest first. A pane busy for ordinary reasons is read at a settled idle (idle twice, :settle-ms apart); a pane under a /goal Stop hook is read at its single turn boundary, because the hook restarts the next turn within a poll and twice-in-a-row can never happen on it (friction 20261116185504: 30 min at :wait-idle, then 337k -> 469k tokens). poll/wait-rest is the one waiter, so the choice holds across every step of a job.

Strata: Promote due? / ctx-drop / goal-after pure Pipeline compact! / say! / goal! drive the steps through the host port (waiting: poll; typing: composer) Boundary start! / job / jobs one background job per pane

Every effect (tmux, transcript, clock, sleep) goes through the host port, so the whole sequence runs in a test against a scripted screen.

Compact a Claude Code pane and bring it back to work: wait until it is
idle, remember its /goal, send /compact, re-seed it with a prompt, then
set the goal again.

The goal step exists because /compact clears an active /goal: a peer that
is re-seeded with catchup alone finishes catchup, finds no task and stops.

WAITING FOR REST. A job must not type into a working turn, so every step
waits for rest first. A pane busy for ordinary reasons is read at a settled
idle (idle twice, :settle-ms apart); a pane under a /goal Stop hook is read
at its single turn boundary, because the hook restarts the next turn within
a poll and twice-in-a-row can never happen on it (friction 20261116185504:
30 min at :wait-idle, then 337k -> 469k tokens). `poll/wait-rest` is the one
waiter, so the choice holds across every step of a job.

Strata:
  Promote   due? / ctx-drop / goal-after          pure
  Pipeline  compact! / say! / goal!               drive the steps through the host port
            (waiting: `poll`; typing: `composer`)
  Boundary  start! / job / jobs                   one background job per pane

Every effect (tmux, transcript, clock, sleep) goes through the host port,
so the whole sequence runs in a test against a scripted screen.
raw docstring

after-compact-reasonclj

(after-compact-reason reason {:keys [during]})

The :done reason of a compacted job that a later step stopped with REASON and DATA (compacted-end): a pane that stayed busy (:timeout or :busy) during step S reads :pane-busy-after-S; any other reason is kept.

The :done reason of a compacted job that a later step stopped with REASON
and DATA (`compacted-end`): a pane that stayed busy (:timeout or :busy)
during step S reads :pane-busy-after-S; any other reason is kept.
sourceraw docstring

blocking-viewclj

(blocking-view job)

What an :already-running refusal says of the BLOCKING job value: its id, kind, status, the first 80 characters of its text, and the step that typed, if one did.

What an :already-running refusal says of the BLOCKING job value: its id,
kind, status, the first 80 characters of its text, and the step that
typed, if one did.
sourceraw docstring

boundary-seenclj

(boundary-seen before-count boundaries)

Evidence from BOUNDARIES (panes/compact-boundaries of the transcript now) that a compaction finished after the BEFORE-COUNT boundaries there were when /compact was sent. {:by :compact-boundary :tokens post}, or nil.

Evidence from BOUNDARIES (`panes/compact-boundaries` of the transcript now)
that a compaction finished after the BEFORE-COUNT boundaries there were
when /compact was sent. {:by :compact-boundary :tokens post}, or nil.
sourceraw docstring

cancel!clj

(cancel! job-id)
(cancel! job-id reason)

Cancel JOB-ID for REASON (:cancelled by default) if it has not typed yet (cancel-verdict, decided inside the swap, so it cannot race the job's first keystroke). The job ends :cancelled, which frees its pane's slot, and its :on-end runs once with the cancelled job (the tmux-job sense). {:cancelled? true :job job}, or {:cancelled? false :refuse kw ...} naming why, e.g. :already-typed with the :step; nil when there is no such job.

Cancel JOB-ID for REASON (:cancelled by default) if it has not typed yet
(`cancel-verdict`, decided inside the swap, so it cannot race the job's
first keystroke). The job ends :cancelled, which frees its pane's slot,
and its :on-end runs once with the cancelled job (the tmux-job sense).
{:cancelled? true :job job}, or {:cancelled? false :refuse kw ...} naming
why, e.g. :already-typed with the :step; nil when there is no such job.
sourceraw docstring

cancel-jobclj

(cancel-job job reason now-ms)

JOB cancelled at NOW-MS for REASON, when cancel-verdict allows it; JOB unchanged otherwise.

JOB cancelled at NOW-MS for REASON, when `cancel-verdict` allows it; JOB
unchanged otherwise.
sourceraw docstring

cancel-verdictclj

(cancel-verdict job)

May JOB (a job value) be cancelled now? {:cancel? true}, or a refusal: :already-typed with the :step that typed first (a keystroke reached the pane, so cancelling would leave half a command there), :already-cancelled, or :not-active with the job's :status (it ended on its own).

May JOB (a job value) be cancelled now? {:cancel? true}, or a refusal:
:already-typed with the :step that typed first (a keystroke reached the
pane, so cancelling would leave half a command there), :already-cancelled,
or :not-active with the job's :status (it ended on its own).
sourceraw docstring

cancelled?clj

(cancelled? job)

Has JOB been cancelled? Terminal: nothing the job's runner writes after it may change its status (job-consistent?, the state atom's validator, enforces it).

Has JOB been cancelled? Terminal: nothing the job's runner writes after
it may change its status (`job-consistent?`, the state atom's validator,
enforces it).
sourceraw docstring

claim-typingclj

(claim-typing job step-key)

JOB about to type its STEP-KEY step: records the first step that types (:typed-step), after which cancel-verdict refuses. A cancelled JOB is returned unchanged, and must not type.

JOB about to type its STEP-KEY step: records the first step that types
(:typed-step), after which `cancel-verdict` refuses. A cancelled JOB is
returned unchanged, and must not type.
sourceraw docstring

compact!clj

(compact! h state ref opts)

Compact the pane REF names, through host H, recording progress in STATE (an atom). OPTS: see defaults, plus :force? (ignore the threshold), :instructions (text after /compact), :goal (replace the goal) and :goal-append (extend it). Returns STATE's final value.

The /compact step ends on proof that the compaction ran (send-and-compact!), never on a screen marker. A compaction proven while the pane then stays busy (someone else gave it work) is :done with :reason :pane-busy-after-compact and the texts it did not type under :unsent: the recycle worked, and typing into a working pane is what this job never does.

ONCE :compacted IS RECORDED THE JOB CANNOT FAIL. Every later wait for rest is advisory (stop!, compacted-end): a pane still busy after the re-seed, because the /goal is still in force and its Stop hook leaves no turn boundary, ends :done :pane-busy-after-reseed. What the step would have failed with is kept under :advisory, the texts not typed go under :unsent, and :reseed-pending / :goal-pending say which (friction 20261121201539-4a5836cb: cc-04c4ee28 and cc-804a41e1 compacted 463k -> 151k, then ended failed timeout). A job that never compacted still fails as before.

REST: see the namespace docstring. Nothing here lands on a running turn.

Compact the pane REF names, through host H, recording progress in STATE
(an atom). OPTS: see `defaults`, plus :force? (ignore the threshold),
:instructions (text after /compact), :goal (replace the goal) and
:goal-append (extend it). Returns STATE's final value.

The /compact step ends on proof that the compaction ran (`send-and-compact!`),
never on a screen marker. A compaction proven while the pane then stays busy
(someone else gave it work) is :done with :reason :pane-busy-after-compact
and the texts it did not type under :unsent: the recycle worked, and typing
into a working pane is what this job never does.

ONCE :compacted IS RECORDED THE JOB CANNOT FAIL. Every later wait for rest
is advisory (`stop!`, `compacted-end`): a pane still busy after the
re-seed, because the /goal is still in force and its Stop hook leaves no turn
boundary, ends :done :pane-busy-after-reseed. What the step would have
failed with is kept under :advisory, the texts not typed go under :unsent,
and :reseed-pending / :goal-pending say which (friction
20261121201539-4a5836cb: cc-04c4ee28 and cc-804a41e1 compacted 463k ->
151k, then ended `failed timeout`). A job that never compacted still
fails as before.

REST: see the namespace docstring. Nothing here lands on a running turn.
sourceraw docstring

compacted-endclj

(compacted-end job reason stop)
(compacted-end job reason stop last)

JOB, which recorded :compacted, stopped by a LATER step: :done all the same, since the compaction is what the job is for (friction 20261121201539-4a5836cb). REASON says why the rest did not go out; STOP, what that step would have failed or skipped with, is kept under :advisory, never as an :error; LAST is the pane's screen state (else STOP's :last). The texts not typed are under :unsent, :reseed-pending and :goal-pending name which. A goal the pane shows active is not pending: it is in force.

JOB, which recorded :compacted, stopped by a LATER step: :done all the
same, since the compaction is what the job is for (friction
20261121201539-4a5836cb). REASON says why the rest did not go out; STOP,
what that step would have failed or skipped with, is kept under
:advisory, never as an :error; LAST is the pane's screen state (else
STOP's :last). The texts not typed are under :unsent, :reseed-pending and
:goal-pending name which. A goal the pane shows active is not pending:
it is in force.
sourceraw docstring

ctx-dropclj

(ctx-drop before row drop-ratio)

Evidence from ROW that a compaction ran: its context fell below DROP-RATIO of BEFORE tokens. {:by :ctx-drop :tokens n}, or nil.

Evidence from ROW that a compaction ran: its context fell below DROP-RATIO
of BEFORE tokens. {:by :ctx-drop :tokens n}, or nil.
sourceraw docstring

default-reseedclj

source

defaultsclj

source

due?clj

(due? row threshold)

Should ROW be compacted at THRESHOLD tokens?

Should ROW be compacted at THRESHOLD tokens?
sourceraw docstring

goal!clj

(goal! h state ref opts)

Set the /goal of the pane REF names without compacting it: OPTS :goal replaces, :goal-append extends the pane's active goal (read from its transcript). Waits for a settled idle; text at the prompt is waited out up to :input-timeout-ms (deliver!), then stops the job.

Set the /goal of the pane REF names without compacting it: OPTS :goal
replaces, :goal-append extends the pane's active goal (read from its
transcript). Waits for a settled idle; text at the prompt is waited out up
to :input-timeout-ms (`deliver!`), then stops the job.
sourceraw docstring

goal-afterclj

(goal-after {:keys [goal goal-append]} captured)

The goal to set after the re-seed. GOAL (an override) wins over CAPTURED; APPEND is added to whichever applies. Nil when there is nothing to set.

The goal to set after the re-seed. GOAL (an override) wins over CAPTURED;
APPEND is added to whichever applies. Nil when there is nothing to set.
sourceraw docstring

idle?clj

Is ROW a Claude pane at rest? See poll/idle?.

Is ROW a Claude pane at rest? See `poll/idle?`.
sourceraw docstring

jobclj

(job job-id)

The current state of JOB-ID, or nil.

The current state of JOB-ID, or nil.
sourceraw docstring

job-consistent?clj

(job-consistent? job)

The job invariant a job's state atom validates: once cancelled (it carries :cancelled-at), a job stays :cancelled. A runner still waiting when its job was cancelled therefore cannot write a later status over it: the write is refused and the runner stops there.

The job invariant a job's state atom validates: once cancelled (it carries
:cancelled-at), a job stays :cancelled. A runner still waiting when its job
was cancelled therefore cannot write a later status over it: the write is
refused and the runner stops there.
sourceraw docstring

job-textclj

(job-text {:keys [kind opts]})

The text JOB would type, as a supervisor reads it: the prompt of a say, the /goal of a goal, the /compact (with instructions) of a compaction.

The text JOB would type, as a supervisor reads it: the prompt of a say,
the /goal of a goal, the /compact (with instructions) of a compaction.
sourceraw docstring

jobsclj

(jobs)

Every job, newest first.

Every job, newest first.
sourceraw docstring

say!clj

(say! h state ref opts)

Submit OPTS :text to the pane REF names as one prompt. Waits for a settled idle first unless :wait-idle? is false (then a busy pane is skipped). Done once the pane starts working on it, or settles: the reply itself can take an hour, read it later with read. Text at the prompt stops the job at once: a say is not queued behind someone's draft.

Submit OPTS :text to the pane REF names as one prompt. Waits for a settled
idle first unless :wait-idle? is false (then a busy pane is skipped). Done
once the pane starts working on it, or settles: the reply itself can take
an hour, read it later with `read`. Text at the prompt stops the job at
once: a say is not queued behind someone's draft.
sourceraw docstring

screen-stateclj

(screen-state row)

What a timeout reports of the pane's last ROW: enough for a supervisor to tell a slow pane from a stuck one without reading the screen itself.

What a timeout reports of the pane's last ROW: enough for a supervisor to
tell a slow pane from a stuck one without reading the screen itself.
sourceraw docstring

start!clj

(start! ref {:keys [sync? on-end supersede?] :as opts})

Start a background job on the pane REF names. OPTS :kind is :compact (default), :say or :goal. Returns the job map at once, or {:error ...} when that pane already has a running job. The job follows the pane by its tmux id, which /compact does not change. OPTS :on-end, a fn of the final job map, runs once when the job ends (how the watcher turns it into a sense). Pass :host in OPTS to use another port (tests); :sync? true runs in the caller.

A job cancelled (cancel!) before its first keystroke ends :cancelled: its state refuses any later status (job-consistent?), its runner stops at its next wait (cancellable-host), and :on-end runs once, from cancel!.

:already-running names the blocking job (blocking-view) and hints supersede. OPTS :supersede? true cancels that job (reason :superseded) when it has not typed, and takes the slot; one that typed refuses :already-typed naming the step, and nothing is started.

Start a background job on the pane REF names. OPTS :kind is :compact
(default), :say or :goal. Returns the job map at once, or {:error ...} when
that pane already has a running job. The job follows the pane by its tmux
id, which /compact does not change. OPTS :on-end, a fn of the final job
map, runs once when the job ends (how the watcher turns it into a sense).
Pass :host in OPTS to use another port (tests); :sync? true runs in the
caller.

A job cancelled (`cancel!`) before its first keystroke ends :cancelled:
its state refuses any later status (`job-consistent?`), its runner stops at
its next wait (`cancellable-host`), and :on-end runs once, from `cancel!`.

:already-running names the blocking job (`blocking-view`) and hints
supersede. OPTS :supersede? true cancels that job (reason :superseded) when
it has not typed, and takes the slot; one that typed refuses :already-typed
naming the step, and nothing is started.
sourceraw docstring

start-refusalclj

(start-refusal kind opts row)

Why a KIND job with OPTS would stop at once on the pane whose row is ROW, without typing: {:reason kw ...}, or nil when it would go on to work. The same cheap checks the runners make first (compact!, start-row, say!), so a supersede cancels the blocking job only for a job that will actually run.

Why a KIND job with OPTS would stop at once on the pane whose row is ROW,
without typing: {:reason kw ...}, or nil when it would go on to work.
The same cheap checks the runners make first (`compact!`, `start-row`,
`say!`), so a supersede cancels the blocking job only for a job that will
actually run.
sourceraw docstring

unsent-afterclj

(unsent-after job)

The sends JOB planned after its /compact (:sends-planned, [{:step k :text t}]) that no step records as sent: [[k text] ...], in order.

The sends JOB planned after its /compact (:sends-planned, [{:step k
:text t}]) that no step records as sent: [[k text] ...], in order.
sourceraw docstring

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
× close