Plugins

Everything you see in Greed comes from these plugins, each a folder of Luau you can read, change or replace. Unload one with greed.plugin.unload(name) in your config.

acp

Agents in Greed over the Agent Client Protocol: Claude Code, Gemini, Codex or any agent that speaks ACP, each in a transcript buffer you write to and read from, working in the project or in a workspace of its own.

  space i n   start an agent: pick which, and where it works
  space i l   the sessions, running and kept: show, take up, review or bring them in
  space i m   move this session's transcript to a pane, tab, float or panel

In a transcript, alt-enter sends what’s in the box at the bottom and ctrl-c stops the agent’s turn. A question the agent asks shows as a row of choices in the box, answered with enter or a choice’s letter in any mode (question.luau).

Agents are registered by name with the commands that run them; the first one installed is used. Add your own in init.luau:

    require("@acp").register({ name = "mine", commands = { { "my-agent", "--acp" } } })

Uses: core, picker, statusline, vcs, agent, models, panes, markdown.

agent

Lets agents and scripts use the editor: greed ctl from a shell, and MCP clients like Claude Code through greed mcp.

Requests come in on the session socket. registry.luau answers MCP’s methods (initialize, tools/list, tools/call), so the tools are the same for an agent and for greed ctl TOOL. Add your own with require("@agent").tool { ... }; tools.luau has the built-in ones, and proposals.luau the review of edits agents propose.

Uses: core, picker, terminal, operations, approvals, describe, markdown, models.

approvals

Approving plugins. A plugin that isn’t one of Greed’s own and declares capabilities (running programs, files by path, the network, …) waits until you approve them, and again if it later asks for more.

  :plugins-approve   review the waiting plugins and approve one
  :plugins           every plugin, where it comes from and what it may use
  :plugin-reload NAME load a plugin again from its folder

Uses: core, picker.

assist

Commands that ask a language model, in the roles :models shows, with what you pinned to the context (space i p, see the context plugin):

  space i e   explain the selection, in a panel as the answer arrives
  space i a   ask something about the selection
  space i f   fix the problem under the cursor, as changes to review
  space i c   draft a description of the changes in progress

Fixes come as proposed changes (] o, space o a, space o r), which undo as one operation. In the description buffer, a applies it (jj describe, or a git commit of what’s staged).

Uses: core, models, agent, vcs, context.

blocks

Runnable blocks in Markdown: a fenced block whose language has a runner (```sh, ```python, ```luau, ```http) runs when you ask, and its output is saved in a result block right under it, so the file shows it anywhere and a diff shows what changed. Running it again replaces the result.

  space m r   run the block under the cursor (enter on its fence too)
  space m R   run every block in the file, in order
  space m c   clear the block's result; :blocks-results-clear for all
  space m s   stop the block running under the cursor

Nothing runs when a file opens. The first time you run a block in a file Greed asks whether to: y for now, a to always trust that file. Files you trust, and those whose front matter says greed: run, show a run button on each block. Agents run blocks only in files you trust, and only as they were when you last ran them or trusted the file, so a block an agent rewrote waits for you to run it first.

Options go in the info string: id=NAME names a block’s result, and input=NAME gives another block that result (on stdin, or as input in Luau), running the named block first if it has no result yet, or every time with rerun=true. dir=PATH runs a program elsewhere than the file’s folder, and timeout=SECONDS stops it after that long. Add a language from Luau:

    require("@blocks").runner("lua", require("@blocks").program({ "lua", "-e" }))

Uses: core, agent, markdown.

cli

Greed’s command line commands that are only Luau: greed ls, greed new, greed bring and greed reference. Plugins add their own the same way:

    greed.cli({
        name = "hello",
        doc = "Say hello",
        usage = "[NAME]",
        run = function(args)
            return `hello {args[1] or "there"}`
        end,
    })

greed hello world then prints “hello world”.

cmdline

The command line: press “:” (alt-x in the vscode style) and type a command, like in Vim or Helix.

Every command can be run by name (:save, :pick-file), and the short names Vim and Helix users know are aliases (:w, :q, :wq, :e). Words after the command are its arguments (:open src/main.rs), and a trailing “!” forces it (:q! quits with unsaved changes). :lua runs Luau and := shows the value of an expression. A line range in front (:%s/a/b/g, :5,10d) selects those lines first; ex.luau has Vim’s line commands, and :g/regex/command is here.

Matches show above the prompt as you type. Tab and shift-tab go through them, up and down go through earlier command lines starting with what’s typed, enter runs and esc closes.

Other plugins add aliases and argument completion through require("@cmdline"):

    local cmdline = require("@cmdline")
    cmdline.alias("gs", "git-status")
    cmdline.completer("branch", function(word)
        return { { text = "main" }, { text = "dev" } }
    end)

A command then uses args = { { name = "branch", complete = "branch" } }.

Uses: core.

context

The context: what you’ve pinned for models and agents to see, as live references read fresh each time they’re sent.

  space i p   pin the selection, or the file when nothing is selected
  space i i   show the pinned items, one a line with its size; delete a
              line (x d) to drop the item

:context-add-problems pins this file’s problems, :context-add-diff the changes in progress, :context-clear drops everything. Assist commands send the context with each question, and agents read it with the context_get tool. It’s kept per project.

A plugin adds items that are worked out when sent:

    require("@context").define("todos", function()
        return "the TODO lines of the project ..."
    end)
    require("@context").add({ kind = "computed", name = "todos" })

Uses: core, agent, vcs.

core

Greed’s editing engine: the commands, motions, text objects, registers, floats, prompts and the editing styles registry, written against the same API any plugin uses. The editing styles themselves, like Helix and Vim, are plugins that give these commands keys.

describe

Help: describe anything the editor is made of, to see what it does, who defined it and where. In the help window, enter jumps to the definition and esc (or q) closes it.

  space h h   describe anything: commands, options, events, the API,
              plugins and modes, in one picker
  space h c   a command          space h o   an option
  space h e   an event           space h a   a function of the API
  space h p   a plugin           space h m   a mode and its keys
  space h k   press a key to see what it runs

Agents get the same through the describe tool, from text.

Uses: core, picker.

flash

Flashes text as it’s copied, so you can see what went to the clipboard.

With a “#rrggbb” background for “ui.flash” in the theme it fades out; with the 16 terminal colors it shows briefly and goes. Either way it’s a decoration and a theme entry changing over time, which is all an animation is.

To change how long it lasts, set “flash-duration” from your config:

    require("@greed").option.set("flash-duration", 150)

Uses: core.

format

Formatting: :format, and on every save unless format-on-save is off. A language’s formatter program (see the languages plugin) is used when it’s installed; otherwise the language server is asked. Only what changed is replaced, so the cursor and selections stay where they were.

To stop formatting on save:

    require("@greed").option.set("format-on-save", false)

Uses: core, languages.

grep

Search the whole project, and replace by editing what was found.

  space /             search the project for a regex as you type
  ctrl-e              in that picker: put the matches in a results panel
  :grep PATTERN DIR?  put the matches in a results panel straight away

The results panel is a multibuffer: each matching line under its file’s name. Edit the lines with anything (s to select the matches and c to change them all works well) and the files change as you type; :w saves them, enter opens the match under the cursor, and q closes the panel.

Patterns are regexes; ones in lowercase ignore case. The project is the folder holding .jj or .git (see core’s project.luau).

Uses: picker, multibuffer.

helix

Helix’s editing style, the default: select text, then say what to do with it. Its modes are helix (normal), helix-insert and helix-select; the status line shows them as NORMAL, INSERT and SELECT. The commands are core’s; this plugin gives them Helix’s keys. Copy any part of it into your own config to change it.

Uses: core.

hints

Key hints: after a key that starts longer sequences, like “space”, show what can come next and what each key does. f1 shows the keys of the mode you’re in, and the first time you’re in a mode listed in intro (like typing into a terminal), a line in the status line says how to get out.

Uses: core.

hosts

Connecting to another machine from inside Greed: space C (:connect) lists the hosts you connected to lately and those in ~/.ssh/config, and going to one shows its session here, as greed ssh HOST would, starting one there if none is running. Typing a host that isn’t listed connects to it too.

Uses: core, picker.

image

Image files open as the image: PNG, JPEG and GIF, drawn as wide as the view at most (in the window, and in terminals that show images), under a line with its name, size and zoom.

  +  -  bigger, smaller
  =     as wide as the view, or its own size when it's smaller
  0     its own size

Uses: core.

languages

Languages, batteries included: which files are in which language, their language servers and how they’re commented and indented. The table is in languages.luau. A server only starts if it’s installed, so nothing needs setting up; :health shows what’s found and what’s missing.

Change an entry from your config. Fields you give replace those fields:

    local languages = require("@languages")
    languages.set("python", { servers = { { "pylsp" } } })
    languages.set("odin", { extensions = { "odin" }, servers = { { "ols" } } })

Uses: core.

lsp

Language servers: hover, definitions, references, rename, code actions and diagnostics. Lines with problems get a sign, and the worst problem’s message shows after the line (turn that off with :set diagnostic-messages false).

  space k   show what's under the cursor, with any problems there
  g d       go to the definition
  g r       pick a place it's used
  space r   rename it everywhere
  space a   pick a fix or refactor
  space d   pick a problem in this file
  space D   pick a problem in any file
  ] d / [ d next / previous problem

Servers start the first time a file of their language is open, if one is installed; the languages plugin says which (see :health).

Uses: core, picker, multibuffer, statusline.

markdown

Markdown as a document: headings without their hashes (the top level twice the size), bold, italic, struck and code without their markers, links as their text, fenced code on a background of its own, quotes with a bar, --- as a line, list dashes as bullets and tables in columns with borders (tables.luau). The file stays plain Markdown: typing on a line shows it as written (see core.reveal). Turn it off with :set markdown-look false, or for one file with markdown-look-toggle. tab folds the section, list item or code block around the cursor (folds.luau).

The reading view (markdown-read) shows the file read-only with no markup at all, images in place and links to follow (links.luau), in the “read” mode; esc goes back to editing at the same place.

Other plugins can draw some parts their own way: notes draws headings and bullets as symbols, and claims them with require("@markdown").claim.

Uses: core.

models

Language models by role. Plugins ask for a role, like “fast” or “reasoning”, and your config says which provider and model plays it, so no plugin hard-codes a provider and switching to a local model is one line.

  :models   each role's provider and model and whether its key is found;
            enter changes a role, k sets a key, l signs in

What you pick in :models (or the setup page) is kept in Greed’s data folder and read before your config, which has the last word.

In your config:

    local models = require("@models")
    models.roles.fast = { provider = "ollama", model = "llama3.2" }
    models.providers.work = { kind = "openai", url = "https://llm.example.com/v1", secret = "work" }

Keys come from greed.secrets (:models, :secret-set anthropic, or ANTHROPIC_API_KEY).

Uses: core, picker.

multibuffer

Multibuffers: one buffer made of excerpts from many files, edited in place. Typing in an excerpt edits its file as you go (the file opens in Greed the first time one of its excerpts changes), and a change made to the file anywhere else shows in the excerpt. :w saves every file changed this way, enter goes to the line under the cursor and q closes the view.

Search results open in one. A plugin makes its own with

    require("@multibuffer").open({ { path = "/src/main.rs", from = 9, to = 12 } },
        { summary = "1 place" })

Each file’s name shows above its excerpts and its line numbers beside them; neither is text you can edit. Excerpts that overlap or touch are joined.

Uses: core.

notes

Notes: a folder of plain Markdown files, linked with [[note]], with todos and an agenda. It’s only files, so git or Syncthing can carry them to other machines and a phone.

  space n d   today's note            space n f   find a note
  space n c   capture a todo          space n /   search the notes
  space n a   the agenda: open todos, soonest due first
  space n x   tick a todo, or untick it
  space n t   jot a thought down in the inbox
  space n r   dismiss the reminders notice
  space n l   have Greed's agent link the inbox to your other notes
  space k     on a due date or a reminder, say when it is in words
  g d         follow the [[link]] under the cursor (making the note)
  tab, z a    fold the section, list item or code block under the cursor,
              or unfold it (Markdown's folds)

In notes (Markdown files in the notes folder, or every Markdown file with notes-everywhere), links show without their brackets, markup shows as symbols (look.luau), and each note lists the notes linking to it at its end. Todos and lines can carry reminders (reminders.luau).

    local greed = require("@greed")
    greed.option.set("notes-folder", "~/Documents/notes")

Uses: core, picker, agent, markdown, statusline, acp.

operations

Operations: work across files taken as one thing. An operation groups the edits it makes in every buffer and the programs it runs, so you can review it in one view and undo it in one step.

  space u o   recent operations, to review one
  space u u   undo the latest operation (in a review, that one)

In a review, space g r puts back the change under the cursor.

A plugin or agent makes one with

    local operations = require("@operations")
    operations.run("rename parse to parse_line", function(op)
        -- edit buffers, then
        operations.exec(op, { "cargo", "test" })
    end)

Uses: core, picker, multibuffer.

panes

Panes and tabs, the way a terminal multiplexer has them: split the screen between files and terminals, move between them, give a pane more room, keep tabs of layouts (arranged by the layout managers in layouts.luau). The keys follow zellij’s where they can:

• alt keys work everywhere, in every editing style and in terminals:

  alt-h/j/k/l move between panes (and to the next tab at the edge),
  alt-n opens a terminal pane (a floating one while floats are shown),
  alt-f shows or hides the tab's floating views (opening a floating
  terminal when there are none), alt-F floats this file, alt-= and
  alt-- resize, alt-< and alt-> (alt-[ and alt-] too) or alt-1..9
  change tabs. alt-w changes how the tab lays out its floats (see
  floats.luau), alt-{ and alt-} cycle through them and alt-W picks one
  from the dock.

• alt-p and alt-t open the pane and tab modes, where single keys act until

  esc.

• In normal mode, ctrl-w (and the leader’s w) is the window prefix Vim and Helix

  users know, and in Vim, g t and g T change tabs.

Every key is in M.keys; rebind or unbind them from your config like any other (see docs/keys.md).

Uses: core, picker, terminal, statusline.

pdf

PDF files open as their pages: one page at a time, drawn as wide as the view (in terminals that show images, and in the window), or as the text on every page, which reads anywhere and searches with /.

  ]  [     next and previous page
  +  -  =  bigger, smaller, as wide as the view
  t        pages or text

Uses: core.

picker

Pickers: type to narrow a list down, then choose an item.

A picker is one floating buffer. Its first line is what you type; the lines below are the items that match, best first, with the current one highlighted. Move with up/down (or ctrl-n/ctrl-p), choose with enter, close with esc.

Other plugins open one with require("@self/picker").pick(...); see pickers.luau for examples.

Uses: core.

pipe

Pipe each selection through something and put back what comes out:

  |               ask what to pipe through
  :pipe TARGET    the same, from the command line

The target says what it is:

  sort -u                        a shell command, given the selection as input
  luau: snake_case               a Luau function (see pipe.define)
  model: use the new client API  a language model, in the pipe-model role

Every selection gets its own result, and they all go in as one change, so one undo takes them back. A model’s changes are an operation too, to review with space u o; each result lands in its place even if you edit while the model works.

Uses: core, models, operations.

plan

A plan and decisions you share with agents, as notes in the project’s notes folder (.greed/notes, see the notes plugin), so they’re searched, linked and in the agenda like any note.

The plan (project:plan) is an agent’s checklist where you can see and change it: tick, reorder, add or delete items, and the agent reads what you did. An agent replaces the whole plan when it writes, giving the version it read, so it can’t write over changes you made since.

Decisions (project:decisions/*) are what you settled, kept across sessions: “use sqlite”, “never touch the generated code”. Ones an agent adds stay proposed until you accept them, and agents are told so, so an agent can’t make itself rules the next one follows.

Uses: core, agent, picker, notes.

projects

Projects: space P lists, in one picker, the projects open here, the sessions running on this machine, recent projects, and the projects your sources find. enter goes to one: it switches to it if it’s open or has a session, and opens it in a session of its own if not. alt-enter opens it in a new session even when one is running for it. A typed folder opens too.

Sources are folders to look in and commands that print paths:

    require("@projects").sources({
        -- every folder one level under these
        { dirs = { "~/Development", "~/Work" } },
        -- deeper, but only folders that look like projects
        { dirs = { "~/src" }, depth = 3, markers = { ".jj", ".git" } },
        -- any command that prints one path per line
        { command = { "zoxide", "query", "-l" } },
    })

Sources are looked at in the background, when the editor starts and each time the picker opens, and what they found last is kept, so the picker opens at once.

Uses: core, picker.

prose

Text objects for prose: select or move by sentence, paragraph and Markdown section.

  m i p / m a p   select the paragraph (a: with the blank lines after it)
  m i s / m a s   select the sentence (a: with the spaces after it)
  m i h / m a h   select the section under a heading (a: with the heading)
  ] p / [ p       next / previous paragraph
  ] s / [ s       next / previous sentence

Uses: core, markdown.

restore

Session restore: a session remembers its projects, the files open in each and where the cursor was, and opens them again when it starts. Written down when it quits and when a file is saved, per session name in the cache, so it only works for editors running as a session (which greed is, unless GREED_NO_SESSION is set).

Uses: core.

setup

Setting Greed up: the first time you start it without a config, a page asks how you like to edit, which theme, whether your font has icons, whether you use Claude Code and which language model to use. The page is setup.md, a questionnaire in Markdown (see the markdown and blocks plugins): a style or theme picked switches at once, and Save writes a config from the answers and opens it, and has the model’s roles use the provider picked. :setup brings the page back any time.

tab and shift-tab go from choice to choice and button to button, enter (or space) or a click picks one or presses it, and esc or q closes it as “Not now”.

Uses: core, theme, models, markdown, blocks.

shell

A shell in a buffer: type a command at the prompt at the bottom, enter runs it, and it becomes a block above: the command, what it printed, and how it ended. Blocks stay to read, search, fold, copy and run again.

  space o s   switch to a shell, or open one (:shell opens a new one)
  enter       run what's at the prompt; on a block, edit its command
  [ p  ] p    the block before or after the cursor
  g o         select the block's output
  ] e  [ e    the next or previous file:line the output names; enter opens it
  ctrl-c      interrupt the running block (vscode style: copy a selection)
  ctrl-t      type into the running block's program, in a terminal
  space r     run the block again, as it ran; space R here and now
  space y/Y   copy its output / its command
  space x     stop it; space v opens its whole output; space c clears

The shell runs cd, export, unset, env, history, clear, open and help itself; every other line goes to a real shell, yours (sh for an agent), whose cd and export carry over (fallback.luau). It runs in a pseudo terminal (pty.luau), handed to a terminal when a program wants one; an agent’s run through a pipe. Each shell has its own folder and variables, and a project can have several.

$3 | sort, buf:NAME | ..., @sel | ... and @file | ... send block 3’s output, a buffer, the selection or the file you’re in to a command, and ... > buf:NAME (>> adds) sends its output to a buffer (data.luau). Output that’s JSON is kept as a value on the block, and a table (kubectl get, docker ps, ps) as a table, which $3 | where ..., select and sort work on (tables.luau). / filters what a block shows, and space s sorts a table (rows.luau).

Agents run commands with shell_run and read blocks with shell_read (tools.luau).

Uses: core, picker, terminal.

statusline

The status line: on the left the mode, the tab, the file (or the latest message) and whether keys are being recorded; on the right the branch, problems, the language and its server, the editing style (dim), anything unusual about the file, how many selections there are, where the cursor is, the machine and the session. With the statusline-pills option some are pills, with rounded ends drawn in the theme’s colors, and with the effects option light goes through the tab or the file when you go to another, and the mode when it changes.

Add to it from your config, or take a piece away:

    local statusline = require("@statusline")
    statusline.add("right", "clock", function() return os.date("%H:%M") end)
    statusline.remove("host")

greed.statusline with a function of your own replaces it all; the last one set wins.

Uses: core.

terminal

Terminals: a shell, or any program, in a buffer. :terminal [command] opens one in the main view and sends it every key; ctrl-\ goes back to the editing style’s mode, where the output is text to select, search and copy, and i or enter types into the program again.

The buffer holds the lines that scrolled off the top, then the screen. Output replaces the screen part and adds what scrolled off above it.

Uses: core, picker.

theme

Themes: what every style name looks like. Greed comes with the default (the terminal’s 16 colors) and the usual ones from other editors: Nord, Dracula, Catppuccin, Gruvbox, Tokyo Night, One Dark and more.

  :theme NAME   switch to a theme
  :theme        pick one, trying each as you move; esc goes back

The theme picked is remembered (in the cache folder) until you pick another. To set it from your config, or define your own:

    local theme = require("@theme")
    theme.use("nord")
    theme.define("mine", {
        palette = { bg = "#101418", ... },  -- see palette.luau
        styles = { comment = { fg = "#5c6773" } },
    })
    theme.define("nord-bold", { inherits = "nord", styles = { keyword = { bold = true } } })

A theme is the base under greed.theme.set: entries set that way, from your config or a plugin, stay on top whichever theme is in use.

Uses: picker, cmdline.

tree

A file tree in a side panel. space e opens it (or moves to it, or closes it if you’re in it). In the tree: enter or l opens a file or folds a folder, h folds the folder you’re in, r reads the disk again, q closes; a makes a file (or a folder, ending in /), R renames, d deletes. Hidden and ignored files are left out, like in the file picker.

It’s only a plugin: to turn it off, greed.plugin.unload("tree") from your config.

Uses: core.

tutor

The tutor: :tutor opens tutor.md, a page to read and edit with the keys of your editing style. It asks which style first, switches to the one picked, and shows each lesson’s keys for it, with <!-- if style=... --> parts (see the markdown plugin’s questions).

A lesson’s exercise is a practice block followed by a want block, the text it should become. The tutor hides the want block and marks the practice block done once its text matches. The want block’s options give each style’s keys for it (vim="w d w"); the tests press them, so the keys the page teaches are known to work.

Uses: core, markdown, blocks.

undo-tree

The undo tree, like Emacs’s vundo: every state the text has been in, the branches an undo followed by an edit left behind included. space u t shows it; moving up and down takes the text to that state as you go, enter keeps it, and esc goes back to where you were.

  ○ 0  loaded
  ○ 1  3m
  │ ○ 2  2m        a branch left behind
  ● 3  now         where the text is

The newest branch of each state carries on below it; older ones are indented under it.

Uses: core.

vcs

Version control: signs beside lines added (+), changed (~) and removed (-) since the last commit, with jj, or git where there’s no .jj.

  ] g / [ g   next / previous change; ] G / [ G the last and first
  m i g       the change under the cursor; m a g its lines
  space g r   put the change under the cursor back the way it was
  space g b   who last changed this line, and when
  space g s   every change since the last commit, in one multibuffer
  space u c   commit just the latest operation's files, named after it
  space g a   stage the change under the cursor (git)
  space g S   what's staged (git), to unstage hunks and commit

With jj the comparison is with the working copy’s parent (@-), so the signs show what the change you’re working on does to the file. With git it’s with what’s staged, so staged changes lose their signs.

Uses: core, agent, multibuffer, operations, picker, statusline.

vim

Vim-style editing, written only against the plugin API. It has modes of its own (vim, vim-insert, vim-replace and the three visual modes), beside Helix’s, and says which plays each role: keys other plugins bind for the command role (the language server’s, the next change) and the leader (space) work here as in every style.

Switch to it with :style vim, or put this in ~/.config/greed/init.luau:

    require("@greed").option.set("editing-style", "vim")

It reads in this order: common.luau, text helpers; motions.luau, the motions (one table, each saying how an operator takes its range) and marks; objects.luau, ranges and text objects; operators.luau, operators applied through apply and the line and case tables; visual.luau, the visual modes (block mode keeps a selection per line), with the commands for motions and operators; then this file, with insert, replace, the change list and U; keys.luau last. Ex commands (:s, :g, ranges) are the command line plugin’s, and . is core’s.

Uses: core.

vscode

The vscode style: no modes, VS Code’s keys. Typing inserts text (replacing any selection), arrows move, shift and the arrows select, and the usual ctrl shortcuts do the usual things. The editing itself is core’s (core/modeless.luau), shared with any other style without modes; this plugin gives it VS Code’s keys.

Switch to it with :style vscode, or to use it all the time, put this in ~/.config/greed/init.luau:

    require("@greed").option.set("editing-style", "vscode")

Uses: core, picker.