## Install
Linux and macOS, x86_64 and aarch64:
curl -fsSL https://hjkl.ug/install.sh | sh
This checks the download against the release's sha256sums.txt and puts lug in
~/.local/bin. If you have no init.lua yet, it asks which model and prompt mode you
want, whether to use haul and basic.lug, and how basic.lug should look, then writes a
starter with those set. haul installs the plugins the first time Lug starts.
Pass the answers as options to skip the questions, or -y to take the defaults:
curl -fsSL https://hjkl.ug/install.sh |
sh -s -- --model anthropic/claude-opus-5 --mode normal --style plain --theme github-dark
| Option | Does |
|---|---|
--dir DIR |
Install somewhere other than ~/.local/bin (or set LUG_INSTALL_DIR) |
--version v0.0.1 |
Pin a release (or set LUG_VERSION) |
--model none |
No model yet: Lug starts, and asks for one when you send (for a provider behind a proxy, say) |
--model corp/MODEL --base-url URL --wire openai-chat |
A provider of your own, such as a proxy: written to lug.opt.providers |
--manager none |
No plugin manager, and so no plugins |
--base none |
haul, but not basic.lug |
--no-config |
Leave init.lua alone |
--source |
Clone over SSH (or LUG_GIT_URL) and build with cargo |
--help |
List every option |
If no release is found, the installer offers to build from source. With no terminal to
ask on, it takes the defaults. You can also download a tarball from the
releases page and check it with
sha256sum -c --ignore-missing sha256sums.txt.
## Quick start
export ANTHROPIC_API_KEY=sk-... # or run :login anthropic KEY inside Lug
cd your-project
lug --model anthropic/claude-opus-5
Type a request, then press <C-y> to send it (or <Esc> then <CR>). When a tool
wants to change something, press a to allow it, A to always allow that tool, e to
edit its arguments, or d to skip it. If your project has an AGENTS.md or
CLAUDE.md, Lug reads it into the system prompt.
| Keys | Does |
|---|---|
<C-y> |
Send the prompt |
<C-c> |
Cancel the run |
<C-w>k / <C-w>j |
Move to the transcript and back to the prompt |
]t [t za |
Next and previous tool call; fold or unfold it |
v V y q |
In the transcript: select characters or rows, copy them, quote them into the prompt |
@ |
Reference a file, with completion |
gf |
Open the path under the cursor in $EDITOR |
<Space>am <Space>ss |
Pick a model; pick a session |
<S-Tab> |
Toggle auto mode: tool calls run without asking |
: |
:model, :sessions, :compact, :theme, :set, :q and more |
lug "fix the failing test" # start with a first message
lug --continue # reopen this directory's latest session
lug --auto # auto mode: tool calls run without asking
lug ls # list this directory's sessions
lug --init # write a commented starter init.lua
lug docs lua # annotations for lua-language-server; prints where
lug test # run a plugin's tests, in its folder
Every key and command is in docs/keys.md.