th claude: tmux-driven Claude Code session supervisor + smooth plugin marketplace#116
Merged
Conversation
🦋 Changeset detectedLatest commit: 3728270 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
…gine v1) Adds `th claude run/ls/attach` and a dependency-light `smooth-tmux` crate. `th claude run` launches Claude Code in an isolated tmux session and supervises it: when the account-wide "temporarily limiting requests" throttle fires, it backs off with full jitter (pool-aware RateLimitGovernor) and resends the last message until it lands — preferring the message it sent, falling back to scraping the last user turn from the pane. Why: the throttle currently leaves a Claude Code turn dead on screen with no auto-recovery. This is the 1:1 vertical slice of the broader topology (1→N Big-Smooth-led farm, N→1, mixed) — all later wirings of the same supervisor + governor + registry primitives. The governor is shared so a 429 on any session backs off the whole pool rather than thundering the herd. - crates/smooth-tmux: spawn/send(bracketed-paste)/capture(scrollback)/idle (10 tests, incl. live tmux roundtrip) - claude/governor.rs: backoff+jitter + circuit breaker (pure math unit-tested) - claude/detect.rs: pane-state classification + last-message extraction - claude/registry.rs: ~/.smooth/claude/sessions/*.json + dead-session prune - claude/supervisor.rs: watch→govern→resend loop, Ctrl-C clean stop - 30 tests pass; clippy -D warnings clean; docs + changeset included Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DXqPyj8SvxyUbfyRPvBA6P
Adds a per-session control channel so Big Smooth and a human can share one tmux pane without typing over each other. `th claude mode <id> driving|manual|paused` writes a control file the supervisor reads each poll: - driving: supervisor sends task input + steering and rescues rate-limits - manual: human drives (attach); supervisor only rescues their throttled turn - paused: supervisor stands down (no sending, no rescue) The initial prompt is only sent while driving; rate-limit rescue is gated on the mode. Worker sessions now launch with SMOOTH_AGENT_HANDLE / SMOOTH_SESSION exported so the smooth-agent plugin can register them on the th-mail bus. `th claude ls` gains a MODE column. control.rs parse logic is pure + unit-tested (35 tests pass; clippy -D warnings clean). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DXqPyj8SvxyUbfyRPvBA6P
Adds the team's first Claude Code plugin marketplace (.claude-plugin/ marketplace.json, name "smooth") hosted in this repo, and its flagship smooth-agent plugin — the recipe layer over the `th claude` engine: - commands/smooth.md: /smooth orchestrator (status/run/add-agent/drive/manual/ mail/ls/attach) that shells out to `th claude` + `th msg`/`th agent`/`th pearls` - skills/agent-comms: worker reports status / answers pings over th-mail - skills/pearls-flow: worker tracks work as pearls - hooks/register-agent.sh (SessionStart): auto-registers a worker on th-mail under $SMOOTH_AGENT_HANDLE so Big Smooth can address it; no-op for plain claude Why: makes the orchestration recipe + th-mail/pearls awareness installable with `/plugin install smooth-agent@smooth` and versioned, instead of hand-symlinking skills into ~/.claude. The stateful engine stays in the `th` binary; this is the declarative recipe layer. Repo-specific guardrail hooks stay project-scoped. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DXqPyj8SvxyUbfyRPvBA6P
brentrager
force-pushed
the
th-49de8d-claude-driver
branch
from
a48f798 to
3728270
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The account-wide Claude Code rate-limit throttle ("Server is temporarily limiting requests · Rate limited") leaves a turn dead on screen with no auto-recovery. We want to drive Claude Code worker sessions that ride out the throttle, hand control between an orchestrator ("Big Smooth") and a human, and coordinate agents — installable as a Claude Code plugin.
What's here (3 phases)
Engine (
th claude, binary)smooth-tmuxcrate: spawn/send(bracketed-paste)/capture(scrollback)/idle, isolated per-session tmux socket.th claude run— launch Claude in a supervised tmux session; on the throttle, back off with full jitter (pool-awareRateLimitGovernor+ circuit breaker) and resend the last message until it lands. Real usage/quota limits are detected and not retried.th claude ls/attach— list (prunes dead) / hand your terminal to a session.th claude mode <id> driving|manual|paused— control switch so Big Smooth and a human share one pane without typing over each other.Recipe (
smoothmarketplace +smooth-agentplugin).claude-plugin/marketplace.json(namesmooth) +smooth-agent:/smoothorchestrator command,agent-comms/pearls-flowworker skills, and a SessionStart hook that registers a worker on the th-mail bus under$SMOOTH_AGENT_HANDLE.Verification
cargo clippy -- -D warningsclean;cargo fmtclean.ls/modeworked, session pruned clean on Ctrl-C.Deferred (follow-up pearls)
1→N farm +
th claude add(Phase C), full ratatui control TUI, full team marketplace (Phase E). This is the 1:1 vertical slice; all topologies reuse the same supervisor + governor + registry.Note
Drives Claude Code subscription auth. Backoff-and-resume that honors the limit is fine; large unattended fan-out is the ToS gray zone — worker count is kept tasteful and documented.
🤖 Generated with Claude Code