Kode harness (preview)

Overview

The Kode harness is the program kd-tui, installed next to kode. kode opens a desk in it, and you direct an agent that works in the desk. The agent has the agent tools of the desk, the Kode skills, and your rights. The harness does not offer the provider anthropic. To work with Claude, use the Claude Code plugin.

kode picks the desk in this order: --desk, the desk that you last opened with kode -s NAME, your only desk. With more than one desk and none opened, it asks you to choose. With no desk, it creates main with no environment.

The harness splits the work. The agent of the desk creates, starts, stops, and deletes workspaces and environments, and reads no code. The agent of each workspace changes the code of that workspace, and can start subagents in clones of it. The sidebar lists the workspaces of the desk, and a row says needs you when an agent waits for your answer.

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 desk then does not go idle.

Type these commands in the prompt.

The setting vim changes the keys to a NORMAL and an INSERT mode. /help shows the keys of each mode.

Tasks

Open a desk

Reason for the task

Direct an agent in a desk.

Job set-up

• Access: you. For a team desk, a team member whose access is not paused.
• Agent tool: none; an agent uses the SDK.
• Conditions: kd-tui is installed next to kode, and you are signed in. See Install kode.
• References: kode, Desks.

Procedure

1. Run kode with the desk. Put a team name first for a team desk.

   CLICopy

   kode acme --desk dev

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

Close-out

1. Make sure that the desk opens. An idle desk wakes during the open.

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.
• References: none.

Procedure

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

2. Select a row and use enter. To skip the list, type the provider and the method.

   textCopy

   /login deepseek api_key

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

4. Type /model, select a model, and use enter. The list shows only the models of connected providers.

Close-out

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

The harness saves the credentials in auth.json and the model in settings.json, in ~/.config/kode on the host of the desk, not on your computer. A provider that refuses a request with 401 or 403 shows as blocked in /model. Select the row to sign in again.

Give a task 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 use enter.

   textCopy

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

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

3. Use esc on an empty prompt to stop a turn that goes the wrong way.

Close-out

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

Answer a permission 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 and an action, for example workspace with delete, and gives the reason.
2. Select Allow once, Allow always, or Reject with left and right. Use enter to send it.

Close-out

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

A permission card shows only for a tool that deletes something, and only when your words in this turn do not name the target. esc rejects the card. Allow always holds for that tool in that conversation until you quit the harness.

Read the changes of a workspace

Reason for the task

See what the agent changed and what runs in the workspace.

Job set-up

• Access: you. You can enter only your own workspaces.
• Agent tool: none; an agent uses the SDK.
• Conditions: the desk has a workspace that runs.
• References: Tool server API.

Procedure

1. Use ^p and select the workspace.
2. Use ^f to open the Files view. The list has the CHANGES against HEAD above the FILES tree.
3. Select a row with j and k, and open it with enter. Use v to flip a changed file between its diff and its text.
4. Use ^j to open the Jobs view. Select a process and open its log with enter.
5. Use esc to return to the chat.

Close-out

1. Make sure that the title bar names the workspace that you selected.

Troubleshooting