Getting Started
~944 tokens

Quick Start

Install Maki, connect a provider, run a first session. A few minutes, start to finish.

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

Installs to ~/.local/bin. Override with MAKI_INSTALL_DIR.

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.

Connect a provider

maki auth login              # interactive picker (OAuth or API key)
export ANTHROPIC_API_KEY=... # or just export a key

Anthropic, OpenAI, Google, Ollama, and friends all work; multiple keys in one var rotate on rate limits. Every env var and model catalog is in Providers.

First session

From a repo:

maki

Type what you want done, press Enter, watch it work. Worth knowing on day one:

  • Permissions. File edits inside the repo run freely. bash and web tools ask first: y allows once, s for the session, a for the project. Deny rules always win; /yolo skips the prompts. Details in Permissions.
  • Plan mode. Tab toggles it. The agent may only write the plan file until you approve, then back to build mode.
  • Models. /model switches mid-session.
  • Sessions. /new starts a second session while the first keeps working in the background; /sessions jumps between them. Tomorrow, maki --continue resumes where you left off.
  • Your shell. Prefix input with ! to run a command yourself (!cargo test). !! hides command and output from the agent.
  • Escape hatch. Esc Esc cancels a streaming response. When idle, it rewinds instead.
  • Help. Ctrl+H lists every keybinding, or see Keybindings.

Default model (optional)

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

Without it, Maki remembers the last model you used.

Teach it your project

Maki loads AGENTS.md (or CLAUDE.md, .cursorrules, and friends) from your repo automatically. Per-project settings live under .maki/:

.maki/
├── init.lua           # overrides global config
├── permissions.toml   # permission rules
├── mcp.toml           # MCP server config
├── commands/          # custom slash commands (.md files)
└── skills/            # project skills (each dir has a SKILL.md)
AGENTS.md              # always in context
AGENTS.local.md        # personal per-project instructions (gitignored)

A project .maki directory can run code, so Maki asks once per folder before loading it. AGENTS.md, commands and skills load either way. See Folder Trust.

Which instruction file wins, when subdirectory rules load, and how skills and memory fit together: Context. All settings: Configuration.