Imported from joshdholtz/ruckus (AGENTS.md). Install upstream with npx skills add joshdholtz/ruckus. Copyright stays with the author.

Driving ruckus from an agent

ruckus is scriptable two ways: the CLI (easiest) and the JSON-RPC socket (for long-lived integrations — see docs/PROTOCOL.md). Both talk to the same background daemon, which is started automatically on first use.

Every command that takes a <target> accepts a pane id, a tab name, or a substring of either. $RUCKUS_DIR (default ~/.ruckus) isolates state — set it to run a throwaway instance.

Inspect

ruckus status --json     # entire tree + pane states as JSON — parse this
ruckus status            # same, human-readable
ruckus ls                # compact tree

status --json returns { spaces, active_space, panes }. Each pane has id, title, cmd, cwd, status (running / exited{code}), activity (working / waiting / idle / done), and optional agent. cwd is updated live from the process (~1s). Poll activity to know when an agent you launched needs input or has finished.

Launch & control

ruckus new -d -n build -- cargo watch -x test   # new tab, detached (-d), named
ruckus split <target> right -- claude           # split a pane, run a command
ruckus send <target> "yes"                      # type into a pane (+Enter)
ruckus send <target> --no-enter "partial"       # no trailing Enter
ruckus focus <target>                           # make it the active pane
ruckus rename tab <id> "reviewer"               # rename a tab (or: rename space)
ruckus restart <target>                         # respawn an exited pane in place
ruckus kill <target>                            # kill + remove a pane
ruckus tail <target>                            # stream a pane's output

Configure

Agents can set up a user's environment without hand-editing TOML. Edits preserve comments and formatting.

ruckus config get ui.gutter                 # read one value
ruckus config set ui.gutter 2               # numbers, strings, bools
ruckus config set keys.quit '["alt-q","ctrl-q"]'   # arrays: pass valid TOML
ruckus config set theme.accent '"#ff8800"'  # quote string values
ruckus config unset ui.gutter               # revert to the built-in default
ruckus config list                          # print the whole file
ruckus config path                          # where it lives

Config keys are dotted paths into config.toml: ui.*, theme.*, glyphs.*, keys.*, notify.*. config set / unset auto-reload a running daemon and every attached TUI live — no restart. (Only ui.spinner_ms needs a restart.) ruckus reload forces a reload after a hand-edit of the file.

Report activity (prefer this over heuristics)

Built-in detection is best-effort (screen tail + optional OSC 133 / foreground process). If you know the truth — permission prompt up, tool call running — report it. While a report is set, the daemon stops guessing for that pane.

ruckus report-activity <pane> waiting   # needs the user
ruckus report-activity <pane> working   # tool call / thinking
ruckus report-activity <pane> idle
ruckus report-activity <pane> auto      # back to heuristics
ruckus report-agent <pane> claude       # labels the AGENTS list
ruckus report-agent <pane>              # clear label

Same via the socket as report_activity / report_agent — see docs/PROTOCOL.md.

Typical loop

pane=$(ruckus split build right -- claude | grep -o '[0-9]*')
# ... wait for it to need you ...
while :; do
  a=$(ruckus status --json | jq -r ".panes[] | select(.id==$pane) | .activity")
  [ "$a" = waiting ] && break
  sleep 2
done
ruckus send "$pane" "approved"