The Kloudlite harness

Description and operation

General

The Kloudlite harness is the program kl-tui. kloudlite opens a session in it, and you direct an agent that works in the session. The agent has the agent tools of the session and your rights. kl-tui is installed next to kloudlite.

kloudlite opens the session in this order: --session, the session that you selected with kloudlite sessions use, your only session. With more than one session and none selected, it asks you to choose. With no session, it creates main with no environment.

While the harness is open and a turn, a tool call or a client is in use, it sends a hold every 60 seconds. The session then does not go idle. After 30 minutes without use, the session goes idle and its workspaces stop. See Sessions.

The harness has no tool to change the session. It has session_current, session_connect and session_disconnect for the environment of its own session. session_use and session_pick are tools of kloudlite mcp.

Type these commands in the prompt of the harness.

Screen

The chat fills the left column. A title bar names the conversation: Working Session for the session itself, or the name of a workspace. The transcript is below it and the prompt is under the transcript. The prompt card names the conversation that receives your text and the model that answers. The bottom row shows the environment name, the size of the context, for example 84k ctx, and the keys that work now.

The sidebar is on the right when the terminal is wider than 120 columns. Its Workspaces list shows the workspaces of the session. A row says working while the agent of that workspace works, and needs you while a card waits for you. The Environment block shows the connected environment and its services. On a narrower terminal, /settings sidebar show opens the sidebar over the chat.

The harness has five views. Click a hint in the bottom row to open a view, or use its key.

Files shows a workspace only. In the session itself, the harness says enter a workspace first — f opens its files.

Keys

The setting vim chooses the key scheme. The default is off: the prompt always takes your typing, and commands use ctrl with a letter. With vim on, the keyboard has two modes. In NORMAL mode a letter is a command, and i starts INSERT mode, where you type. esc in INSERT mode clears the draft and returns to NORMAL mode.

The mouse works on every row that you can select. You can click a sidebar row, a hint, the title bar, a card option or a row of the Files view. Click a collapsed block of the transcript to open it. A block that is longer than 10 rows shows Click to expand.

The permission mode is default, acceptEdits, plan or bypass. The bottom row names it when it is not default. The mode returns to default each time the harness starts.

A conversation of the harness is not a Kloudlite session. When the agent changes something that you did not ask for in this turn, the harness shows a permission card with the reason.

Tasks

Open a session

Reason for the task: Direct an agent in a session.

Job set-up

• Access: you. For a team session, a team member whose access is not paused.
• Agent tool: none; an agent uses the SDK.
• Conditions: kl-tui is installed next to kloudlite, and a session exists. See Create a session.
• References: kloudlite, Sessions API.

Procedure

1. Run kloudlite with the session. Put a team name first for a team session.

   CLICopy

   kloudlite acme --session dev

2. Add --start if the session is stopped.

Close-out

1. Make sure that the session opens. The first open can take up to 90 seconds.

Sign in and choose a model

Reason for the task: Connect a model provider so that the agent can answer.

Job set-up

• Access: you.
• Agent tool: none; an agent uses the SDK.
• Conditions: the harness is open. The harness does not offer the provider anthropic. To use Claude, see Claude Code plugin.
• References: none.

Procedure

1. Type /login and send it with enter. Each row names a provider and a method, oauth or api key.

2. Select a row and send it with enter. To skip the list, type the provider and the method.

   textCopy

   /login deepseek api_key

3. Open the URL that the harness prints, and enter the code if it shows one. For api key, paste the key at the › prompt, where the harness masks it.

4. Wait until the login screen closes. Use esc to cancel it.

5. Type /model, select a model, and send it with enter. The list shows only the models of providers that you connected.

Close-out

1. Make sure that the prompt card names the model.

The harness saves credentials in auth.json and the model in settings.json. Both are in ~/.config/kloudlite on the session's host, not on your computer. KLOUDLITE_CONFIG_DIR there sets another folder. A provider also reads its usual environment variable. With no saved model, the harness uses deepseek/deepseek-v4-flash when its list has it.

Send a prompt and follow the work

Reason for the task: Give the agent a task and watch it work.

Job set-up

• Access: you.
• Agent tool: none; an agent uses the SDK.
• Conditions: a model is connected. See Sign in and choose a model.
• References: Agent tools.

Procedure

1. Type the task in the prompt and send it with enter. With vim on, type i first.

   textCopy

   Run the tests in ~/workspace and fix the first failure.

2. Read the transcript. It shows the answer, the reasoning, and one row for each tool call with its state.

3. Read the row above the prompt. It names the tool that runs now, or thinking… or working….

4. Use pagedown or the wheel to scroll, and end to return to the end. Click a collapsed block to read all of it.

5. Type the next prompt during the turn and send it with enter. The harness queues it or cuts in, and ^s cuts in at once.

Close-out

1. Make sure that esc interrupt has left the bottom row. The turn is over.

A queued prompt shows as N queued in the bottom row. Type up on an empty prompt to edit the queue. In the queue, up and down select a prompt, enter returns it to the prompt, d drops it and esc leaves the queue.

Stop a running turn

Reason for the task: End a turn that goes the wrong way.

Job set-up

• Access: you.
• Agent tool: none; an agent uses the SDK.
• Conditions: a turn runs.
• References: none.

Procedure

1. Use esc. With vim off and text in the prompt, the first esc clears the text, so use it again.

Close-out

1. Make sure that the transcript shows interrupted.

Answer a permission or question card

Reason for the task: Let the agent continue after it asks you.

Job set-up

• Access: you.
• Agent tool: none; an agent uses the SDK.
• Conditions: a card replaces the prompt.
• References: none.

Procedure

1. Read the card. A Permission required card names a tool, for example workspace_delete, and gives the reason.

2. Select an answer with left and right, or with tab and shift+tab. A list of answers uses up and down.

3. Send the answer with enter. A permission card offers Allow once, Allow always and Reject.

Close-out

1. Make sure that the card has gone and the agent continues.

A list of answers is filtered by typing. You can also click an answer. A question card shows the question and the answers.

A permission card appears only for a tool that deletes something, and only when your words in this turn do not name the target. esc rejects a permission card. On a question card, esc selects the last answer. Allow always holds for that tool in that conversation until you quit the harness. A card shows only in its own conversation, and the sidebar marks the workspace needs you.

Switch workspace and view

Reason for the task: Talk to the agent of another workspace, or look at its files.

Job set-up

• Access: you. You can enter only your own workspaces.
• Agent tool: none; an agent uses the SDK.
• Conditions: the session has a workspace.
• References: Sessions.

Procedure

1. Select a workspace with a click on its row in the sidebar. The key ^p lists the workspaces and the session itself.

2. Open a view with ^f, ^j, ^g or ^q. With vim on, f opens the files.

3. Use esc to return to the chat.

Close-out

1. Make sure that the title bar and the prompt card name the conversation that you chose.

A click on a hint in the bottom row opens the same view. A turn goes on in its own conversation while you look at another one.

Read the files, the changes and the processes of a workspace

Reason for the task: See what the agent changed and what runs in the workspace.

Job set-up

• Access: you.
• Agent tool: none; an agent uses the SDK.
• Conditions: you selected a workspace that runs.
• References: Tool server.

Procedure

1. Open the Files view with ^f, or with f when vim is on. The left list has the CHANGES against HEAD above the FILES tree.

2. Select a row with j and k. Open it with l or enter, and use tab to move between the list and the reader.

3. Use v in the reader to flip a changed file between its diff and its whole text. Use n and shift+n to go to the next and the previous change.

4. Type / and a text to filter the paths. Use r to read the files again and esc to leave.

5. Open the Jobs view with ^j. Select a process with j and k, and open its log with l or enter.

6. Type / in the Jobs view to filter by name or command. Use esc to leave.

Close-out

1. Make sure that the header shows updated after the agent edits a file.

The log of a process follows its end. After you scroll up, G or F follows it again. A process that ended keeps its log in the list for 10 minutes. The key s does not search a workspace, and the harness says search is not available for workspaces.

Change a setting

Reason for the task: Change how the harness looks, types or thinks.

Job set-up

• Access: you.
• Agent tool: none; an agent uses the SDK.
• References: none.

Procedure

1. Type /settings and send it with enter. Each row is a setting, and the hint shows its value.

2. Select a setting and a value. To skip the lists, type both.

   textCopy

   /settings vim on

3. Type /theme and select tokyonight, kloudlite-dark, opencode or kloudlite-light.

Close-out

1. Make sure that the list shows the new value as current.

The default theme is kloudlite-dark. thinkingLevel, autoCompact and codemode apply to every open conversation at once. The harness saves each setting in settings.json.

Continue or start a conversation

Reason for the task: Return to earlier work, or begin again with an empty transcript.

Job set-up

• Access: you.
• Agent tool: none; an agent uses the SDK.
• References: none.

Procedure

1. Type /session and select a conversation to continue it. You can type /session use ID.

2. Type /session name TEXT to name the conversation. Type /session desc TEXT to add a line under the title.

3. Type /clear to start again. The harness archives the transcript, deletes nothing, and shows an empty chat.

Close-out

1. Make sure that the transcript shows the conversation that you chose.

The list of /session shows the conversations of the place you are in, with their age. There is no /session new. When the harness opens, it continues the last conversation of a place. /compact keeps the conversation and shortens the context. Text after /compact says what to keep.

Quit the harness

Reason for the task: Close the harness and leave the session running.

Job set-up

• Access: you.
• Agent tool: none; an agent uses the SDK.
• References: none.

Procedure

1. Type /exit and send it with enter. You can use ^c.

Close-out

1. Make sure that your shell prompt returns.

A running turn goes on in the session. The next kloudlite opens the session and finds it busy.

Troubleshooting