Rando Dispatch

Focus, even when you can't.

Random thoughts in. Right routes out.

Rando Dispatch is project traffic control for coding agents. It catches each incoming thought, checks it against the active objective, and sends it down the right lane—without making you stop to organize your brain first.

You keep talking naturally. Rando keeps the mission from wandering off.

The problem

You are fixing the invitation flow. Then:

The settings page should support organization branding. Also, should we use Redis? And maybe this auth model is wrong.

A normal coding agent may treat all three ideas as the new plan. Rando treats them as incoming traffic:

Invitation fix                 → MAIN_PATH      → keep going
Organization branding         → SIDE_QUEST     → park it
Redis comparison              → FORK_RESEARCH  → investigate separately
Replace the auth model        → COURSE_CHANGE  → confirm before switching

No special prefixes. No lost ideas. No silent rewrite of the project because a thought arrived at full volume.

What Rando does

• Keeps a persistent objective for the project while activation remains session-scoped.
• Captures prompts locally before the agent acts on them.
• Suggests a route, then asks the host agent to validate it against the conversation.
• Splits compound prompts so one side idea does not swallow the main task.
• Parks useful thoughts without starting them.
• Dispatches bounded research or build work when the host supports forks or subagents.
• Tracks dispatches from queued through completed, failed, or cancelled.
• Requires explicit intent before replacing the active objective.

Routes

Route	What happens
MAIN_PATH	Continue in the current session.
BLOCKER	Interrupt, resolve the blocker, then return.
SIDE_QUEST	Save it for review; do not touch current work.
FORK_RESEARCH	Send a bounded read-only investigation to an isolated lane.
FORK_BUILD	Build in an isolated task, branch, or worktree; never auto-merge.
CAPTURE_ONLY	Preserve the thought without acting.
COURSE_CHANGE	Confirm explicit intent before replacing the objective.

One repo, two native plugins

Rando Dispatch uses one dependency-free Python core and ships two self-contained plugin packages:

• Codex: plugins/rando-dispatch
• Claude Code: claude-plugins/rando-dispatch

Each host gets its native manifest and marketplace entry. The routing behavior, commands, hook, and skill stay in sync through a reproducible build.

Install

Requirements: Python 3.9 or newer, plus Codex or Claude Code with plugin support.

Codex

codex plugin marketplace add zro-design/rando-dispatch
codex plugin add rando-dispatch@rando-dispatch

Start it inside each session where you want routing:

$rando start

Then prompt normally. You do not need to prefix every thought with $rando.

Codex discovers the packaged hooks/hooks.json through its plugin convention. The manifest intentionally does not duplicate that path.

Claude Code

claude plugin marketplace add zro-design/rando-dispatch
claude plugin install rando-dispatch@rando-dispatch

Start it inside each session where you want routing:

/rando-dispatch:rando start

Claude namespaces every marketplace-installed plugin skill, so /rando-dispatch:rando start is the normal form. Then prompt normally; use another Rando command only for deliberate management actions.

Update an existing installation

Codex:

codex plugin marketplace upgrade rando-dispatch
codex plugin add rando-dispatch@rando-dispatch

Claude Code:

claude plugin marketplace update rando-dispatch
claude plugin update rando-dispatch@rando-dispatch

Start a new task or restart Claude Code after updating so the new skill list is loaded.

Try a local checkout

git clone https://github.com/zro-design/rando-dispatch.git
cd rando-dispatch
python3 scripts/build_packages.py
PYTHONPATH=src python3 -m rando_dispatch.cli --session-id "manual-session" start "Ship the current milestone"

Rando commands

Start Rando once per host session, then free-type your thoughts normally. Project goals and captures persist, but a new session, /clear, or a forked resume does not inherit the prior session's started state. Use Rando resume to activate saved project state in the new session. The hyphenated shortcuts appear individually in skill suggestions; the original rando <action> forms still work.

Codex exposes the concise $rando-* shortcuts. Claude Code namespaces plugin skills as /rando-dispatch:rando-*.

Action	Codex	Claude Code	Use it when you mean…
Start	$rando start	/rando-dispatch:rando start	Protect this objective as the main mission.
Park	$rando-park "..."	/rando-dispatch:rando-park "..."	Definitely save this for later.
Dispatch	$rando-dispatch "..."	/rando-dispatch:rando-dispatch "..."	Investigate or build this separately now.
Switch	$rando-switch "..."	/rando-dispatch:rando-switch "..."	Intentionally replace the main objective.
Status	$rando-status	/rando-dispatch:rando-status	Remind me what we're doing.
Review	$rando-review	/rando-dispatch:rando-review	Show me the ideas Rando captured.
Pause	$rando-pause	/rando-dispatch:rando-pause	Temporarily stop automatic routing.
Resume	$rando-resume	/rando-dispatch:rando-resume	Turn automatic routing back on and restore the saved mission.

On Codex, the umbrella forms such as $rando status remain supported. On Claude Code, the equivalent umbrella form is /rando-dispatch:rando status.

If you simply have a tangent, just type it. Rando will capture and route it without requiring a command:

Maybe the settings page should support custom branding someday.

Use park, dispatch, or switch only when you already know exactly which action you want.

See the complete command cheat sheet for more examples, expected behavior, route meanings, and the advanced direct CLI.

For example, use $rando-status on Codex or /rando-dispatch:rando-status on Claude Code.

Local by default

Rando stores project state under .rando/:

.rando/
├── state.json       # project objective, progress, blockers, dispatches, decisions
├── sessions/        # hashed per-session start and pause state
└── prompts.jsonl    # private capture log with stable IDs

The directory and files use owner-only permissions where the operating system supports them. Rando has no runtime dependencies, network calls, telemetry, accounts, or hosted service. Add .rando/ to your global or project ignore rules when integrating manually; this repository already ignores it.

How the hook behaves

The lifecycle and prompt hooks are intentionally fast and non-blocking:

1. SessionStart records whether the exact host session is new, resumed, cleared, or compacted. New and cleared sessions begin unstarted.
2. If Rando is not started for the current session, or that session is paused, it says nothing and records nothing.
3. If active in the current session, it captures the prompt locally and assigns an rd-... ID.
4. A deterministic classifier suggests a preliminary route.
5. The host agent receives the objective, route, and guardrails as additional context.
6. The agent validates the suggestion, splits independent intents, and continues the active mission after parking or dispatching side work.

The heuristic is a traffic signal, not an oracle. Semantic judgment stays with the coding agent.

Current limits

Rando Dispatch is an alpha release.

• Fork and subagent execution depends on what the current host supports. Rando records and governs the lifecycle; it is not a background-job service.
• Compound-intent splitting is performed by the host agent, while the local classifier produces one preliminary whole-prompt suggestion.
• The first release uses transparent phrase and objective-overlap heuristics so behavior remains fast, local, and explainable.

Development

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m unittest discover -s tests -v
PYTHONDONTWRITEBYTECODE=1 python3 scripts/build_packages.py
PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate_repo.py

See the Command cheat sheet, Architecture, Contributing, and Security.

Why “Rando”?

Because the random thought is not the enemy. Losing it is frustrating; obeying all of them at once is chaos.

Rando catches the thought, calls the lane, and keeps traffic moving.

License

MIT © 2026 ZRØ Design