--- title: REPL walkthrough path: guides/repl status: published --- # ScaiFlux REPL Walkthrough A narrative tour of the interactive REPL — what happens end-to-end from `scaiflux` at the prompt to a turn completing, plus the knobs you'll reach for most often. Aimed at someone who's just installed ScaiFlux and wants to feel productive in five minutes. For the reference surface (subcommands, flags, slash-command catalog) see **`USAGE.md`**. For install + auth see **`QUICKSTART.md`**. ## TL;DR - `scaiflux` drops you into a REPL. No subcommand needed. - If there are saved sessions in this workspace, a picker shows up first. Pick one to resume, type `n` for a new one, `q` to quit. - Type anything, hit enter. The spinner shows a rotating verb (`Foam Lancing…` on Poolnoodle models) with a timer + token counter + context-usage percent in real time. - Press **ESC** during model thinking to cancel. Ctrl-C stays the escape hatch for running tools. - `/help` lists every slash command. `/status` and `/context` show what's currently in play. `/save model` pins your current model as the workspace default. --- ## 1. First launch ```bash $ scaiflux ``` No arguments needed. ScaiFlux reads credentials from `~/.scaiflux/credentials.json` (created by `scaiflux login`), picks the default model from `.scaiflux.json → model` (or the login-time default), and shows the startup banner: ```text ╭─ ≋ ScaiFlux ≋ ──────────────────────────────────────────────╮ │ workspace /home/mbi/tmp/my-project │ │ mode workspace-write │ │ model scailabs/poolnoodle-omni │ │ limits max_tokens=16384 · context=256000 │ │ tools 27 registered │ ╰────────────────────────────────────────────────────────────────╯ ▸ ``` If the workspace already has sessions under `.scaiflux/sessions/`, you'll see a picker before the banner instead: ```text Existing sessions in this workspace # updated msgs first user message id 1 3m ago 47 refactor the parser session_1744… 2 2h ago 5 debug this crash session_1733… 3 yesterday 23 let's build a cat website! session_1732… Pick a session to continue, new, or quit. Type `d N` or `d ` to delete, `clear` to wipe all. > _ ``` Number → resume; `n` → fresh session; `q` → exit; `d 2` → delete #2 and keep picking; `clear` → nuke them all and start fresh. ## 2. A turn, in slow motion Type anything and hit enter: ```text ▸ what's in SCAIFLUX.md? ``` What you see while the model thinks: ```text ⠋ Sock Sorcering… 0.8s · 4.9K↓ · 2% ctx ``` Reading left-to-right: animated spinner · rotating "verb" (random from a 180-entry list, themed extras on Poolnoodle-family models) · elapsed time · input tokens sent · context-window used. The color of the `% ctx` readout goes green → yellow → red as the window fills. Then streaming text appears with rendered markdown, code fences syntax-highlighted, etc. If the model calls a tool, a dedicated tool spinner takes over: ```text ⠙ ● read_file(path=SCAIFLUX.md) 0.2s ``` When the tool completes, it collapses to a one-line summary: ```text ● read_file(path=SCAIFLUX.md) ✓ (47ms) (file contents rendered here, syntax-highlighted when the path is a code file) ``` Turn ends with a dimmed footer: ```text — 4872↓ · 123↑ · 3% ctx · 2 iter · end_turn ``` `↓` input tokens, `↑` output, `% ctx` context used, `iter` number of model→tool→model round-trips, stop reason. ## 3. Interrupting Two keys, two scopes: - **ESC** cancels the model while it's thinking or streaming text. The partial response is discarded; the REPL prints `⚠ interrupted by ESC — partial response discarded` and returns to the prompt. ESC is paused during tool execution so subprocess stdin isn't clobbered — a running `bash` command keeps its terminal as expected. - **Ctrl-C** is the universal escape hatch, including during tools. The subprocess gets SIGINT; if you hit it at the prompt, the REPL exits cleanly. Double-pressing ESC? First press stops the turn. Second press is just an ESC at the empty prompt (no-op). ## 4. Slash commands worth knowing Start with `/help` for the full catalog. The ones you'll reach for: | Command | What it does | |---|---| | `/status` | Workspace, model, mode, session id, message count | | `/context` | Context-window usage with a progress bar, message breakdown, tool count | | `/model ` | Switch models mid-session. Tab-completes from the catalog. Rejects unknown slugs with did-you-mean suggestions | | `/mode ` | Switch permission mode (`read-only`, `plan`, `workspace-write`, `danger-full-access`, `prompt`) | | `/clear` | Start a fresh session in this workspace | | `/cd ` | Tear down runtime, rebootstrap in a new workspace, carry conversation forward | | `/save ` | Persist current setting to `.scaiflux.json`. `` ∈ `model / mode / max-tokens / all`. `--global` writes to `~/.scaiflux/settings.local.json` | | `/session list` | List stored sessions for this workspace | | `/session delete ` | Remove one (refuses to delete the active session) | | `/session clear` | Wipe every session for this workspace | | `/memory` | Project memory and auto-memory tools | | `/reveal` | Print the last tool result in full (the REPL keeps it collapsed by default) | | `/banner` | Reprint the banner at the current terminal width | | `/poolnoodle on|off|status` | Toggle Poolnoodle mode 🛟 (see below) | | `/exit` or Ctrl-D | Leave the REPL | ## 5. Persisting settings Most REPL settings are session-scoped by default. Pin them with `/save`: ```text ▸ /model qwen/qwen3-30b-a3b model set to qwen/qwen3-30b-a3b ▸ /save model saved model → /home/mbi/tmp/my-project/.scaiflux.json [project] ``` Next launch in this workspace starts on that model. Use `--global` when the preference should apply across every workspace (e.g. your default permission mode): ```text ▸ /save mode --global saved mode → /home/mbi/.scaiflux/settings.local.json [global …] ``` Save order: the config hierarchy merges user-home → project → local, later wins. So `--global` acts as a fallback; per-workspace saves always override it. ## 6. Context management, in plain English Context windows fill up. ScaiFlux has a few layers between "you're fine" and "the model has no room to think": - **Pre-flight cap** — `max_tokens` is auto-derived from each model's context window (half the window, capped at 16 384). Override with `--max-tokens` or via `.scaiflux.json → model_limits..max_output_tokens`. - **Dynamic bound** — every turn, `max_tokens` gets clipped against remaining context minus a small safety margin. - **Ring buffer** — only the 5 most-recent tool results ride through at full size. Older ones become short stubs (or LLM-generated summaries if you've enabled `summarizer.auto_summarize_tool_results`). - **Warning injection** — cross 80 % and the model gets a user-role note asking it to wrap up. Cross 95 % and the note upgrades to "stop, summarise now". - **Auto-compaction** — at 100 k cumulative input tokens (overridable via `SCAIFLUX_AUTO_COMPACT_INPUT_TOKENS`), older messages are evicted. Priority-based: tool exchanges go first, user messages last. Watch it live with the `% ctx` readout on the spinner + footer, and inspect with `/context` any time: ```text ▸ /context context: ██████████████░░░░░░░░░░░░░░░░ 47% ~123,456 / 262,144 tokens (138,688 remaining) max output: 16,384 tokens / turn messages in session: 34 tools: bash, edit_file, glob_search, … ``` ## 7. Memory Two kinds: - **Project memory** — `SCAIFLUX.md` (and `AGENTS.md`, `.scaiflux/instructions.md`) walked up from the workspace. Loaded into the system prompt each turn, capped at 4 KB per file. Edit in an editor; changes land on the next bootstrap. - **Auto-memory** — the model can call a `memory_write` tool to save notes across conversations (`~/.scaiflux/memory//`). Notes are inlined into the system prompt on each turn, capped at 12 KB total. Types: `user`, `feedback`, `project`, `reference`. You almost never have to think about auto-memory — if you tell the model "remember I prefer pytest over unittest", it calls the tool and the preference sticks for every future session in that workspace. ## 8. Poolnoodle mode 🛟 An easter egg. Toggle on: ```text ▸ /poolnoodle on Poolnoodle mode: ON 🛟 Expect lighter emoji use, mild sarcasm, and strong opinions loosely held on the next turn. Saved to /home/mbi/tmp/my-project/.scaiflux.json. ``` The persona stanza lands at the top of the system prompt and anchors the voice for the rest of the session. Still the same engineering discipline underneath — it just teases the situation instead of answering like a dry form letter. `/poolnoodle off` returns to the default voice without drama. The banner gains a `gadgets` row when a gadget is active so you can tell at a glance. ## 9. Leaving cleanly - `/exit` or Ctrl-D at the prompt. - Session state persists automatically — every message lands on disk as it happens, so even a hard crash loses at most the in-flight model response. - Picker on the next launch lets you resume exactly where you stopped. ## Where next - **`USAGE.md`** — full reference for subcommands, flags, and slash commands. - **`QUICKSTART.md`** — first-install flow with auth setup. - **`PHILOSOPHY.md`** — why ScaiFlux is shaped the way it is. - **`.scaiflux.json`** — the config file. The schema at `https://scaiflux.dev/schema/scaiflux.schema.json` documents every option your editor will autocomplete.