---
url: /guide/first-conversation.md
---
# Your first conversation

Open a project directory and launch Kuru. Starting with the offline provider makes it easy to explore the interface before signing in:

```sh
cd /path/to/project
kuru --provider demo
```

The demo provider needs no credentials or network access. Kuru includes its verified Dolt engine and licenses; first memory use extracts them locally, and later launches reuse the cache. See [local storage](../concepts/memory#local-storage) for details.

Or select the project without changing directories:

```sh
kuru -C /path/to/project --provider demo
```

## Meet the pool

The welcome portrait shows the selected framework. Type a prompt and press Enter. Kuru runs a bounded turn through its peers and returns a response under the selected speaking identity.

Try `/parts` to inspect the active peers and relationships. The starting IFS pool includes Self, two managers, two firefighters, and two exiles. Each role offers a different tendency; Self has no supervisory authority over the others.

The wide layout shows peer activity and relationship membership alongside the
conversation. A narrow pane keeps the conversation and editor central. Each
completed reply shows the returned speaker or relationship and its input/output
token counts beneath the reply. Tool-call and peer-round limits are named
separately. An empty model response is labeled as a response outcome, while an
older limited result whose cause was not stored is labeled as an unspecified
legacy limit. Activity reports describe routing and phases without exposing
private peer messages; they do not determine the final reply.

## Make it yours

For a one-shot script, use `kuru run "PROMPT" --json`, or pipe UTF-8 text into
`kuru run`. An argument plus a nonempty pipe sends the argument followed by
separately labeled literal data. Input is limited to 128 KiB before project
authority starts. `--output-format stream-json` gives bounded public status,
replaceable facing-text snapshots and a terminal outcome; it is not a lossless
token stream. Errors, hooks and compaction notices stay on stderr. See
[headless input and output](../reference/commands#headless-input-and-output) for
precedence, gaps, exit codes and exact retry after interrupted output.

The controls beside the composer show your current choices:

| Key           | Choice           |
| ------------- | ---------------- |
| F2 | Model            |
| F3 | Reasoning effort |
| F4 | Framework        |

Below them, a standing row keeps the last prepared request's context estimate and this session's cost estimate next to the permission counts, so one screen carries all six. An unknown price reads as `cost unknown`, never as a zero charge or a quota, and the figures are the ones `/cost` and `/permissions` report. Very narrow terminals abbreviate that row rather than drop a control.

Type in a picker to filter, use the arrow keys to move, and press Enter to select. Escape closes it. Your unsent draft stays in place. Choices persist for this project, including after quitting and relaunching.

Use Alt+Enter for a newline. Page Up, Page Down and the mouse wheel read the public transcript, fetching older pages as needed. Ctrl+F finds literal, case-sensitive text beyond the viewport; Enter visits the next match and Escape restores your previous reading position without changing the draft. During work, Escape or Ctrl+C cancels the operation. While idle, Ctrl+C quits.

The composer moves by grapheme, so combining marks and joined emoji stay
together. At the top or bottom line, Up and Down browse
submitted prompts from this session. Ctrl+R searches those
prompts; Escape restores the unsent draft. This bounded history is
temporary in-memory state, separate from the saved conversation.

On Unix terminals that send bracketed-paste events, large or multiline pastes appear as compact chips while the provider still
receives the exact pasted text. Put the cursor on a chip and press
Ctrl+G to expand or compact it, or Ctrl+X
to remove only that pasted span. Drafts are limited to 128 KiB; a paste that
would exceed the limit is rejected as a whole.

Windows currently receives pasted input as individual console keystrokes. It
does not identify an atomic paste block, so paste chips and whole-block rejection
are unavailable there; review multiline input before sending it.

Cancellation waits for the active operation to settle and keeps your submitted
prompt in the transcript. If an answer completed first, Kuru shows it. Otherwise
Kuru stores a fixed interruption marker that remains visible after later work and
resume. `/retry` reuses only the last submission's exact durable ID, prompt and
target. It can return an already completed result or finish work interrupted
before possible dispatch without duplicating the displayed prompt. It refuses
when an external call may already have been received. Entering another prompt is
new work; Kuru does not retry automatically.

Settings cannot change during active work. Cancel or wait for the turn to finish before choosing another model or framework.

## Work with files

File reading and listing are available inside the project. Writes and shell commands each need explicit permission:

```sh
kuru --allow-write
kuru --allow-write --allow-shell
```

Shell commands use your account's process permissions, including access beyond the project. [Tools and permissions](/reference/tools) explains these boundaries and configured MCP tools.

Tool calls appear as collapsed cards beneath their submitted prompt. Press
F6 to select a card and F7 to expand or collapse it; your
unsent draft stays in place. Shell previews are partial until the call settles.
File changes can show the checked recorded diff, even if the workspace has
changed since the write. Private peer and cognitive arguments and results stay
withheld. Card details are temporary; resumed history does not reconstruct
missing output. See [tool cards](/reference/tools#tool-cards).

Kuru reads applicable ancestor and project-root `AGENTS.md` and `CLAUDE.md` files, with nearer instructions taking precedence. Checked `@relative/file.md` imports can add bounded Markdown sources. When an actor first reaches nested project instructions through an authorized file path, Kuru asks for separate workspace trust before using them. A newly instructed write pauses for replanning before changing the file. See [configuration and workspace trust](/reference/configuration).

## Return to the work

`/quit` ends the session. A fresh launch starts a new conversation while preserving project choices and the peers' durable memories. To continue a specific transcript:

```sh
kuru sessions
kuru --resume SESSION_ID
```

See [sessions and dreaming](/concepts/sessions) for memory consolidation, membership changes, and their controls.

## Reduce motion

Framework portraits use fixed ASCII contours with a slow color cycle. The composer stays still while you type. To make ornament static:

```sh
KURU_REDUCED_MOTION=1 kuru
```

Operation timers and meaningful activity continue updating. No special icon font is needed.

For the complete command list, use `/help` or open [commands and shortcuts](/reference/commands).