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#

1

$ 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:

1
2
3
4
5
6
7
8

╭─ ≋  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:

1
2
3
4
5
6
7
8
9

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 <id>` 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:

1

▸ what's in SCAIFLUX.md?

What you see while the model thinks:

1

⠋ 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:

1

⠙ ● read_file(path=SCAIFLUX.md)  0.2s

When the tool completes, it collapses to a one-line summary:

1
2

● 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:

1

— 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:

5. Persisting settings#

Most REPL settings are session-scoped by default. Pin them with /save:

1
2
3
4
5

▸ /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):

1
2

▸ /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.<slug>.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:

1
2
3
4
5
6

▸ /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/<workspace-slug>/). 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:

1
2
3
4

▸ /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.