Your first Kaitoi Code session.

For setup and updates, see Install and update. Check kaitoi --version and use kaitoi code --help to confirm available commands. Older builds may interpret unsupported code acp or code serve commands as model prompts.

Kaitoi Code is the terminal agent in Kaitoi CLI. It can inspect a project, edit files, run checks, use Kaitoi workflows, and delegate work to subagents or Crew. Start with one small change so you can follow the proposal, the permissions, and the result.

Code and Crew are available on every Kaitoi plan, including Pay-as-you-go. Hosted model turns and paid tools use your credits. Direct local-model turns need no Kaitoi account and incur no Kaitoi inference charge. Creating your own developer REST API keys is a separate capability, available on every plan.

See Install and update for installation and update instructions.

#Open the right project

In your terminal, move into the project folder. Replace the example path with your own:

cd /path/to/your-project

In a Git project, use git status --short to note any existing changes before you start. Then launch Code:

kaitoi --workspace . --mode plan

The dot means “this folder.” The explicit workspace makes the target clear; --mode plan starts with read-only tools for the model. Running kaitoi on its own normally offers the current folder and starts in Build mode. kaitoi code works the same. Open the dashboard with kaitoi ui or kaitoi dashboard. Direct kaitoi runtime, kaitoi connect and other commands remain available alongside Penny's approved tools.

When a hosted-model session needs sign-in, Code offers to open your browser. When a ready local model is detected, that prompt also offers an option naming that model and its server, which you can use without an account. Local-model conversations do not require a Kaitoi account; Kaitoi-hosted models and account tools do. See Sign-in and configuration for setup.

At Accessing workspace, check the full path and choose Yes, I trust this folder to enable local file tools there. This establishes the workspace; individual actions still follow the mode and permission settings.

If you choose No local file access, Code can continue without those tools. When you launch without an explicit --workspace, declining the current folder can instead reuse a different, previously trusted folder. Always check the active workspace before requesting changes.

#Check the session before your first request

At Code's You > prompt, enter:

/status

Check Workspace, Workspace trusted, Mode, Provider, and Model. For this walkthrough, the workspace should be your project and the mode should be Plan. Local commands shows whether the agent's local command tools are enabled; Auto-approve and the permission settings can also affect when you are asked.

To inspect available models, use /providers. To choose one, use /provider <provider-id> and /model <model-id> with values from that list. These choices can be saved when a user config file already exists; Code tells you whether they were saved. They are not always temporary session choices.

Slash commands belong inside Code. The kaitoi code ... commands in this guide belong in your normal terminal.

#Inspect first, then agree on one change

Send a specific, bounded request. For a project with a README:

Read the README and the files that define how this project starts and runs tests. Find one small error or unclear step in the setup instructions. Explain the evidence and propose a README-only correction. Do not edit anything yet. If the instructions are already correct, say so.

Code can read and explain in Plan mode, but its model tools cannot apply file edits or run local commands there. Plan mode still uses the selected model; hosted conversation usage can consume credits. Use /cost to inspect session usage.

Look for a concrete finding and the file that supports it. If the request is too broad, narrow it before switching modes.

In this fictional JavaScript project, package.json defines a dev script as vite. The README says npm dev. The proposed edit replaces that one command with npm run dev, which invokes the named script. This is a proposal, not evidence that a file has already changed. After approving an edit in a Git project, compare git status --short with the starting state and inspect git diff -- README.md. Separately run the project's appropriate check and inspect its output. A correct diff does not prove that the application starts. The diagram shows example file content, not the Kaitoi Code interface, and executes no commands.

If your project has no such error, choose another small, well-defined change. The goal is a correction supported by your files, not reproducing the example above.

#Make the edit in Build mode

After reviewing the proposal, switch modes:

/mode build

Then ask for the agreed change:

Apply only the README correction we agreed on. Leave other files unchanged. Summarize the exact change, then tell me how to check it.

When an edit needs approval, Permission needed shows the file change and its diff. Read the changed lines. If the preview is shortened, choose View the whole diff. Allow once authorizes that operation; Deny refuses it. Some cards offer broader choices, such as allowing edits for the rest of this session.

Code does not necessarily ask again for every edit or command. Existing session approvals, saved project rules, and automatic approval settings can cover an action. Use /permissions to inspect the approvals rather than assuming a new prompt will appear.

#Check what changed and what ran

Review the actual file after the edit. In a Git project, inspect the diff in your editor or normal terminal:

git status --short
git diff -- README.md

Compare the changed-file list with the starting state and confirm that the README diff contains only the intended correction. Then use a check that fits the change: for a corrected startup command, for example, check that the command works in the prepared project environment. Reading a patch, editing a file, and successfully running a check are separate results.

If you want Code to run the check, ask it to state the command first. When its local command tools are off, enable them with:

/commands on

This enables the tools; it does not approve every command. Review the command and working directory when prompted. Saved rules may already cover it. Command settings can persist when a user config exists. See Commands and background processes for sandbox requirements and longer-running work.

Ask Code to finish with:

List the files changed, the checks actually run, their results, and anything still unverified.

A refused permission, unavailable command environment, or failed check means that part remains unfinished. Keep it visible in the summary.

#Stop, finish, or come back later

Press Esc while Code is responding to stop the current turn. At a permission card, Esc declines that request. Stopping does not undo file changes that already completed.

Enter /exit to leave the session. Code saves session history locally; its ordinary background processes end with the session. A durable Crew run has its own lifecycle.

To return, start Code in the same project, check /status, then use:

/sessions
/resume

/sessions lists saved sessions for the current workspace. /resume opens the picker; you can also use /resume <number-or-id>. History does not by itself restore an earlier version of your project files. See Sessions and history and Checkpoints and recovery.

#Keep these commands handy

Command	Use it to
/help	See the full command list.
/status	Check the active workspace, model, mode, and session settings.
/workspace	Show the workspace; add a path to choose another folder.
/mode plan · /mode build	Switch between the model's planning and editing tools.
/permissions	Inspect session approvals and saved project command rules.
/cost	Inspect credits and token usage for the session.
/doctor	Inspect diagnostics when setup or tools are not working.

For larger work, /crew <task> switches to Crew mode and sends the task. The run starts through a proposal and approval flow. Continue with Subagents or Crew once you are comfortable with a direct Code session.