reyn chat

Start an interactive REPL session attached to an agent. Each user turn is dispatched through the chat router, which classifies the intent and either replies directly, runs a skill, or delegates to another agent.

Memory recall and write happen automatically inside the router phase — see concepts/memory.

Synopsis

reyn chat [agent_name] [OPTIONS]

agent_name is positional and optional. When omitted, reyn attaches to the auto-created default agent.

Options

Common runtime flags (--model, --output-language, --llm-timeout, --llm-max-retries) are shared with reyn run-once. See Common flags.

⚠️ Breaking change (#3924): --grant-file-write was removed from reyn chat (and reyn run-once / reyn pipe run / reyn web). Per-invocation permission flags don't scope well in a multi-agent system — measured zero real call sites anywhere in scripts/dogfood/CI, only the flag's own tests. Grant the same capability durably in reyn.yaml instead:

permissions:
  file.write: ["<zone-root>"]  # scoped to the working tree, #3925's ZoneRoot vocabulary
  file.read: allow

See Protect credentials from sandboxed commands.

Chat-specific flags:

Flag	Default	Description
--cui	off	Use plain console output (no TUI). Useful for piping output, debugging, or headless environments.
--no-restore	off	Skip restoring in-flight skill state AND skip loading the persisted chat transcript this run (neither is deleted — both load normally on the next run without this flag). Useful for debugging or starting a clean session.
--reset	off	Wipe in-flight skill state (snapshots + WAL) before starting. Audit logs in .reyn/events/ are preserved.
--banner	off	Show the ASCII-art startup banner (gradient REYN logo + agent / model info).
--eager-embedding-build	off	Await action embedding index build synchronously on the first turn (pays ~2–5 s once so search_actions is immediately available).
--exclude-tools NAMES	—	Comma-separated tool names to hide from the agent's LLM-visible catalog (e.g. web_search,web_fetch). The tools still exist and still run if the agent calls them by name; they are just not offered to the model's discovery surface this session.
--connect <URL>	off	Attach to a remote reyn web server over AG-UI (HTTP+SSE) instead of running a local session (e.g. --connect http://127.0.0.1:8080). The positional agent_name selects which agent on the server. AG-UI client dependencies are core (#5051) — no separate install step. Renders the SAME way as a local session: the inline CUI on an interactive TTY (with the main status bar — agent / model / cost / ctx% / working indicator — streamed over the wire), or the plain console for --cui / a non-TTY / piped output. Status-bar dropdowns are session-local and degrade to empty on a remote attach; /rewind shows a plain text list instead of the local picker. A closed-set intervention ([y]es/[A]lways/[n]o/[N]ever) now presents with the SAME choice-set panel a local session shows (#5050 — a remote client that connects/reconnects/switches to a session with an already-pending intervention used to fall back to free-text input; #5053 landed the wire data, #5064 landed the presentation). See how-to: remote thin client.
--token <SECRET>	off	Bearer token for --connect (the secret reyn web prints on launch, or a token configured via gateway.auth.token). Falls back to the REYN_WEB_AUTH_TOKEN env var. A same-machine UDS server may need none.

Agent workspace

Each agent persists state under .reyn/agents/<name>/:

• profile.yaml — name, role, optional allowed_mcp, optional preferences (#4206 ③: free-override config — see agent.md § preferences)
• history.jsonl — append-only conversation log (chat + agent-to-agent messages, with chain_id for cross-agent trace)
• events.jsonl — runtime events for reyn events
• memory/ — agent-scoped memory layer (MEMORY.md + body files)
• runs/ — workspaces for spawned skill runs

To resume a previous conversation, attach to the same agent:

reyn chat researcher

The default agent always exists. Create more with reyn agent new.

Slash commands

While a session is active, lines starting with / are intercepted and never routed to an agent.

Command	Effect
/agent edit role <text>	Rewrite the attached agent's persona
/agent new <name>	Create new agent and attach to it
/agents	List loaded agents and which one is currently attached
/answer <id-prefix> <text>	Answer a pending ask_user / permission prompt (id-prefix: any unique prefix of the intervention id)
/attach <name>	Switch the REPL pointer to another agent (the previous one keeps running in the background)
/attachment <path>	Attach ANY file to the next user message (multimodal input; any extension — mime resolved via stdlib mimetypes, never a reyn-specific table). /image remains the narrower, image-only convenience command; both queue onto the SAME shared attachment set
/budget [reset]	Full budget breakdown; /budget reset clears per-process counters (see config/budget)
/cancel	Cancel the in-flight turn (same as Esc / Ctrl+C) — reports what was actually cancelled, or that nothing was running
/clear-history (alias /clear)	Wipe chat history (destructive; clears in-memory + persistent history and the action-usage table; events/run-state/profile preserved)
/compact	Compact the conversation history now to free up the context window (see chat-compaction). #5888: an explicit /compact folds the WHOLE unprotected middle — it is a request to shrink, not a fit-check, so it no longer stops when the middle already fits (the reactive overflow ladder still folds only its shortfall). The reply names what it measured: window used/size, middle room/used, what the head/tail keep-window protected, and the seq already folded through. Turns inside that keep-window are still never folded — if it holds everything, the reply says exactly that
/concept <term>	Inline glossary lookup
/copy [N\|list]	Copy an agent reply to the clipboard (1 = newest, 2 = one turn back, …)
/cost	Quick token + USD cost summary for this agent
/exec <cmdline>	Run argv through the SAME sandboxed exec op the LLM's own exec tool uses — screen-only reply (exit code + stdout + stderr), never touches history.jsonl (#5837 stage 1). /exec-attach <cmdline> runs the same way but queues the result onto the shared /attachment//image attachment set, drained by the next user message. Gated the SAME way as the LLM's own exec tool call — see the tool axis row in Permission model § Axes for the mechanism, rather than restating it here. !<cmdline> and !!<cmdline> are client-side shorthand for /exec-attach//exec respectively (#5837 stage 2) — normalized before dispatch, so the server never sees a bang
/exit	Exit the chat (alias: /quit, Ctrl+D)
/help [<cmd>]	Slash command help — list all, or focus on one
/hook on\|off <name>	Enable/disable a hook for this session (live at the next dispatch; session-scoped — the hook still fires in the agent's other sessions; persists across restart). off only takes effect for a per-agent- or per-session-origin hook; a startup- or runtime-origin hook (config-file layers the agent cannot write) is protected — it keeps firing regardless (#5213/#5218). /hook off on a protected hook is refused and names the actual origin instead of claiming success — it does not persist the request either, so a later /hook inspection never shows a stale, inert disabled: entry (#5230). The status bar's Hook tab uses the SAME predicate the dispatcher enforces (#5222)
/image <path> (alias /img)	Attach an image to the next user message (multimodal input; png/jpg/jpeg/gif/webp/svg). See /attachment for any other file type
/list	List pending interventions
/memory [list\|view <name>]	Inspect project memory entries (see concepts/memory)
/model [<class>]	Show the session's model class and any override, or set a per-session model-class override with /model <class> (validated against known classes; clears on restart)
/open <ref>	Open a generated artifact (html/office/pdf/image — anything the terminal can't render) with the OS's own default app. The Artifacts tab (Art, bottom-chrome drawer) lists refs newest-first; selecting a row runs this for you
/pending [list\|discard <id>\|claim <id>]	List / discard / claim stalled cross-channel ops
/quit	Exit the chat (alias: /exit, Ctrl+D)
/reload	Hot-reload runtime config (.reyn/*.yaml) at the next turn boundary
/reset confirm	Reset in-flight run state (snapshots + WAL; audit logs preserved)
/resident	Approximate resident-memory breakdown by in-process container — count + shallow sys.getsizeof estimate, session-lifetime and process-global (including the LLM-client Router cache), no threshold, no eviction (#4497)
/rewind [seq]	Time-travel to an earlier checkpoint — no arg opens the picker menu; seq jumps directly (see Time-travel · How-to)
/session new \| switch <sid> \| list	Open / switch / list conversation sessions for the attached agent (see Sessions)
/tasks [cancel <task_id> [confirm]]	List this session's currently-running tasks (prompt/pipeline async launches), or request cancellation of one — the same list_tasks/cancel_task ops the LLM itself calls. Cancel is destructive (a prompt task's cancel reaches across to the target AGENT's live turn — the target's session id is not tracked, so a bare arg warns and asks for confirm, same two-step pattern as /reset) (see Multi-agent concepts)
/visibility on\|off <tool\|mcp\|category> <name>	Toggle this session's LLM visibility of a capability (hidden next turn / restored up to the agent's authorized envelope — an envelope-denied capability stays hidden)

/list / /answer are foundational — they let pending interventions coexist without blocking the prompt. /agents / /attach / /agent are the multi-agent workflow primitives; a spawned/delegated peer's progress is monitored via /agents (note: /attach switches the REPL's attached agent — unrelated to /attachment, which queues a file). /hook / /visibility are session-scoped LLM-catalog controls, mirroring the status bar's hook/tool/mcp/category chips. /copy is a conversation-pane utility; /image//attachment enable multimodal input; /exec//exec-attach run a sandboxed argv directly, mirroring the LLM's own exec tool rather than adding a new capability; /open launches a generated artifact with the OS's own default app (local sessions only — see the Artifacts tab).

Multi-agent behavior

If the router decides this turn would be better handled by another agent, it emits a messages_to_agents entry instead of (or in addition to) a skills_to_run entry. The receiving agent processes the request asynchronously; its reply is auto-routed back into the originating chain. See concepts/multi-agent for the full model.

A user-initiated chain emits an interim reply_text (the originating agent's first router turn) followed by a synthesized final reply (after delegate responses arrive). This preserves the "you'll see I'm working on it" UX even across hops.

The /attach slash lets you watch a delegate's progress mid-chain — the previous agent's session.run() keeps consuming its inbox, so coming back later still resolves cleanly.

Permission behavior

reyn chat is interactive: when a sub-skill needs a permission outside the defaults, the prompt blocks until you respond via the intervention queue. Choices can be persisted to .reyn/approvals.jsonl (see permissions reference).

Diagnosing slow startup

Set REYN_STARTUP_TIMING=1 before starting reyn chat to get a per-stage breakdown of where startup time went:

REYN_STARTUP_TIMING=1 reyn chat

The report prints to stdout after the TUI exits (quit normally, Ctrl-C, or a startup exception all trigger it) — the interface owns the screen while it's running, so anything printed earlier would be overwritten or corrupt the display. It lists a fixed set of stages (import, config, registry, plugins, mcp, session, client-prep:transport, client-prep:read-model, client-prep:tui-import, client-prep:app-construct, client-prep:other, tui-boot) each with its seconds and share of wall time, even a stage that took 0.00s — a stage that never printed a line would be indistinguishable from one that ran instantly, which is the more useful fact to preserve. client-prep:other (#3735) is the residual control-flow between the four named client-prep sub-stages, not a fifth independent measurement — the four plus this one always sum to exactly the client-prep span, so it never spills into the overall unaccounted line below. A final unaccounted line is the wall time none of the declared stages explain — the number to look at first if the breakdown itself looks unremarkable but startup was still slow, and the report itself flags it with a ⚠ line when it exceeds 20% of TOTAL (a likely instrumentation coverage gap, not just untimed work). Off by default; when unset, nothing is measured, formatted, or printed.

Examples

Start a new session against the default agent:

reyn chat

Attach to a named agent:

reyn chat researcher

Use a stronger model just for this conversation:

reyn chat --model strong

See also

• Reference: agent CLI — reyn agent new / list / show / rm
• Reference: topology CLI — reyn topology to declare communication structure
• Reference: multi-agent config — safety.loop.max_agent_hops
• Reference: state-dir — agents/ location
• Concepts: multi-agent
• Concepts: memory