First Session

Open the TUI, compose a task, route it to an agent, review the output, and land the result

With Kavi installed and initialized, you are ready to run your first session. This page walks through the full lifecycle: opening the TUI, composing a task, watching it execute, reviewing the result, and landing the changes.

Start a Session

From your project root, run:

kavi open

Launches the keyboard-driven terminal interface with multiple views.

kavi start

Runs a session without the TUI, for scripting or CI.

The TUI at a Glance

The TUI has 9 views that you navigate with keyboard shortcuts. The key views for your first session are:

Compose -- where you describe what you want done
Execution -- where you watch agent output stream in real time
Review -- where you inspect the result before accepting it
Approval -- where tool calls appear for your approval

Compose a Task

In the Compose view, type a natural-language description of what you want. For example:

Add a health-check endpoint at GET /api/health that returns { status: "ok" }

Submit the task. Kavi analyzes your request and decides which agent should handle it.

Routing

Kavi routes tasks using a layered strategy:

Path and keyword rules -- if your .kavi/config.toml has routing rules that match the task, those fire first.
AI classifier -- if no rule matches, Kavi uses an LLM to classify the task and pick the best agent.
Ask the user -- if Kavi is uncertain, it asks you to choose.

You will see the routing decision displayed in the TUI. You can override it if you disagree.

Approve Tool Calls

As the agent works, it may request to run tools -- reading files, writing code, executing commands. Each tool call passes through the approval gateway.

You will see each pending tool call with a description of what it wants to do. Approve, reject, or modify each one. Nothing executes without your explicit consent.

Watch Execution

Switch to the Execution view to watch the agent's output stream in real time. You can see:

What files are being read or written
What commands are being run
The agent's reasoning and progress

Review the Result

When the agent finishes, move to the Review view. Here you can:

Inspect the diff of all changes made
Open a review thread with dispositions: accept, reject, or revise
Request revisions with specific feedback, which sends the task back to the agent

Land the Changes

Once you are satisfied with the result, land the changes:

kavi land

This merges the validated work into your branch. Only reviewed and accepted changes get landed.

What Just Happened

In this session you:

Described a task in natural language
Let Kavi route it to the appropriate agent
Approved each tool call through the gateway
Watched the agent execute in real time
Reviewed the output with accept/reject/revise controls
Landed the validated changes

This is the core Kavi loop. Every session follows this pattern, whether you are fixing a bug, adding a feature, or refactoring a module.