Skip to main content
This guide walks you through your first loaf session, from authentication to running commands.

​
Before you start

Make sure you’ve completed the Installation steps:
  • Node.js >=20 installed
  • Repository cloned and dependencies installed with npm install

​
Launch loaf

Start loaf in TUI mode: 
cd loaf
npm run dev
On first launch, you’ll see the onboarding flow.

​
Onboarding flow

loaf guides you through a two-step setup:
1

Connect an AI provider

loaf supports multiple AI providers. Choose one to authenticate:
Best for: ChatGPT models (GPT-4, o1, o3)
  1. Select OpenAI from the onboarding menu
  2. loaf opens a browser window for OAuth login
  3. Sign in with your OpenAI account
  4. Grant access when prompted
  5. Return to the terminal — authentication is complete
loaf uses OpenAI’s OAuth flow. Your credentials are stored securely in your system keychain.
2

Configure web search (optional)

loaf can perform web searches using the Exa API.Option 1: Add Exa API key
  1. Enter your Exa API key when prompted
  2. Press Enter to save
  3. The search_web tool is now available
Option 2: SkipType skip and press Enter. You can add the key later with /auth.
Get a free Exa API key at exa.ai. The free tier includes 1,000 searches/month.
After onboarding, loaf is ready to use.

​
Choose a model

Before your first prompt, select an AI model:
1

Open the model selector

Type /model and press Enter.You’ll see a list of available models based on your connected providers.
2

Select a model

Use arrow keys to navigate:
  • ↑/↓: Move through the list
  • Enter: Select a model
  • Type to search: Filter models by name
gpt-4.1        # GPT-4 Turbo (latest)
o1-preview     # OpenAI o1 reasoning model
o3-mini        # Fast reasoning model
3

Configure thinking level

For reasoning models (o1, o3), loaf prompts you to select a thinking level:
  • OFF: No extended reasoning (fastest)
  • MINIMAL: Very light reasoning
  • LOW: Fast with lighter reasoning
  • MEDIUM: Balanced depth and speed
  • HIGH: Maximum reasoning depth
  • XHIGH: Extra high reasoning (for hardest tasks)
Thinking level controls reasoning effort for extended-reasoning models. For standard models, it’s ignored.
Your model selection is saved. You can change it anytime with /model.

​
Your first commands

1

Send a message

Type a message at the prompt and press Enter:
> explain how loaf works
loaf sends your message to the selected model and streams the response.
2

Execute a tool

Ask loaf to perform an action:
> list files in the current directory
loaf calls the bash tool to run ls and shows you the output.
loaf has built-in tools for shell commands, file operations, JavaScript execution, and web search. See Tools for details.
3

Read and edit files

loaf can read and modify files:
> read package.json and show me the dependencies
Or make changes:
> update the version to 0.3.0 in package.json
loaf uses the read_file and apply_patch tools to inspect and edit files.
4

Run code

Execute JavaScript directly:
> calculate the fibonacci sequence up to 10 terms
loaf uses the run_js tool to execute code and return results.

​
Essential commands

loaf includes slash commands for common operations:
Displays a list of all available slash commands.
> /help
Opens the model selector to switch AI models or adjust thinking levels.
> /model
Add or update authentication for AI providers.
> /auth
Load a previous chat session:
/history        # Browse all sessions
/history last   # Load most recent session
/history <id>   # Load specific session by ID
Clears the current conversation history to start fresh.
> /clear
Shows all registered tools (built-in and custom).
> /tools
Displays available skills from:
  • Repository .agents/skills
  • User directory ~/.loaf/skills
  • Global directory ~/.agents/skills
> /skills
Use skills with $skill-name syntax in your messages.
Re-runs the onboarding flow to reconfigure providers.
> /onboarding
Exits the loaf TUI.
> /quit
Or press Ctrl+C (or Cmd+C on macOS).

​
Using skills

Skills are reusable instruction bundles. To use a skill, mention it with the $ prefix: 
> $code-review analyze this file for potential bugs
loaf loads the skill’s instructions and applies them to your request. See Skills for more details.

​
Interrupting and steering

​
Interrupt active inference

Press Ctrl+C (or Cmd+C on macOS) while loaf is generating a response to interrupt it.

​
Steer during inference

Type a message while loaf is working to queue a steering message. loaf processes it after the current inference completes.

​
Keyboard shortcuts

ShortcutAction
↑ / ↓Navigate command history
Ctrl+C / Cmd+CInterrupt inference or exit
TabAutocomplete slash commands
Ctrl+V / Cmd+VPaste clipboard content (including images)

​
Configuration files

loaf stores state in ~/.loaf (or %USERPROFILE%\.loaf on Windows):
  • auth.json: OAuth tokens and API keys
  • state.json: Model selection, thinking level, input history
  • chat-sessions/: Saved chat sessions

​
Reset configuration

To wipe all local config and restart onboarding: 
> /forgeteverything
This deletes all authentication, settings, and chat history. Use with caution.

​
Next steps

Now that you’re up and running, explore more:

Core concepts

Learn about skills, tools, and models

Commands

Master all slash commands

Custom tools

Extend loaf with your own JavaScript tools

RPC mode

Integrate loaf programmatically

Build docs developers (and LLMs) love

Get started for freeTalk to us