Quick Start

Install Maki, connect a provider, and run your first session. Takes a few minutes.

Install

Linux / macOS

# Download and read the script first (don't blindly trust shell scripts).
curl -fsSL https://maki.sh/install.sh -o install.sh
cat install.sh

# Then run.
chmod +x install.sh && sh install.sh

One-liner:

curl -fsSL https://maki.sh/install.sh | sh

Windows (PowerShell)

# Download and read the script first (don't blindly trust remote scripts).
irm https://maki.sh/install.ps1 -OutFile install.ps1
Get-Content install.ps1

# Then run.
.\install.ps1

One-liner:

irm https://maki.sh/install.ps1 | iex

Windows (Git Bash)

curl -fsSL https://maki.sh/install.sh | sh

Both install to %LOCALAPPDATA%\maki and add it to your user PATH. Override with MAKI_INSTALL_DIR / $env:MAKI_INSTALL_DIR.

Living on the edge (main branch)

cargo install --locked --git https://github.com/tontinton/maki.git maki

With Nix

nix run github:tontinton/maki

Or download a pre-built binary from GitHub Releases.

API Keys

Export a key for at least one provider (e.g. ANTHROPIC_API_KEY). Some providers support OAuth login instead via maki auth login <provider>.

See Providers for the full list of supported providers, environment variables, and setup instructions.

Run

From your project directory:

maki

Type a prompt, press Enter, and the agent starts working.

Keybindings

These are the defaults. Plugins and init.lua can rebind most of them with maki.keymap.set; see Keybindings for precedence and caveats.

  • Newline in input: \+Enter, Ctrl+J, or Alt+Enter
  • Scroll output: Ctrl+U / Ctrl+D (half page)
  • Cancel streaming: Esc Esc
  • Rewind (when idle): Esc Esc
  • Quit: Ctrl+C
  • All keybindings: Ctrl+H

Choosing a Model

Set a default in your config:

-- ~/.config/maki/init.lua
maki.setup({
    provider = {
        default_model = "anthropic/claude-sonnet-4-20250514",
    },
})

Switch models mid-session with the /model command.

Project Configuration

Add a .maki/ directory to your project root for per-project settings:

.maki/
├── init.lua           # Overrides global config
├── permissions.toml   # Permission rules
├── mcp.toml           # MCP server config
└── commands/          # Custom slash commands (.md files)
AGENTS.md              # Loaded into agent context automatically
AGENTS.local.md        # Personal per-project instructions (gitignored)

Maki also recognizes CLAUDE.md, COPILOT.md, .cursorrules, CONVENTIONS.md, GEMINI.md, and others as instruction files (first match wins).

AGENTS.md is loaded at the start of every session. Put coding conventions, repo quirks & gotchas, or off-limits directories in here. Maki will automatically load instruction files inside subdirs when doing a read in the subdir.

See Configuration for all options.