Chat surfaces

Everything you can do at the werbos chat prompt: REPL flags, slash commands, private mode, mission scaffolding, the budget gate. The 'what can I type?' reference.

werbos chat is the canonical surface. The same engine drives werbos serve (HTTP), the React SPA, and the in-process WerbosClient, but the REPL is where the surface area lives most visibly. This page is the reference for everything you can type inside it — flags, slashes, private mode, missions.

Inside the REPL: `?` / `/help`

The fastest way to remember the surface:

werbos> ?
werbos> /help

Both render a quick-reference card with slashes grouped by surface:

chat:      /mirror /private /buddy /reset
eval:      /label /regressions
notebook:  /notebook (Tom)
skills:    /skill
vision:    /see [region|full|window|clear]
mission:   /goal /dream /tasks
budget:    /budget
schedule:  /schedule

Persona slashes

/mirror               # show current character / voice ratio (0-100)
/mirror 50            # change persistently for this session
/mirror 30 disagree with me on this  # one-turn override; resets after the AI replies

The mirror slider is the F.2 character/voice blend control. See personas for the full story.

Private chat — `--private` flag + `/private` slash

Private mode skips archive write at session finalize. Useful for ephemeral tasks where you don’t want a .pfm left behind.

werbos chat --private             # entire session is private

Inside the REPL:

werbos> /private                  # toggle private mode for the session
werbos> /private status           # show current state

Server-side counterpart:

POST /api/chats?private=1

The SPA renders a “private” badge on the active-chat header when this is set. chat.private_mode is exposed in the _active_chat_dict return shape so any UI can render the indicator.

The session still runs through every other surface — events, recorder, tool dispatch. Only the finalize archive write is skipped.

Vision — `/see` slash

/see                  # interactive region select (drag)
/see region           # same as above
/see full             # silent full-screen capture
/see window           # click-to-pick window
/see clear            # drop pending images without sending

Captures attach to the live session’s pending-images buffer; the NEXT typed message becomes the prompt. Pair with --vision-model for the model to actually see the image. See vision for the full surface.

Skills — `/skill` slash

/skill                # show current mode + list enabled skills
/skill list           # all skills with status (enabled, invocations, age)
/skill show <name>    # print the body
/skill enable <name>  # toggle enabled flag
/skill disable <name>
/skill mode <off|propose|auto>

Skills auto-fire when the user message matches their triggers. See skills for the design.

Tom + the notebook

werbos chat --tom                 # memoryless persona, only a notebook

Inside any session (Tom or default):

/notebook                         # show notebook + byte count
/notebook clear                   # wipe
/notebook edit <text>             # replace contents

The notebook is Tom’s only state across turns. Capped at 4 KB. Every Tom turn emits a KIND_TOM_ATTESTATION event proving history_length: 0. See personas for the compliance angle.

Mission scaffolding — `/goal` and `/dream`

/goal shapes long-running work; /dream is the wishful “someday-maybe” rung. Phases + status give background agents structured input to answer “which ticket moves an active goal forward?”

/goal                             # list active goals
/goal new <text>                  # create a new goal
/goal retire <id>                 # graveyard, not delete
/dream                            # list dreams
/dream new <text>                 # create

Goals + dreams persist as JSON in mission/<id>.json. The graveyard pattern (retired_at field, never deleted) keeps the diff history honest — git log mission/ answers “what did I commit to and when did I let it go?”

Background tasks — `/tasks`

/tasks                            # list pending + running tasks
/tasks status <id>                # detail for one task
/tasks cancel <id>                # mark cancelled

Tasks live in werbos.tasks.TaskStore (SQLite, optimistic-lock CAS via a version column). The asyncio runner yields to foreground turns — when you start chatting, the runner backs off until the AI turn-lock releases. See background tasks for the design.

Budget gate — `/budget`

Generic per-agent cost caps. Trips emit warden Alerts.

/budget                           # show current caps + spend
/budget set <agent> <amount>      # change a cap
/budget reset <agent>             # reset spend

Background agents call BudgetGate.check_or_pause() before spending; on BudgetExceeded they transition to waiting_human with a retry_after_utc so the next-day re-attempt has a deterministic trigger.

Reminders — `/schedule`

One-shot scheduled reminders with relative-duration parsing.

/schedule in 30m remind me to check the build
/schedule at 17:00 wrap up the day
/schedule in 2h dogfood the html persona
/schedule list                    # what's queued
/schedule cancel <id>

Powered by werbos.schedule.ScheduleStore + werbos serve’s background sweep. Reminders fire as foreground notifications; if you’re mid-chat, they queue until the next prompt.

Dogfood loop — `/regressions` and `/label`

/label good                       # mark the last assistant turn good
/label bad <reason>               # mark bad (the dogfood-replay agent reads this)
/regressions                      # show recent regressions surfaced by the replay agent

The replay agent re-runs bad-labeled turns through the current model nightly and surfaces /regressions items when the new result is better than the original — the chat-archive quality- feedback loop.

CLI flags

The full set is werbos chat --help; the subset that matters for day-to-day:

# persona surface
werbos chat --persona-name html       # packaged persona by slug
werbos chat --persona-file PATH       # load persona from disk
werbos chat --tom                     # memoryless persona
werbos chat --mirror 87               # character / voice ratio (0-100)
werbos chat --character-file PATH     # override the always-full 13%

# tools
werbos chat --tools calculator        # opt-in tools
werbos chat --no-shell                # disable shell tool (default leash)
werbos chat --confirm-shell           # prompt before each shell call
werbos chat --shell-yolo              # shell with no confirms (dangerous)

# vision
werbos chat --vision-model llama3.2-vision:11b
werbos chat --vision-host http://...  # vision model on a different host
werbos chat --vision-prompt "..."     # override the default vision prompt

# memory + context
werbos chat --memory-dir ~/notes      # custom memory dir
werbos chat --no-memory               # disable memory entirely
werbos chat --project-context-file PATH
werbos chat --no-project-context      # skip .werbos.md walk

# session shape
werbos chat --private                 # don't archive
werbos chat --backend mlx --adapter PATH  # MLX with a LoRA adapter
werbos chat --max-tokens 8192         # context budget

# archive
werbos chat --archive-dir ~/...       # custom archive dir
werbos chat --archive-format json     # alternative to .pfm

Quit tokens

The REPL accepts a generous set of “I’m done” tokens:

:q  :quit  :exit  quit  exit  bye  Q
Ctrl-D                # EOF
Ctrl-C                # interrupt; finalizes the archive cleanly

A second Ctrl-C during archive finalization escapes with a clean (interrupted; archive may be incomplete) message — no traceback.

Chat surfaces

Inside the REPL: ? / /help

Persona slashes

Private chat — --private flag + /private slash

Vision — /see slash

Skills — /skill slash

Tom + the notebook

Mission scaffolding — /goal and /dream

Background tasks — /tasks

Budget gate — /budget

Reminders — /schedule

Dogfood loop — /regressions and /label