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

hive-tmux.claude.composer

The prompt line (composer) of a Claude Code pane: type text into it and, for a slash command, read it back before submitting it.

Stratum: Pipeline, under hive-tmux.claude.compact. Every effect (tmux, sleep) goes through the host port.

The prompt line (composer) of a Claude Code pane: type text into it and,
for a slash command, read it back before submitting it.

Stratum: Pipeline, under `hive-tmux.claude.compact`. Every effect (tmux,
sleep) goes through the host port.
raw docstring

hive-tmux.claude.host

The host port the Claude pane verbs read and write through, and its one real adapter.

Stratum: Port + Boundary. Everything that touches the tmux server, the Claude Code state directory (~/.claude) or the clock is a key of the port map, so panes and compact are tested with a stub map and no tmux.

The adapter shells out to the tmux CLI rather than libtmux: the panes a supervisor watches are on whatever server the operator runs, not only the hive session the python bridge owns.

The host port the Claude pane verbs read and write through, and its one
real adapter.

Stratum: Port + Boundary. Everything that touches the tmux server, the
Claude Code state directory (~/.claude) or the clock is a key of the port
map, so `panes` and `compact` are tested with a stub map and no tmux.

The adapter shells out to the tmux CLI rather than libtmux: the panes a
supervisor watches are on whatever server the operator runs, not only the
`hive` session the python bridge owns.
raw docstring

hive-tmux.claude.interrupt

When may a compact job cut into a working turn? Pure: a screen and a row in, a verdict out. compact performs what this decides.

A /goal coordinator can keep ONE turn alive for hours by looping on 100 s ss wait calls (friction 20261121180326-2ea1d54b), so a job that waits for a turn boundary never sees one. Interrupting is the way out, but a keystroke into a working turn can cut a commit, a ship land or a kubectl apply in half. So the rule is narrow:

  • never while text stands at the prompt (someone's draft);
  • never while the running tool reads as a WRITE (write-markers);
  • under :auto, only on a pane whose /goal was active when the job began, after it waited :interrupt-after-ms for rest, and only while the running tool reads as a read-only wait (read-only-markers) or no tool runs at all (the model is thinking, the prompt is empty);
  • under true, the goal and wait gates are dropped and an unclassified tool is accepted; the write and prompt gates still hold.

How the interrupt is made is the caller's choice (:interrupt-via): :force-send type /compact (Claude Code queues it: Queued · ctrl+x ctrl+s to send now), then C-x C-s. Measured on Claude Code 2.1.330: a running foreground Bash is moved to the background, not killed, and the compaction starts at once. :escape Esc (up to 3 tries) until the spinner is gone, then /compact as usual (the raw-tmux recipe recycle-goal-pane.sh). Esc kills the running tool call.

Stratum: Promote. No tmux, no clock.

When may a compact job cut into a working turn? Pure: a screen and a row
in, a verdict out. `compact` performs what this decides.

A /goal coordinator can keep ONE turn alive for hours by looping on
100 s `ss wait` calls (friction 20261121180326-2ea1d54b), so a job that
waits for a turn boundary never sees one. Interrupting is the way out,
but a keystroke into a working turn can cut a commit, a `ship land` or a
`kubectl apply` in half. So the rule is narrow:

  * never while text stands at the prompt (someone's draft);
  * never while the running tool reads as a WRITE (`write-markers`);
  * under :auto, only on a pane whose /goal was active when the job began,
    after it waited :interrupt-after-ms for rest, and only while the
    running tool reads as a read-only wait (`read-only-markers`) or no
    tool runs at all (the model is thinking, the prompt is empty);
  * under true, the goal and wait gates are dropped and an unclassified
    tool is accepted; the write and prompt gates still hold.

How the interrupt is made is the caller's choice (:interrupt-via):
  :force-send  type /compact (Claude Code queues it: `Queued · ctrl+x
               ctrl+s to send now`), then C-x C-s. Measured on Claude Code
               2.1.330: a running foreground Bash is moved to the
               background, not killed, and the compaction starts at once.
  :escape      Esc (up to 3 tries) until the spinner is gone, then /compact
               as usual (the raw-tmux recipe recycle-goal-pane.sh). Esc
               kills the running tool call.

Stratum: Promote. No tmux, no clock.
raw docstring

hive-tmux.claude.panes

Claude Code panes as data: which tmux pane runs which Claude session, how full its context is, and whether it is working.

Strata: Collect list-raw / capture tmux reads through the host port Promote parse-panes / join-session / goal-text / pane-row pure Boundary panes / pane one call that does all of it

Three sources are joined, because no single one is enough: tmux list-panes pane id, target, cwd, title sessions/<pid>.json session id, name, busy|idle (Claude Code's own word) the pane's screen context tokens, /goal active, spinner

A bg session's process is not a child of the pane that shows it, so the join is by name: the footer rule (or the pane title) names the session, the same name ListAgents prints. cwd breaks a tie between equal names.

Claude Code panes as data: which tmux pane runs which Claude session, how
full its context is, and whether it is working.

Strata:
  Collect   list-raw / capture        tmux reads through the host port
  Promote   parse-panes / join-session / goal-text / pane-row   pure
  Boundary  panes / pane              one call that does all of it

Three sources are joined, because no single one is enough:
  tmux list-panes            pane id, target, cwd, title
  sessions/<pid>.json        session id, name, busy|idle (Claude Code's own word)
  the pane's screen          context tokens, /goal active, spinner

A bg session's process is not a child of the pane that shows it, so the
join is by name: the footer rule (or the pane title) names the session, the
same name ListAgents prints. cwd breaks a tie between equal names.
raw docstring

hive-tmux.claude.poll

Waiting on a Claude Code pane: poll its row until a predicate holds, until it is at rest twice in a row, until its prompt is free of anyone's text.

Two ways to wait for rest, and the difference matters:

settled idle idle twice, SETTLE-MS apart. A pane between two tool calls looks idle for a moment, so one idle read proves nothing. turn boundary idle once. Under a /goal Stop hook the pane starts its next turn within one poll, so the rest between turns lasts a single read and never two in a row: waiting for two can only ever time out (friction 20261116185504-0376516a).

:between-turns? in the opts selects the second; every waiter here honours it, so a job stays consistent across all of its steps.

Stratum: Pipeline, under hive-tmux.claude.compact. Every read, clock and sleep goes through the host port, so a test drives time.

Waiting on a Claude Code pane: poll its row until a predicate holds, until it
is at rest twice in a row, until its prompt is free of anyone's text.

Two ways to wait for rest, and the difference matters:

  settled idle   idle twice, SETTLE-MS apart. A pane between two tool calls
                 looks idle for a moment, so one idle read proves nothing.
  turn boundary  idle once. Under a /goal Stop hook the pane starts its next
                 turn within one poll, so the rest between turns lasts a
                 single read and never two in a row: waiting for two can
                 only ever time out (friction 20261116185504-0376516a).

`:between-turns?` in the opts selects the second; every waiter here honours
it, so a job stays consistent across all of its steps.

Stratum: Pipeline, under `hive-tmux.claude.compact`. Every read, clock and
sleep goes through the host port, so a test drives time.
raw docstring

hive-tmux.claude.registry

The tmux subdomain of the host's swarm tool: Claude and Codex discovery, with Claude compaction, re-seed and goal restore.

swarm tmux panes assistant panes with provider and capabilities; Claude: pane, target, name, session id, cwd, ctx-tokens, busy?, status, goal-active?, goal-age swarm tmux compact compact one pane, or every pane over threshold swarm tmux job one compaction job by id, or all of them

The `tmux` subdomain of the host's `swarm` tool: Claude and Codex discovery,
with Claude compaction, re-seed and goal restore.

  swarm tmux panes     assistant panes with provider and capabilities;
                       Claude: pane, target, name, session id, cwd,
                       ctx-tokens, busy?, status, goal-active?, goal-age
  swarm tmux compact   compact one pane, or every pane over threshold
  swarm tmux job       one compaction job by id, or all of them
raw docstring

hive-tmux.claude.screen

Pure reading of a Claude Code pane: the captured screen lines of one tmux pane in, the facts a supervisor needs out.

Stratum: Promote. Nothing here touches tmux, the filesystem or a clock; the lines come from hive-tmux.claude.panes, which is the Boundary.

What the screen carries (Claude Code 2.1.x):

  • Working… (26m 48s · ↓ 29.8k tokens) <- spinner line while a turn runs 260803 tokens · ◎ /goal active (26m) <- status line: context size, goal ──────────── caveman skill hydration ─ <- footer rule naming the session ❯ <- the prompt -- INSERT -- ⏵⏵ auto mode on <- vim mode + permission mode

The context count is the bare NNN tokens that opens the status line. The spinner line also says 29.8k tokens, which is the turn's output, so only a first segment made of digits and tokens counts.

Matching is plain string work, no regex: every shape here is a fixed glyph or word at a fixed edge of a line.

Pure reading of a Claude Code pane: the captured screen lines of one tmux
pane in, the facts a supervisor needs out.

Stratum: Promote. Nothing here touches tmux, the filesystem or a clock; the
lines come from `hive-tmux.claude.panes`, which is the Boundary.

What the screen carries (Claude Code 2.1.x):

  * Working… (26m 48s · ↓ 29.8k tokens)      <- spinner line while a turn runs
      260803 tokens · ◎ /goal active (26m)   <- status line: context size, goal
  ──────────── caveman skill hydration ─       <- footer rule naming the session
  ❯                                            <- the prompt
    -- INSERT -- ⏵⏵ auto mode on               <- vim mode + permission mode

The context count is the bare `NNN tokens` that opens the status line. The
spinner line also says `29.8k tokens`, which is the turn's output, so only a
first segment made of digits and ` tokens` counts.

Matching is plain string work, no regex: every shape here is a fixed glyph
or word at a fixed edge of a line.
raw docstring

hive-tmux.claude.sense

The sixth-sense classes the pane watcher's shouts become, so a supervisor hears pane changes with swarm ss wait instead of polling.

:sense/pane-idle a pane that worked settled idle :sense/goal-ended a pane's /goal stopped being active :sense/context-high a pane crossed the watch threshold upward :sense/pane-waiting a pane waits on a human (permission or other prompt) :sense/tmux-job a compact | say | goal job ended (detail job_status)

sixth-sense belongs to hive-agent, which this addon does not depend on, so its registry is resolved softly (the hive-elm pattern): without it the shouts are still piggybacked, only never pushed.

The sixth-sense classes the pane watcher's shouts become, so a supervisor
hears pane changes with `swarm ss wait` instead of polling.

  :sense/pane-idle      a pane that worked settled idle
  :sense/goal-ended     a pane's /goal stopped being active
  :sense/context-high   a pane crossed the watch threshold upward
  :sense/pane-waiting   a pane waits on a human (permission or other prompt)
  :sense/tmux-job       a compact | say | goal job ended (detail job_status)

sixth-sense belongs to hive-agent, which this addon does not depend on, so
its registry is resolved softly (the hive-elm pattern): without it the
shouts are still piggybacked, only never pushed.
raw docstring

hive-tmux.claude.watch

Watch Claude Code panes server-side and shout each change, so the agent that supervises them hears it through sixth-sense (swarm ss wait) instead of polling tmux.

Strata: Promote step pure: previous pane states + new rows -> states + events Boundary start! / stop! one watcher thread per process, shouts through the host

Events (see hive-tmux.claude.sense for the sense classes): :pane-idle a pane seen working is idle on two ticks in a row :goal-ended goal-active? went true -> false, or Goal achieved appeared :context-high ctx-tokens went from under the threshold to at or over it :pane-waiting the session status went to :waiting (a permission or other human prompt); once per waiting spell :tmux-job a compact | say | goal job ended (via job-ended!)

The first tick only seeds: a pane already idle when the watch starts is not news. Every shout is addressed to :parent, the supervisor's agent id, which is who ss wait hears by default.

Watch Claude Code panes server-side and shout each change, so the agent
that supervises them hears it through sixth-sense (`swarm ss wait`)
instead of polling tmux.

Strata:
  Promote   step            pure: previous pane states + new rows -> states + events
  Boundary  start! / stop!  one watcher thread per process, shouts through the host

Events (see hive-tmux.claude.sense for the sense classes):
  :pane-idle     a pane seen working is idle on two ticks in a row
  :goal-ended    goal-active? went true -> false, or `Goal achieved` appeared
  :context-high  ctx-tokens went from under the threshold to at or over it
  :pane-waiting  the session status went to :waiting (a permission or other
                 human prompt); once per waiting spell
  :tmux-job      a compact | say | goal job ended (via `job-ended!`)

The first tick only seeds: a pane already idle when the watch starts is not
news. Every shout is addressed to :parent, the supervisor's agent id, which
is who `ss wait` hears by default.
raw docstring

hive-tmux.config

Typed config for hive-tmux's Python bridge.

Currently exposes one knob:

:python-executable — path to a Python interpreter for libpython-clj to load. Repoints libpython-clj at a Python where libtmux is installed (e.g. a conda env).

Resolution chain (first non-nil wins, see coalesce):

  1. HIVE_PYTHON_EXECUTABLE env var
  2. HIVE_TMUX_PYTHON env var
  3. nil → caller falls back to host auto-detection or libpython-clj defaults.
Typed config for hive-tmux's Python bridge.

Currently exposes one knob:

  :python-executable — path to a Python interpreter for libpython-clj
                       to load. Repoints libpython-clj at a Python
                       where libtmux is installed (e.g. a conda env).

Resolution chain (first non-nil wins, see `coalesce`):
  1. HIVE_PYTHON_EXECUTABLE env var
  2. HIVE_TMUX_PYTHON env var
  3. nil → caller falls back to host auto-detection or libpython-clj
           defaults.
raw docstring

hive-tmux.events

Event registrations and fx handlers for tmux pane lifecycle.

Events: :tmux/pane-created — after pane is registered in state :tmux/pane-killed — after pane is killed and deregistered :tmux/task-dispatched — after task sent to pane :tmux/interrupt-sent — after C-c sent to pane :tmux/state-changed — after registry mutation

Effects: :tmux/log — log event via timbre

Event registrations and fx handlers for tmux pane lifecycle.

Events:
  :tmux/pane-created       — after pane is registered in state
  :tmux/pane-killed        — after pane is killed and deregistered
  :tmux/task-dispatched    — after task sent to pane
  :tmux/interrupt-sent     — after C-c sent to pane
  :tmux/state-changed      — after registry mutation

Effects:
  :tmux/log                — log event via timbre
raw docstring

hive-tmux.init

IAddon implementation for hive-tmux — tmux terminal backend.

Follows the vterm-mcp exemplar: reify + nil-railway pipeline. Zero compile-time hive-mcp dependencies — all resolved via requiring-resolve.

Usage: ;; Via addon system (auto-discovered from META-INF manifest): (init-as-addon!)

IAddon implementation for hive-tmux — tmux terminal backend.

Follows the vterm-mcp exemplar: reify + nil-railway pipeline.
Zero compile-time hive-mcp dependencies — all resolved via requiring-resolve.

Usage:
  ;; Via addon system (auto-discovered from META-INF manifest):
  (init-as-addon!)
raw docstring

hive-tmux.observe.hook-plan

Pure planning of the tmux set-hook invocations that install and remove ingestion.

The plan is DATA: a vector of argv vectors. Nothing here runs tmux, so the whole installation surface is testable without a server, and the boundary that does run it stays a one-liner.

Pure planning of the tmux `set-hook` invocations that install and remove
ingestion.

The plan is DATA: a vector of argv vectors. Nothing here runs tmux, so the
whole installation surface is testable without a server, and the boundary
that does run it stays a one-liner.
raw docstring

hive-tmux.observe.ingest

Joins a hook arrival to the registry and the event system.

Effects arrive as an injected map (:registry :deregister! :dispatch!) rather than as direct calls on hive-tmux.state and hive-events, so the whole arrival path is exercised against recording fns.

Joins a hook arrival to the registry and the event system.

Effects arrive as an injected map (`:registry` `:deregister!` `:dispatch!`)
rather than as direct calls on `hive-tmux.state` and `hive-events`, so the
whole arrival path is exercised against recording fns.
raw docstring

hive-tmux.observe.lifecycle

Start and stop tmux-originated ingestion for the addon.

Installing hooks is OPT-IN and off by default. set-hook -g is a persistent, server-wide change to the operator's tmux, and an addon that rewrites it on every init would be editing an environment it does not own. The listener itself is inert (a socket nobody writes to), so it starts by default and the operator turns on the half that touches their server.

Start and stop tmux-originated ingestion for the addon.

Installing hooks is OPT-IN and off by default. `set-hook -g` is a persistent,
server-wide change to the operator's tmux, and an addon that rewrites it on
every init would be editing an environment it does not own. The listener
itself is inert (a socket nobody writes to), so it starts by default and the
operator turns on the half that touches their server.
raw docstring

hive-tmux.observe.listener

UNIX-socket boundary: accepts hook arrivals and hands each decoded event to an injected dispatch fn.

The dispatch fn is an argument rather than a direct hive-events call, so the accept loop is exercised in tests against a recording fn and carries no dependency on the event system it feeds.

UNIX-socket boundary: accepts hook arrivals and hands each decoded event to
an injected dispatch fn.

The dispatch fn is an argument rather than a direct `hive-events` call, so
the accept loop is exercised in tests against a recording fn and carries no
dependency on the event system it feeds.
raw docstring

hive-tmux.observe.reconcile

Turns one hook arrival into a registry action.

The registry is keyed by ling-id while an arrival carries only a pane-id, so reconciling needs a reverse lookup. Planning is pure over a registry VALUE: the decision is testable without a registry, a tmux server or a socket, and the boundary that performs it stays a case over the plan.

Turns one hook arrival into a registry action.

The registry is keyed by ling-id while an arrival carries only a pane-id, so
reconciling needs a reverse lookup. Planning is pure over a registry VALUE:
the decision is testable without a registry, a tmux server or a socket, and
the boundary that performs it stays a `case` over the plan.
raw docstring

hive-tmux.observe.schema

Malli value objects for tmux-originated event ingestion.

JVM-only on purpose: malli arrives as a :mvn/version coordinate, which ClojureWasm does not resolve. The portable half of the subsystem lives in hive-tmux.observe.wire and carries no contracts of its own; these schemas describe its values from the JVM side, where they can be enforced and can generate tests.

Malli value objects for tmux-originated event ingestion.

JVM-only on purpose: malli arrives as a `:mvn/version` coordinate, which
ClojureWasm does not resolve. The portable half of the subsystem lives in
`hive-tmux.observe.wire` and carries no contracts of its own; these schemas
describe its values from the JVM side, where they can be enforced and can
generate tests.
raw docstring

hive-tmux.observe.wire

Wire format shared by the JVM listener and the cljw hook client.

This namespace is loaded by ClojureWasm, which resolves only :git/url and :local/root coordinates. It therefore requires nothing outside clojure.core and clojure.edn, and must stay that way: a :mvn/version dependency reached from here is silently skipped by cljw and fails at call time rather than load time.

Wire format shared by the JVM listener and the cljw hook client.

This namespace is loaded by ClojureWasm, which resolves only `:git/url` and
`:local/root` coordinates. It therefore requires nothing outside
`clojure.core` and `clojure.edn`, and must stay that way: a `:mvn/version`
dependency reached from here is silently skipped by cljw and fails at call
time rather than load time.
raw docstring

hive-tmux.python.bridge

Low-level Python bridge utilities via libpython-clj.

Copy-adapted from hive-agent-bridge.python.bridge — same pattern: lazy init, conda env detection, thin wrappers.

No asyncio needed: libtmux operations are synchronous.

Preflight status is a closed ADT (defadt PreflightStatus) with exhaustive adt-case matching for remediation hints.

Low-level Python bridge utilities via libpython-clj.

Copy-adapted from hive-agent-bridge.python.bridge — same pattern:
lazy init, conda env detection, thin wrappers.

No asyncio needed: libtmux operations are synchronous.

Preflight status is a closed ADT (defadt PreflightStatus) with
exhaustive adt-case matching for remediation hints.
raw docstring

hive-tmux.python.tmux-ops

High-level libtmux operations — server/session/pane lifecycle.

Topology: One tmux session named 'hive' (configurable). Each ling gets its own window (full-width, not a split).

All operations are synchronous (<10ms) — no asyncio needed.

High-level libtmux operations — server/session/pane lifecycle.

Topology: One tmux session named 'hive' (configurable).
Each ling gets its own window (full-width, not a split).

All operations are synchronous (<10ms) — no asyncio needed.
raw docstring

hive-tmux.state

Atom-based pane registry for tmux terminal backend.

Maps ling-id -> {:pane-id, :window-id, :pane, :window, :cwd}.

Not DataScript — pane/window are Python object references that can't be serialized. The canonical ling registry in DataScript (via ds-lings) remains the source of truth for ling lifecycle; this atom is a local index for tmux-specific operations.

Atom-based pane registry for tmux terminal backend.

Maps ling-id -> {:pane-id, :window-id, :pane, :window, :cwd}.

Not DataScript — pane/window are Python object references that can't
be serialized. The canonical ling registry in DataScript (via ds-lings)
remains the source of truth for ling lifecycle; this atom is a local
index for tmux-specific operations.
raw docstring

hive-tmux.swarm-bridge

Bridge tmux pane lifecycle events into hive-mcp's swarm event backbone.

Problem:

  • hive-tmux emits re-frame-style events (:tmux/pane-created, :tmux/pane-killed, …) via hive.events. These are local to the hive-events router and never reach hive-mcp.channel.core, NATS, or the swarm/sync handlers.
  • When a tmux pane is created outside the standard Ling/spawn! flow (or when the JVM spawn path is bypassed for any reason), the swarm registry never learns about the slave and swarm_status shows nothing.

Solution:

  • On addon initialization, re-register the :tmux/pane-created and :tmux/pane-killed event handlers with wrapping handlers that preserve the original :tmux/log effect and ALSO emit a new :swarm/publish-slave-event effect.
  • The :swarm/publish-slave-event effect is handled by a fx registered here; it uses requiring-resolve to locate hive-mcp.swarm.event-bridge/publish-slave-event! and forwards the translated payload.
  • On shutdown, the original handlers are reinstated so that subsequent dispatches fall back to pure logging.

Design (SOLID/DDD/FP):

  • SRP: this ns ONLY translates :tmux/pane-* → :slave-* and forwards via publish-slave-event!. No direct DataScript writes, no NATS coupling.
  • DIP: depends on hive.events (stable re-frame API) and on a requiring-resolved var from hive-mcp. No compile-time coupling to hive-mcp.
  • OCP: adding a new tmux event → slave event mapping is a single entry in event->slave-type plus a pure payload-translator fn.
  • Pure helpers (translate-pane-created, translate-pane-killed) are side-effect free and trivially testable. Side effects live at the boundary (publish!, start!, stop!).

Loop safety:

  • publish-slave-event! already handles NATS loop prevention via the :via :nats-bridge tag. Events emitted from this bridge are additionally tagged with :source :hive-tmux for traceability.
  • Duplication with the JVM Ling/spawn! path is harmless because add-slave! in ds-lings is idempotent (upsert-style) and the swarm/sync handlers reconcile by slave-id.
Bridge tmux pane lifecycle events into hive-mcp's swarm event backbone.

Problem:
- hive-tmux emits re-frame-style events (`:tmux/pane-created`,
  `:tmux/pane-killed`, …) via `hive.events`. These are local to the
  hive-events router and never reach `hive-mcp.channel.core`, NATS,
  or the swarm/sync handlers.
- When a tmux pane is created *outside* the standard `Ling/spawn!`
  flow (or when the JVM spawn path is bypassed for any reason), the
  swarm registry never learns about the slave and `swarm_status`
  shows nothing.

Solution:
- On addon initialization, re-register the `:tmux/pane-created` and
  `:tmux/pane-killed` event handlers with wrapping handlers that
  preserve the original `:tmux/log` effect and ALSO emit a new
  `:swarm/publish-slave-event` effect.
- The `:swarm/publish-slave-event` effect is handled by a fx
  registered here; it uses `requiring-resolve` to locate
  `hive-mcp.swarm.event-bridge/publish-slave-event!` and forwards
  the translated payload.
- On shutdown, the original handlers are reinstated so that
  subsequent dispatches fall back to pure logging.

Design (SOLID/DDD/FP):
- SRP: this ns ONLY translates `:tmux/pane-*` → `:slave-*` and
  forwards via `publish-slave-event!`. No direct DataScript writes,
  no NATS coupling.
- DIP: depends on `hive.events` (stable re-frame API) and on a
  `requiring-resolve`d var from hive-mcp. No compile-time coupling
  to hive-mcp.
- OCP: adding a new tmux event → slave event mapping is a single
  entry in `event->slave-type` plus a pure payload-translator fn.
- Pure helpers (`translate-pane-created`, `translate-pane-killed`)
  are side-effect free and trivially testable. Side effects live
  at the boundary (`publish!`, `start!`, `stop!`).

Loop safety:
- `publish-slave-event!` already handles NATS loop prevention via
  the `:via :nats-bridge` tag. Events emitted from this bridge are
  additionally tagged with `:source :hive-tmux` for traceability.
- Duplication with the JVM `Ling/spawn!` path is harmless because
  `add-slave!` in ds-lings is idempotent (upsert-style) and the
  swarm/sync handlers reconcile by slave-id.
raw docstring

hive-tmux.terminal

ITerminalAddon implementation for tmux-based ling lifecycle.

Spawns Claude CLI instances in tmux panes via libtmux. All hive-mcp dependencies resolved at runtime via requiring-resolve (zero compile-time coupling).

Uses hive-dsl rescue/guard instead of raw try-catch.

ITerminalAddon implementation for tmux-based ling lifecycle.

Spawns Claude CLI instances in tmux panes via libtmux.
All hive-mcp dependencies resolved at runtime via requiring-resolve
(zero compile-time coupling).

Uses hive-dsl rescue/guard instead of raw try-catch.
raw docstring

hive-tmux.vessel

TmuxVessel — IVessel implementation for tmux host environment.

Uses requiring-resolve for all hive-mcp dependencies (zero compile-time coupling). Follows EmacsVessel pattern — slave lookup via ISwarmRegistry/get-slave protocol.

Capabilities: #{:terminal} (no editor, delivery, or repl).

TmuxVessel — IVessel implementation for tmux host environment.

Uses requiring-resolve for all hive-mcp dependencies (zero compile-time coupling).
Follows EmacsVessel pattern — slave lookup via ISwarmRegistry/get-slave protocol.

Capabilities: #{:terminal} (no editor, delivery, or repl).
raw docstring

hive-tmux.vessel-target

The hive-vessel target of this addon: :text natives executed through the tmux CLI by hive-vessel.executor.tmux, on the session the python bridge drives.

Strata: target-opts is the pure Promote step (addon config -> executor opts); target is the Boundary that hands those opts to hive-vessel's executor; hooks-for is the addon-facing projection, resolved per call so a consumer holding the hook sees nil once the addon is shut down.

The hive-vessel target of this addon: :text natives executed through the
tmux CLI by hive-vessel.executor.tmux, on the session the python bridge
drives.

Strata: `target-opts` is the pure Promote step (addon config -> executor
opts); `target` is the Boundary that hands those opts to hive-vessel's
executor; `hooks-for` is the addon-facing projection, resolved per call so
a consumer holding the hook sees nil once the addon is shut down.
raw 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