Skip to main content
loaf is a terminal-first AI coding assistant that runs locally on your machine. This guide covers system requirements, installation steps, and first-run setup.

​
System requirements

Before installing loaf, ensure your system meets these requirements:
Node.js version: loaf requires Node.js >=20. Check your version with node --version.
  • Node.js: Version 20 or higher
  • npm: Comes with Node.js
  • Git: For cloning the repository
  • Terminal: Any modern terminal emulator

​
Platform support

loaf runs on:
  • macOS (Intel and Apple Silicon)
  • Linux (most distributions)
  • Windows (with WSL or native)

​
Installation steps

1

Clone the repository

Clone loaf from GitHub:
git clone https://github.com/veyzyn/loaf.git
cd loaf
This downloads the source code to your machine.
2

Install dependencies

Install all required packages:
npm install
This installs dependencies including:
  • Ink: Terminal UI framework
  • OpenAI SDK: Model API client
  • node-pty: PTY support for shell tools
  • keytar: Secure credential storage
On Linux, you may need to install additional system packages for keytar. See the keytar documentation for details.
3

Verify installation

Check that loaf is ready to run:
npm run dev
You should see the loaf startup screen. If this is your first run, you’ll be prompted to set up authentication.Press Ctrl+C (or Cmd+C on macOS) to exit.

​
Configuration directory

loaf creates a data directory on first run to store configuration, credentials, and chat history:
  • macOS/Linux: ~/.loaf
  • Windows: %USERPROFILE%\.loaf
This directory contains:
  • auth.json — OAuth tokens and API keys
  • state.json — Saved settings and model selection
  • chat-sessions/ — Chat history records
  • tools/ — Custom tool scripts (see Custom Tools)
  • skills/ — Custom skill definitions (see Creating Skills)

​
Running loaf

loaf has two modes:

​
TUI mode (default)

Run the interactive terminal UI: 
npm run dev
This starts loaf in terminal user interface mode where you can chat with AI models, execute tools, and manage settings.

​
RPC mode

Run loaf as a JSON-RPC 2.0 server over stdio: 
npm run rpc
This mode is for programmatic integration. See RPC Protocol for details.

​
Development commands

The following npm scripts are available:
CommandDescription
npm run devStart loaf TUI
npm run rpcStart RPC server
npm run typecheckRun TypeScript type checking
npm run testRun test suite
npm run test:coverageRun tests with coverage report
npm run spinnersView spinner gallery (dev tool)

​
First run

On your first launch, loaf will:
  1. Create the ~/.loaf data directory
  2. Display the onboarding flow
  3. Prompt you to connect an AI provider (OpenAI, OpenRouter, or Antigravity)
  4. Optionally configure web search via Exa API
You can re-run onboarding at any time with the /onboarding command.

​
Next steps

Once installed, proceed to the Quickstart guide to authenticate and start using loaf.

Quickstart

Complete your first setup and run your first commands

Authentication

Learn about provider authentication options

Build docs developers (and LLMs) love

Get started for freeTalk to us