Terminal

The Bub application provides two ways to interact in the terminal: bub run and bub chat. Both use the same model, tools, and Tape capabilities:

• bub run handles a single message and is suitable for one-off tasks;
• bub chat keeps the session open for continuous conversation.

Start an interactive session

Run the following command in your terminal to start an interactive session. You can then type a message and press Enter to send it:

bub chat

Use ,help to list the internal commands currently available. To exit, press Ctrl+D or enter ,quit or ,exit.

The toolbar shows the speed of the latest model call, measured from the first streamed chunk to the end of the response. It counts every output token, reasoning included, and excludes both the time before the first chunk and tool execution. The ttft next to it is that excluded time to first chunk. When the provider does not report usage, it shows speed:- tok/s.

You can also submit the first message directly at startup:

bub chat "Inspect this repository and suggest a first task."

Steer a running agent

If the model’s output diverges from your expectations while you are waiting for a response, or you want to add constraints, you can enter a new instruction directly in the interface to guide the agent’s behavior.

Steering adds an instruction while the current turn is still running so the agent can adjust the task in progress. You don’t have to wait for the current generation to finish; just type the correction and press Enter:

Do not modify files yet. List the problems and suggestions first.

The Bub app places the message in the steering inbox. The agent reads it when building a later model request; a model or tool call already in progress is not forcibly interrupted.

Bub’s admission actions are steer and follow_up; they differ in when the message takes effect:

Approach	Handling	Use it for
Steering	Injects into later model requests in the current turn; messages that cannot be consumed in time become pending messages	Correcting direction, adding constraints, and providing new information relevant to the current task
Follow up	Processed as a follow-up task after the current turn ends	Adding another task or running several requests in order

By default, the Bub app steers ordinary input while a run is in progress; there is no separate follow-up shortcut. Steering messages that the current turn does not consume automatically enter the pending queue instead of being dropped.

To stop the task in the current session, use ,quit; it clears pending messages and cancels running tasks.

View the reasoning process

Enter ,thinking to expand or collapse the model’s reasoning process:

,thinking

It only controls whether the terminal displays the reasoning deltas returned by the model; it does not change the model or the reasoning effort. To adjust reasoning effort, use:

,reasoning_effort high

The available values depend on the model provider. The setting takes effect from the next Turn and is saved in the current session’s Tape.

Choose a session

bub run uses cli:local as its default session ID, while bub chat uses cli_session. Specify the same session ID explicitly to continue history between the two entry points:

bub chat --session-id cli:echo
bub run --session-id cli:echo "Summarize what we discussed."

Use commands

The command prefix defaults to , and is used to skip the model call and execute a tool directly:

bub run ",help"
bub run ",fs.read path=README.md"

You can enter commands directly in an interactive session too. Press Ctrl-X to switch between Agent and Shell input modes; Shell mode automatically adds the command prefix to your input. Common commands include:

Command	Purpose
,model openai:gpt-5-mini	Switch the model for the current session
,reasoning_effort high	Set the reasoning effort for the current session
,code_mode enable=true	Enable code mode
,tape.info	View entries, anchors, and token usage
,tape.search query=error	Search the current session record
,tape.anchors	List context boundaries
,tape.handoff name=reviewed summary='...'	Move the default context start point and save a summary
,tape.reset archive=true	Archive the current Tape and start over
,thinking	Expand or collapse reasoning output

Note:

• ,tape.reset archive=true backs up the main Tape and its sidecar to <BUB_HOME>/tapes/, with a UTC timestamp and a .bak suffix in the file names. Using archive=false or plain ,tape.reset skips the backup. After a reset, a new session/start anchor is created, and the old files are not restored automatically.
• handoff does not generate or inject a summary automatically. summary is stored in the anchor’s state; whether it is read later depends on the prompt or context policy. See Tape for details.

Caution

Unregistered commands are handed to bash for execution. Before entering an unknown command, make sure it is a shell command you are willing to run.

Run background processes

In bub chat, use background=true to run a command in a separate background process:

,bash command='npm run dev' background=true

The result includes a shell_id. Use it to read output incrementally or terminate the process:

,bash.output shell_id=bsh-12345678
,bash.output shell_id=bsh-12345678 offset=1200 limit=4000
,bash.kill shell_id=bsh-12345678

Note:

• offset is the character position in the buffered output, not a line number; use next_offset from the returned value for the next read. limit caps the number of characters returned in this call.
• A foreground bash call waits 30 seconds by default. On timeout, the process is not treated as failed; it moves to the background and returns a shell_id. Adjust this with timeout_seconds. Background tasks should be managed within the same bub chat or gateway process, and they are cleaned up when the application exits.