Voltar às skills
yarepl.nvim
por milanglacier
Codex—Ainda sem avaliações
Sua avaliação
Resumo
Versatile REPL/CLI manager. Multiple sending modes with parallel sessions, buffer attachments, and cross-language support. AI CLI integration for Aider and OpenAI Codex. Picker support, project-level configs, code cell text objects, and native dot-repeat.
Descrição
- [yarepl.nvim](#yareplnvim)
- [Showcase](#showcase)
- [Why yarepl.nvim?](#why-yareplnvim)
- [Installation](#installation)
- [Configuration](#configuration)
- [Setup](#setup)
- [Commands](#commands)
- [Yarepl start](#yarepl-start)
- [Yarepl start_or_focus_or_hide](#yarepl-start_or_focus_or_hide)
- [Yarepl attach_buffer](#yarepl-attach_buffer)
- [Yarepl detach_buffer](#yarepl-detach_buffer)
- [Yarepl cleanup](#yarepl-cleanup)
- [Yarepl focus](#yarepl-focus)
- [Yarepl hide](#yarepl-hide)
- [Yarepl hide_or_focus](#yarepl-hide_or_focus)
- [Yarepl close](#yarepl-close)
- [Yarepl swap](#yarepl-swap)
- [Yarepl send_visual](#yarepl-send_visual)
- [Yarepl source_visual](#yarepl-source_visual)
- [Yarepl send_line](#yarepl-send_line)
- [Yarepl send_operator](#yarepl-send_operator)
- [Yarepl source_operator](#yarepl-source_operator)
- [Yarepl exec](#yarepl-exec)
- [Keymaps](#keymaps)
- [Window configuration](#window-configuration)
- [Customizing REPLs](#customizing-repls)
- [Delayed Final CR Option](#delayed-final-cr-option)
- [Customizing the Source Syntax](#customizing-the-source-syntax)
- [Example keybinding setup](#example-keybinding-setup)
- [Extensions](#extensions)
- [aider](#aider)
- [codex](#codex)
- [opencode](#opencode)
- [pi](#pi)
- [code-cell](#code-cell)
- [fzf-lua](#fzf-lua)
- [telescope](#telescope)
- [Snacks.picker](#snackspicker)
- [Set up project-level REPLs](#set-up-project-level-repls)
- [Create persistent REPLs in tmux](#create-persistent-repls-in-tmux)
- [FAQ](#faq)
- [Why lazy loading with `lazy.nvim` doesn't work?](#why-lazy-loading-with-lazynvim-doesnt-work)
- [How do I avoid clutter from the bufferline plugin?](#how-do-i-avoid-clutter-from-the-bufferline-plugin)
- [Yarepl send_visual is not functioning properly](#yarepl-send_visual-is-not-functioning-properly)
- [`<Plug>(yarepl-send-visual)` Only Sends to First REPL](#plugyarepl-send-visual-only-sends-to-first-repl)
- [Limitations](#limitations)
- [Acknowledgements](#acknowledgements)
**Breaking change:** `<Plug>` mappings now use lowercase `yarepl` names. If you
previously mapped `<Plug>(Yarepl-start)` or `<Plug>(Yarepl-codex-exec)`, update
them to `<Plug>(yarepl-start)` and `<Plug>(yarepl-codex-exec)`. This change
aligns with the common convention of using lowercase `<Plug>` names across Vim
plugins. This change also takes effect immediately.
The old `REPL*` commands and `<Plug>(REPL*)` maps are now named under
`Yarepl`. Use commands like `:Yarepl start`, `:Yarepl attach_buffer`,
`:Yarepl send_visual`, and `:Yarepl exec`. The matching plug maps are named
like `<Plug>(yarepl-start)` and `<Plug>(yarepl-send-visual)`. The command part
uses snake style, while `<Plug>` names use kebab style.
The legacy commands and keymaps (`REPL*`) still function for now, but they will
be removed on `2026-06-01`.
If you previously used `REPLStart`, `REPLSendVisual`, or
`<Plug>(REPLStart-ipython)`, the replacement is the same idea with a different
wrapper: `:Yarepl start`, `:Yarepl send_visual`, and
`<Plug>(yarepl-start-ipython)`.
The unified `Yarepl` entry point keeps the plugin easier to extend and makes
completion, counts, and future subcommands behave consistently instead of
spreading the same actions across a growing list of top-level commands.
# yarepl.nvim
Yet Another REPL is a flexible REPL / CLI App management tool that supports
multiple paradigms for interacting with them. This plugin also works with
project-level config and tmux, and includes native dot-repeat without requiring
vim-repeat.
Flexibility and parallelism are core priorities. With yarepl.nvim, you can
effortlessly interact with multiple CLI Apps through various paradigms:
- Send text from multiple buffers (same or different file types) to a single
REPL / CLI App.
- Send text from a single buffer to multiple CLI Apps (same program or different)
- Attach a buffer to a dedicated CLI Apps
The plugin features integration with `aider.chat`, `OpenAI Codex CLI`,
`OpenCode`, and `pi`, and provides convenient code cell text object
definitions. Choose
your preferred
fuzzy finder among `telescope`, `fzf-lua`, or `Snacks.picker` to preview active
REPLs. These features are available as [extensions](#extensions).
# Showcase

This image highlights an AI-driven coding assistant and REPL,
[aider.chat](https://aider.chat), managed by `yarepl`.

This example showcases the Codex CLI integration running side by side with a
Neovim buffer, all managed through `yarepl`.
`yarepl` enables integration with the OpenAI's Codex CLI and Aider.chat. For
more details, refer to the [Extensions](#extensions) section.
# Why yarepl.nvim?
With multiple projects at hand, I require the ability to send text from
different files to REPLs with the same type (such as multiple ipython REPLs).
In instances where I'm performing time-consuming tasks, but need to conduct
further experimentation on the current file, I also require the capability to
send text from the same buffer to multiple REPLs.
Furthermore, when conducting mixed-language programming in a literate
programming style in text format such as `rmarkdown`, `quarto`, or plain
`markdown`, I need to send text in the buffer to different REPLs such as R and
Python .
Additionally, `yarepl.nvim` features a `source_syntax` capability that allows
sourcing large code chunks from temporary files instead of sending them
directly to the REPL. This prevents cluttering your interaction history and
provides better handling of substantial code content, especially useful on
Windows where large stdin processing can be problematic. The plugin writes
selected code regions/content to temporary files and provides convenient syntax
definitions for how each REPL should source files.
As a CLI fnatic, to communicate with chatgpt, I prefer through a REPL `aichat`.
Additionally, I require a set of global hotkeys and an isolated REPL
environment to facilitate communication with `aichat` separately without any
interference with other REPLs.
Unfortunately, currently available REPL plugins do not afford me such great
flexibility in managing REPL in multiple ways. This is why `yarepl.nvim` was
created.
# Installation
`nvim 0.9` is required. Although `nvim 0.8` may also work, there are no plans
to ensure backward compatibility with `nvim 0.8` if there are any compatibility
issues.
**lazy.nvim**:
```lua
{ 'milanglacier/yarepl.nvim', config = true }
```
**rocks.nvim**:
`Yarepl` is available on luarocks.org. Simply run `Rocks install yarepl.nvim`
to install it like any other luarocks package.
`yarepl.nvim` does not require any dependencies but functions better with the following plugins:
1. `telescope.nvim` or `fzf-lua`. `yarepl.nvim` provides extensions for REPL
previewer.
2. A UI frontend that provides an alternative frontend for `vim.ui.select`.
Some options are `dressing.nvim` or `telescope-ui-select.nvim` (only one of
them needs to be installed).
# Configuration
## Setup
```lua
-- below is the default configuration, there's no need to copy paste them if
-- you are satisfied with the default configuration, just calling
-- `require('yarepl').setup {}` is sufficient.
local yarepl = require 'yarepl'
yarepl.setup {
-- see `:h buflisted`, whether the REPL buffer should be buflisted.
buflisted = true,
-- whether the REPL buffer should be a scratch buffer.
scratch = true,
-- the filetype of the REPL buffer created by `yarepl`
ft = 'REPL',
-- How yarepl open the REPL window, can be a string or a lua function.
-- See below example for how to configure this option
wincmd = 'belowright 15 split',
-- The available REPL palattes that `yarepl` can create REPL based on.
-- To disable a built-in meta, set its key to `false`, e.g., `metas = { R = false }`
metas = {
aichat = { cmd = 'aichat', formatter = 'bracketed_pasting', source_syntax = 'aichat' },
radian = { cmd = 'radian', formatter = 'bracketed_pasting_no_final_new_line', source_syntax = 'R' },
-- builtin command names search a .venv/bin/ipython first, then fall back to PATH
ipython = { cmd = 'builtin:ipython', formatter = 'bracketed_pasting', source_syntax = 'ipython' },
python = { cmd = 'builtin:python', formatter = 'trim_empty_lines', source_syntax = 'python' },
R = { cmd = 'R', formatter = 'trim_empty_lines', source_syntax = 'R' },
bash = {
cmd = 'bash',
formatter = vim.fn.has 'linux' == 1 and 'bracketed_pasting' or 'trim_empty_lines',
source_syntax = 'bash',
},
zsh = { cmd = 'zsh', formatter = 'bracketed_pasting', source_syntax = 'bash' },
},
-- when a REPL process exits, should the window associated with those REPLs closed?
close_on_exit = true,
-- whether automatically scroll to the bottom of the REPL window after sending
-- text? This feature would be helpful if you want to ensure that your view
-- stays updated with the latest REPL output.
scroll_to_bottom_after_sending = true,
-- Format REPL buffer names as #repl_name#n (e.g., #ipython#1) instead of using terminal defaults
format_repl_buffers_names = true,
-- Highlight the operated range when using send/source operators
highlight_on_send_operator = { enabled = false, hl_group = 'IncSearch', timeout = 150 },
os = {
-- Some hacks for Windows. macOS and Linux users can simply ignore
-- them. The default options are recommended for Windows user.
windows = {
-- Send a final `\r` to the REPL with delay,
send_delayed_final_cr = true,
},
},
-- Display the first line as virtual text to indicate the actual
-- command sent to the REPL.
source_command_hint = {
enabled = false,
hl_group = 'Comment',
},
}
```
## Commands
`yarepl` doesn't set any default keybindings. Instead, it offers a variety of
commands that you can use to create your own keybindings. We'll also provide an
example configuration for keybindings based on these commands. Additionally,
`yarepl` provides a collection of `<Plug>` keymaps, which you can bind them to
your favorite mappings.
Here is a list of available commands:
### Yarepl start
Creates a REPL with id `i` from the list of available REPLs.
You can create a REPL with a specific id by providing a count, such as
`3Yarepl start` for a REPL with id `3`. If no count is provided, a new REPL
with increamental ID will be created. You can also provide a name as an
argument. If no argument is given, you'll be prompted to select a REPL from the
list of available ones. If the id is already in use, it will focus on the REPL
with that id.
When a name is provided and a count is also provided (for example, `2Yarepl
start ipython`), the count selects the Nth REPL with that name. If there are
fewer than N existing REPLs with that name, a new one is created. When a name
is provided without a count (`Yarepl start ipython`), it always creates a new
REPL of that name.
If you append a `!` to the command, the current buffer will attach to the newly
created REPL, for instance, `Yarepl start!` or `3Yarepl start!`. Note that
attachment only happens when a new REPL is created.
### Yarepl start_or_focus_or_hide
Toggles the visibility (focus/hide) of an existing REPL, or creates a new one
if it does not exist.
The rules for counts and optional REPL names mirror those of `Yarepl start`,
including named selection logic like `2Yarepl start_or_focus_or_hide ipython`.
Here are examples of how to use this command:
1. `Yarepl start_or_focus_or_hide` will hide or focus REPL 1 when it exists,
otherwise it creates a new REPL.
2. `Yarepl start_or_focus_or_hide ipython` will hide or focus the first
`ipython` REPL, otherwise it creates a new `ipython` REPL.
3. `3Yarepl start_or_focus_or_hide` will hide or focus REPL 3 when it exists,
otherwise it creates a new REPL.
4. `3Yarepl start_or_focus_or_hide ipython` will hide or focus the 3rd
`ipython` REPL, otherwise it creates a new `ipython` REPL.
**Important difference**: without a count, `Yarepl start` always attempts to
start a new REPL, whereas `Yarepl start_or_focus_or_hide` first attempts to
focus/hide an existing REPL and creates a new one only if none is found.
### Yarepl attach_buffer
Attaches the current buffer to REPL `i`, for instance, `3Yarepl attach_buffer`
will attach the current buffer to REPL 3. If no count is provided, you'll be
prompted to select the REPL you want to attach the current buffer to. If you
add a trailing `!`, it will attempt to detach the current buffer from any REPL.
### Yarepl detach_buffer
Detach current buffer from any REPL.
### Yarepl cleanup
Cleans up any invalid REPLs and rearranges the sequence of REPL ids. Usually,
there's no need to use this command manually since invalid REPLs are cleaned up
automatically at the appropriate time.
### Yarepl focus
Focuses on REPL `i` or the REPL that the current buffer is attached to.
You can provide an optional argument, and the function will attempt to focus on
the closest REPL with the specified name. If no count is supplied, it will try
to focus on the REPL that the current buffer is attached to. If the current
buffer isn't attached to any REPL, it will use REPL 1. If you add a count `i`,
it will focus on the REPL `i`.
Here are some examples of how to use this command:
1. `Yarepl focus` will try to focus on the REPL that the current buffer is
attached to. If the current buffer isn't attached to any REPL, it will use
REPL 1.
2. `Yarepl focus ipython` will try to focus on the closest REPL with the name
`ipython` starting from id `1`.
3. `3Yarepl focus` will focus on REPL 3.
4. `3Yarepl focus ipython` will try to focus on the closest REPL with the name
`ipython` starting from id `3`.
### Yarepl hide
Hides REPL `i` or the REPL that the current buffer is attached to.
If you provide an optional argument, the function will attempt to hide the
closest REPL with the specified name. When no count is supplied, it will try to
hide the REPL that the current buffer is attached to. If the current buffer
isn't attached to any REPL, it will use REPL 1. If you add a count `i`, it
will hide REPL `i`.
Here are examples of how to use this command:
1. `Yarepl hide` will try to hide the REPL that the current buffer is attached
to. If the current buffer isn't attached to any REPL, it will use REPL 1.
2. `Yarepl hide ipython` will try to hide the closest REPL with the name
`ipython` starting from id `1`.
3. `3Yarepl hide` will hide REPL 3.
4. `3Yarepl hide ipython` will try to hide the closest REPL with the name
`ipython` starting from id `3`.
### Yarepl hide_or_focus
Hides or focuses on REPL `i` or the REPL that the current buffer is attached
to.
If you provide an optional argument, the function will attempt to hide or
focus on the closest REPL with the specified name. When no count is supplied,
it will try to hide or focus on the REPL that the current buffer is attached to.
If the current buffer isn't attached to any REPL, it will use REPL 1. If you
add a count `i`, it will hide REPL `i`.
Here are examples of how to use this command:
1. `Yarepl hide_or_focus` will try to hide or focus on the REPL that the
current buffer is attached to. If the current buffer isn't attached to any
REPL, it will use REPL 1.
2. `Yarepl hide_or_focus ipython` will try to hide or focus on the closest
REPL with the name `ipython` starting from id `1`.
3. `3Yarepl hide_or_focus` will hide or focus on REPL 3.
4. `3Yarepl hide_or_focus ipython` will try to hide or focus on the closest
REPL with the name `ipython` starting from id `3`.
### Yarepl close
Closes REPL `i` or the REPL that the current buffer is attached to.
If you provide an optional argument, the function will attempt to close the
closest REPL with the specified name. If no count is supplied, it will try to
close the REPL that the current buffer is attached to. If the current buffer
isn't attached to any REPL, it will use REPL 1. If you add a count `i`, it
will close REPL `i`.
Here are examples of how to use this command:
1. `Yarepl close` will try to close the REPL that the current buffer is
attached to. If the current buffer isn't attached to any REPL, it will use
REPL 1.
2. `Yarepl close ipython` will try to close the closest REPL with the name
`ipython` and starting from id `1`.
3. `3Yarepl close` will close REPL 3.
4. `3Yarepl close ipython` will try to close the closest REPL with the name
`ipython` starting from id `3`.
### Yarepl swap
Swaps two REPLs. If no REPL ID is provided, you'll be prompted to select both
REPLs. If you provide one REPL ID, you'll be prompted to select the second
REPL.
### Yarepl send_visual
Sends the visual range to REPL `i` or the REPL that the current buffer
is attached to.
If you provide an optional argument, the function will attempt to send to the
closest REPL with the specified name. When no count is supplied, it first
checks whether the current buffer is attached to a REPL with that name and uses
it. If the buffer isn't attached to a matching REPL, it will use REPL 1 to
find the closest match. If you add a count `i`, it will send to the closest
REPL with that name relative to `i`.
Optional highlighting for the operated range is available for both
`Yarepl send_operator` and `Yarepl source_operator` by setting
`highlight_on_send_operator.enabled = true` in your setup.
Here are examples of how to use this command:
1. `Yarepl send_visual` sends the visual range to the REPL that the current
buffer is attached to. If the buffer is not attached to any REPL, it uses
REPL 1.
2. `3Yarepl send_visual` sends the visual range to REPL 3.
3. `Yarepl send_visual ipython` sends the visual range to the attached ipython
REPL if there is one for the current buffer; otherwise, it uses the closest
ipython REPL relative to id `1`.
4. `3Yarepl send_visual ipython` sends the visual range to the closest ipython
REPL relative to id `3`.
Note that due to a limitation of vim, when using `Yarepl send_visual` via
cmdline rather than in a keymap, you must press `Control+u` before using the
command. For example, `V3j:<Control+u>3Yarepl send_visual` sends the selected
three lines to REPL `3`. However, you do not need to specify `Control+u` in
your keymap as the function will do this for you.
### Yarepl source_visual
Similar to `Yarepl send_visual`, the key distinction with `Yarepl source_visual`
is that it first writes the visually selected code to a temporary file. It then
sends a one-liner command to the REPL to source this file, instead of sending
the content directly.
The primary advantage of `Yarepl source_visual` lies in handling large code
content. Instead of sending huge code chunks directly to the REPL, it prevents
cluttering your interaction history, maintaining a cleaner session.
Additionally, on Windows, sourcing from a file mitigates potential issues with
stdin processing when the REPL must read substantial input, as the file-based
approach significantly reduces the data read from the stdin.
Yarepl automatically removes its temporary files when Neovim exits. Since the
REPL executes their contents, only source code you trust.
Note that the REPL configuration requires a corresponding `source_syntax`
implementation. For more information, refer to the section [Customizing the
Source Syntax](#customizing-the-source-syntax). Built-in source
implementations are available for Python, R, and Bash.
Consider enabling `config.source_command_hint.enabled = true`. When enabled,
the first non-empty line of the code chunk displays as virtual text alongside
the source command sent to the REPL, providing a useful hint about the actual
command being executed.
### Yarepl send_line
Sends current line to REPL `i` or the REPL that current buffer is attached to.
If you provide an optional argument, the function will attempt to send to the
closest REPL with the specified name. When no count is supplied, it first
checks whether the current buffer is attached to a REPL with that name and uses
it. If the buffer isn't attached to a matching REPL, it will use REPL 1 to
find the closest match. If you add a count `i`, it will send to the closest
REPL with that name relative to `i`.
Here are examples of how to use this command:
1. `Yarepl send_line` sends the current line to the REPL that the current
buffer is attached to. If the buffer is not attached to any REPL, it uses
REPL 1.
2. `3Yarepl send_line` sends the current line to REPL 3.
3. `Yarepl send_line ipython` sends the current line to the attached ipython
REPL if there is one for the current buffer; otherwise, it uses the closest
ipython REPL relative to id `1`.
4. `3Yarepl send_line ipython` sends the current line to the closest ipython
REPL relative to id `3`.
### Yarepl send_operator
The operator to send the text to REPL `i` or the REPL that the current buffer
is attached to.
If you provide an optional argument, the function will attempt to send to the
closest REPL with the specified name. When no count is supplied, it first
checks whether the current buffer is attached to a REPL with that name and uses
it. If the buffer isn't attached to a matching REPL, it will use REPL 1 to
find the closest match. If you add a count `i`, it will send to the closest
REPL with that name relative to `i`.
Here are examples of how to use this command:
1. `Yarepl send_operator` acts as the operator to send the text to the REPL
that the current buffer is attached to. If the buffer is not attached to any
REPL, it uses REPL 1.
2. `3Yarepl send_operator` sends the motion to REPL 3.
3. `Yarepl send_operator ipython` sends the motion to the attached ipython REPL
if there is one for the current buffer; otherwise, it uses the closest
ipython REPL relative to id `1`.
4. `3Yarepl send_operator ipython` sends the motion to the closest ipython
REPL relative to id `3`.
`Yarepl send_operator` is **dot-repeatable**, you do not need to install
vim-repeat to make it work.
### Yarepl source_operator
The `Yarepl source_operator` is analogous to the `Yarepl send_operator`. To
understand the distinction between these two operators, refer to the section on
`Yarepl source_visual`, which contrasts `Yarepl send_visual` with
`Yarepl source_visual`. This comparison provides a clear analogy that
highlights the differences between `Yarepl send_operator` and
`Yarepl source_operator`.
### Yarepl exec
Sends the command typed in the cmdline to REPL `i` or the REPL that the current
buffer is attached to.
If the first argument of this command is `$NAME`, the function will attempt to
send to a REPL with the specified `NAME`. If no count is supplied, it first
checks whether the current buffer is attached to a REPL with that name and uses
it. If the buffer isn't attached to a matching REPL, it will use REPL 1 to
find the closest match. If you add a count `i`, it will send to the closest
REPL with that name relative to `i`.
Here are examples of how to use this command:
1. `Yarepl exec %run a_file.py` will send the command `%run a_file.py` to the
REPL 1.
2. `3Yarepl exec print("hello world")` will send the command `print("hello
world")` to the REPL 3.
3. `Yarepl exec $ipython %whos` will send the command `%whos` to the closest
ipython REPL relative to id 1.
4. `Yarepl exec $ipython %whos` will send the command `%whos` to the closest
ipython REPL relative to id 3.
5. `Yarepl exec print("hello world")^Mprint("hello world again")` will send the
following two lines to the REPL current buffer is attached to or REPL 1.
```python
print("hello world")
print("hello world again")
```
Note:
1. To type a **literal** `<Enter>` (`^M`) in `cmdline`, you must press
`<Ctrl-v> <Enter>` rather than directly type `Enter`.
2. Some neovim command will interpolate `%` to the file name of current buffer.
But `Yarepl exec` will not do this for you. The interpolation only happens for
the first `$` to get the desired `REPL` name.
## Keymaps
`yarepl` provides the following keymaps:
- `<Plug>(yarepl-start)`
- `<Plug>(yarepl-start-or-focus-or-hide)`
- `<Plug>(yarepl-focus)`
- `<Plug>(yarepl-hide)`
- `<Plug>(yarepl-hide-or-focus)`
- `<Plug>(yarepl-send-line)`
- `<Plug>(yarepl-send-operator)`
- `<Plug>(yarepl-send-visual)`
- `<Plug>(yarepl-source-operator)`
- `<Plug>(yarepl-source-visual)`
- `<Plug>(yarepl-close)`
- `<Plug>(yarepl-exec)`
The keymap variant behaves exactly the same as its command variant. For
example, you map `<Leader>s` to `<Plug>(yarepl-start)`, then type `<Leader>s`
is equivalent to `:Yarepl start`. Type `3<Leader>s` is equivalent to
`:3Yarepl start`.
And for each meta you registered (say you have a meta named `ipython`), the following keymaps will be registered:
- `<Plug>(yarepl-start-ipython)`
- `<Plug>(yarepl-start-or-focus-or-hide-ipython)`
- `<Plug>(yarepl-focus-ipython)`
- `<Plug>(yarepl-hide-ipython)`
- `<Plug>(yarepl-hide-or-focus-ipython)`
- `<Plug>(yarepl-send-line-ipython)`
- `<Plug>(yarepl-send-operator-ipython)`
- `<Plug>(yarepl-send-visual-ipython)`
- `<Plug>(yarepl-source-operator-ipython)`
- `<Plug>(yarepl-source-visual-ipython)`
- `<Plug>(yarepl-close-ipython)`
- `<Plug>(yarepl-exec-ipython)`
For keymaps with a meta, as you would expected, say you bind `<LocalLeader>s`
to `<Plug>(yarepl-start-ipython)`, then type `<LocalLeader>s` is equivalent to
`:Yarepl start ipython`. Type `3<LocalLeader>s` is equivalent to
`:3Yarepl start ipython`.
Note that any letters that are not alphanumeric or `-`/`_` will be replaced
with `-`. Say you have a meta named `python a`, the corresponding keymap to
access them will be `<Plug>(yarepl-start-python-a)`.
When you are binding those plug keymaps to your own keybindings, make sure this is
a recursive map. e.g. `vim.keymap.set('n', '<Plug>(yarepl-start-ipython)', { noremap = false })`.
# Window configuration
if `wincmd` is a string, `yarepl` will execute it as a vimscript command.
```lua
wincmd = 'belowright 15 split'
-- will create a horizontal split below the current using window and takes up 15 lines for the new window
wincmd = 'vertical 30 split'
-- will create a vertical split right to the current using window and takes up 30 columns for the new window
```
In addition to passing a string to `wincmd`, you can also pass a Lua function.
This function accepts two parameters: the buffer number of the REPL buffer, and
the name of the REPL (the keys of `metas`).
```lua
wincmd = function(bufnr, name)
vim.api.nvim_open_win(bufnr, true, {
relative = 'editor',
row = math.floor(vim.o.lines * 0.25),
col = math.floor(vim.o.columns * 0.25),
width = math.floor(vim.o.columns * 0.5),
height = math.floor(vim.o.lines * 0.5),
style = 'minimal',
title = name,
border = 'rounded',
title_pos = 'center',
})
end
```
This function creates a floating window at the center of the Vim screen with
specific size and styling.
You can further customize the behavior by applying the `wincmd` configuration
to specific `meta` entries. When a `meta` includes its own `wincmd` setting, it
overrides the global `wincmd`.
```lua
float_wincmd = function(bufnr, name)
vim.api.nvim_open_win(bufnr, true, {
relative = 'editor',
row = math.floor(vim.o.lines * 0.25),
col = math.floor(vim.o.columns * 0.25),
width = math.floor(vim.o.columns * 0.5),
height = math.floor(vim.o.lines * 0.5),
style = 'minimal',
title = name,
border = 'rounded',
title_pos = 'center',
})
end
yarepl.setup {
metas = {
-- REPL local settings
ipython = { wincmd = 'topleft 25 split' },
radian = { wincmd = float_wincmd },
}
-- global settings
wincmd = 'belowright 15 split',
}
```
Similar to `wincmd` (which allows you to configure a global default with
meta-local overrides), you can also set meta-local overrides for
`source_command_hint`. The configuration option name for meta-local overrides
is identical to the global setting.
# Customizing REPLs
You can disable a built-in REPL meta by set the key to `false`:
```lua
metas = {
R = false
}
```
To modify a built-in meta's settings, simply override the specific option.
There's no need to copy the default values for other options:
```lua
metas = {
ipython = { cmd = { 'ipython', '--simple-prompt' } }
}
```
The built-in command names `builtin:ipython` and `builtin:python` look for
`.venv/bin` on Unix-like systems or `.venv/Scripts` on Windows before falling
back to the executable on `PATH`.
You can add your own REPL meta by following this example:
```lua
function send_line_verbatim(lines)
-- each line is a string
return lines
end
function ipython_or_python()
-- find_binary searches upward from the current directory until it finds the binary
-- search_root: relative path to search (e.g., ".venv/bin")
-- binary_name: executable to locate (e.g., "ipython")
-- fallback_binary: returned if no match is found (e.g., 'ipython' from PATH)
local ipython_cmd = yarepl.cmd_builtin.find_binary(".venv/bin", "ipython", 'ipython')
if vim.fn.executable(ipython_cmd) == 1 then
return { ipython_cmd, '--simple-prompt' }
end
-- Fall back to python3 using the same search logic
return yarepl.cmd_builtin.find_binary(".venv/bin", "python3", 'python3')
end
function ipython_or_python_formatter(lines)
if vim.fn.executable 'ipython' == 1 then
return yarepl.formatter.bracketed_pasting(lines)
else
return yarepl.formatter.trim_empty_lines(lines)
end
end
metas = {
ipython_new = { cmd = { 'ipython', '--simple-prompt' }, formatter = send_line_verbatim },
ipython_or_python = { cmd = ipython_or_python, formatter = ipython_or_python_formatter },
}
```
`cmd` can be three types: a string, a list of strings, or a function that
returns either a string or list of strings. It can also be one of yarepl's
builtin command names, such as `builtin:ipython` or `builtin:python`.
If you want to build your own path lookup logic, use
`require('yarepl').cmd_builtin.find_binary(search_root, binary_name, fallback_binary)`
inside a custom `cmd` function. The helper searches upward from the current
directory for `search_root/binary_name` and returns `fallback_binary` when no
matching binary is found.
`formatter` can be either:
1. A string that matches a builtin formatter name:
- `bracketed_pasting`: wrap the content within bracketed paste sequences
- `bracketed_pasting_no_final_new_line`: similar to `bracketed_pasting`, but does not add a new line at the end
- `bracketed_pasting_delayed_cr`: similar to `bracketed_pasting`, but use with `send_delayed_final_cr = true`
- `trim_empty_lines`: remove empty lines from the input
2. A function that takes a list of strings as input and returns a list of
strings to send to the REPL
[Here is a more complex example for ghci, a haskell repl.](https://github.com/milanglacier/yarepl.nvim/issues/21)
`yarepl` offers a convenient helper function that simplifies the process of
creating a custom formatter without starting from scratch. For usage examples
and general guidelines on setting your own REPL formatter, expand the
**Details** section below.
<details>
Some REPLs can distinguish between pasted text and text from the user manual
input by using prefix and suffix sequences, such as bracketed paste.
For modern REPLs with bracketed pasting support (which is usually the case), it
is recommended to use "`bracketed_pasting`"
Here are some tips for writing your own formatter function:
1. You may want to add a new entry `"\r"` at the end of the list to indicate
the end of input.
2. If your REPL cannot distinguish between copy-pasted text and text from user
manual input, you may want to replace `\t` with 4 or 8 spaces since sending
a raw `\t` may be interpreted as invoking completion.
3. Do not include `\n` in any line as the `chansend` function will
automatically replace it with `\0`.
4. You may want to remove any empty lines from the input (a list of strings)
since `chansend` function translates an empty string `""` into `"\n"`. For
some REPLs without bracketed pasting support (such as Python), a plain
`"\n"` may be treated as the end of input, blocking the rest of the code in
the same function.
5. If your REPL cannot distinguish between copy-pasted text and text from user
manual input and your REPL will do auto-indent for you, you may want to
remove any leading spaces from each line to prevent double indentation.
6. The returned list of strings will be sent to the `chansend` function for
reference.
```lua
-- Calling this function will return a function that takes a list of strings as
-- input and returns a list of strings. This can be used as the formatter function
-- of meta.
-- these are the default config
yarepl.formatter.factory {
-- Specifies whether to return tabs in the string as spaces.
replace_tab_by_space = false,
-- Specifies the number of spaces to replace the tab (if enabled).
number_of_spaces_to_replace_tab = 8,
-- For a list of strings containing more than one string:
when_multi_lines = {
-- The prefixing code sent to the repl firstly.
open_code = '',
-- The suffixing code sent to the repl finally.
end_code = '\r',
-- Whether to remove empty lines from the list of strings.
trim_empty_lines = false,
-- Whether to remove leading spaces at the beginning of each line.
remove_leading_spaces = false,
-- If gsub_pattern and gsub_repl are not empty, `string.gsub` will
-- be called with `gsub_pattern` and `gsub_repl` on each line. Note
-- that you should use Lua pattern instead of Vim regex pattern.
-- The gsub calls happen after `trim_empty_lines`,
-- `remove_leading_spaces`, and `replace_tab_by_space`, and before
-- prepending and appending `open_code` and `end_code`.
gsub_pattern = '',
gsub_repl = '',
},
-- For a list containing only one string:
when_single_line = {
-- The prefixing code sent to the repl firstly.
open_code = '',
-- The suffixing code sent to the repl finally.
end_code = '\r',
-- the same as the specs of `when_multi_lines`
gsub_pattern = '',
gsub_repl = '',
},
os = {
-- Some hacks for Windows. macOS and Linux users can simply ignore
-- them. The default options are recommended for Windows user.
windows = {
-- Join the lines with `\r` before sending to REPL.
join_lines_with_cr = true,
},
},
}
-- `yarepl` provides four builtin formatters that can be referenced by name:
-- 1. 'bracketed_pasting' - Uses bracketed paste mode for modern REPLs
-- 2. 'bracketed_pasting_no_final_new_line' - Same as above but without final newline
-- 3. 'bracketed_pasting_delayed_cr': similar to `bracketed_pasting`, but use with `send_delayed_final_cr = true`
-- 4. 'trim_empty_lines' - Trims empty lines from input
-- You can also create custom formatters by calling `yarepl.formatter.factory`:
yarepl.formatter.trim_empty_lines = yarepl.formatter.factory {
when_multi_lines = {
trim_empty_lines = true,
remove_leading_spaces = false,
},
}
yarepl.formatter.bracketed_pasting = yarepl.formatter.factory {
when_multi_lines = {
open_code = '\27[200~',
end_code = '\27[201~\r',
trim_empty_lines = false,
remove_leading_spaces = false,
},
}
```
</details>
## Delayed Final CR Option
`send_delayed_final_cr` (optional, defaults to `false`): Some REPLs do not
recognize the final CR (return)'s purpose is to tell the REPL that we want to
"finalize" (or evaluate) that command when it is input with a large chunk of
text when bracketed pasting is enabled. To mitigate this, we have to send the
final CR with a delay (to let the REPL realize that we want to evaluate that
command). In general we should ignore this option (keep it as the default
`false`). When you do enable this option, prefer using the
`bracketed_pasting_delayed_cr` formatter so that the final CR is not included
in the initial stream (it will be sent by the delayed event). The observed
exceptions are Claude Code, Codex, and Opencode which should use `true`. PRs
are welcome if you find other REPLs that require setting this option to `true`.
Example usage:
```lua
metas = {
claude_code = {
cmd = 'claude',
formatter = 'bracketed_pasting_delayed_cr',
source_syntax = '@{{file}}',
send_delayed_final_cr = true
},
ipython = {
cmd = 'ipython',
formatter = 'bracketed_pasting',
send_delayed_final_cr = false -- this is the default, can be omitted
},
-- yarepl provides builtin extension to use with codex.
codex = require('yarepl.extensions.codex').create_codex_meta(),
-- yarepl provides builtin extension to use with pi.
pi = require('yarepl.extensions.pi').create_pi_meta(),
}
```
# Customizing the Source Syntax
To utilize `Yarepl source_operator` and `Yarepl source_visual`, your REPL meta
configuration must include either `source_syntax`.
Here's an example setup using `yarepl` with a source syntax:
```lua
local yarepl = require 'yarepl'
yarepl.setup {
metas = {
radian = {
cmd = 'radian',
formatter = 'bracketed_pasting_no_final_new_line',
source_syntax = 'eval(parse(text = "{{file}}"))',
},
}
}
```
When `source_syntax` is specified, the selected code content is initially
written to a temporary file. Here, `{{file}}` serves as a placeholder, which is
replaced by the temporary file path. The interpolated string is subsequently
sent to the REPL.
Several built-in `source_syntax` options can be accessed as strings: `R`,
`aichat`, `bash`, `ipython` and `python`.
For a more flexible "sourcing" behavior, you can also define `source_syntax` as
a function, instead of using a string with `{{file}}`. This function must take
a string and return a string. The input is the selected code, and the output is
what gets sent to the REPL.
A common approach involves writing the input string to a temporary file, then
returning a string that sources this file. The exact "sourcing" syntax depends
on the target programming language.
Here's an example setup using `yarepl` with a source function:
<details>
```lua
local yarepl = require 'yarepl'
local python_source_func = function(str)
local file = yarepl.make_tmp_file(str)
if not file then
return
end
local cmd = string.format('exec(open("%s", "r").read())', file)
return cmd
end
yarepl.setup {
metas = {
ipython = {
cmd = 'ipython',
formatter = 'bracketed_pasting',
source_syntax = python_source_func,
},
}
}
```
</details>
# Example keybinding setup
If you don't want to use those `<Plug>` keymaps provided by the plugin but
instead want to build the keymaps by your own, please check the
[wiki.](https://github.com/milanglacier/yarepl.nvim/wiki/Example-Keymap-setup-without-using-%60-Plug-%60)
Here is the keybindings setup from the maintainer:
```lua
local keymap = vim.api.nvim_set_keymap
local bufmap = vim.api.nvim_buf_set_keymap
keymap('n', '<Leader>cs', '<Plug>(yarepl-start-aichat)', {
desc = 'Start an Aichat REPL',
})
keymap('n', '<Leader>cf', '<Plug>(yarepl-focus-aichat)', {
desc = 'Focus on Aichat REPL',
})
keymap('n', '<Leader>ch', '<Plug>(yarepl-hide-aichat)', {
desc = 'Hide Aichat REPL',
})
keymap('v', '<Leader>cr', '<Plug>(yarepl-send-visual-aichat)', {
desc = 'Send visual region to Aichat',
})
keymap('v', '<Leader>cR', '<Plug>(yarepl-source-visual-aichat)', {
desc = 'Source visual region to Aichat',
})
keymap('n', '<Leader>crr', '<Plug>(yarepl-send-line-aichat)', {
desc = 'Send lines to Aichat',
})
keymap('n', '<Leader>cr', '<Plug>(yarepl-send-operator-aichat)', {
desc = 'Send Operator to Aichat',
})
keymap('n', '<Leader>cr', '<Plug>(yarepl-source-operator-aichat)', {
desc = 'Source Operator to Aichat',
})
keymap('n', '<Leader>ce', '<Plug>(yarepl-exec-aichat)', {
desc = 'Execute command in aichat',
})
keymap('n', '<Leader>cq', '<Plug>(yarepl-close-aichat)', {
desc = 'Quit Aichat',
})
local ft_to_repl = {
r = 'radian',
R = 'radian',
rmd = 'radian',
quarto = 'radian',
markdown = 'radian',
python = 'ipython',
sh = 'bash',
}
autocmd('FileType', {
pattern = { 'quarto', 'markdown', 'markdown.pandoc', 'rmd', 'python', 'sh', 'REPL', 'r' },
group = my_augroup,
desc = 'set up REPL keymap',
callback = function()
local repl = ft_to_repl[vim.bo.filetype]
repl = repl and ('-' .. repl) or ''
bufmap(0, 'n', '<LocalLeader>rs', string.format('<Plug>(yarepl-start%s)', repl), {
desc = 'Start an REPL',
})
bufmap(0, 'n', '<LocalLeader>rf', '<Plug>(yarepl-focus)', {
desc = 'Focus on REPL',
})
bufmap(0, 'n', '<LocalLeader>rv', '<CMD>Telescope yarepl_show<CR>', {
desc = 'View REPLs in telescope',
})
bufmap(0, 'n', '<LocalLeader>rh', '<Plug>(yarepl-hide)', {
desc = 'Hide REPL',
})
bufmap(0, 'v', '<LocalLeader>s', '<Plug>(yarepl-send-visual)', {
desc = 'Send visual region to REPL',
})
bufmap(0, 'v', '<LocalLeader>S', '<Plug>(yarepl-source-visual)', {
desc = 'Source visual region to REPL',
})
bufmap(0, 'n', '<LocalLeader>ss', '<Plug>(yarepl-send-line)', {
desc = 'Send line to REPL',
})
bufmap(0, 'n', '<LocalLeader>s', '<Plug>(yarepl-send-operator)', {
desc = 'Send operator to REPL',
})
bufmap(0, 'n', '<LocalLeader>S', '<Plug>(yarepl-source-operator)', {
desc = 'Source operator to REPL',
})
bufmap(0, 'n', '<LocalLeader>re', '<Plug>(yarepl-exec)', {
desc = 'Execute command in REPL',
expr = true,
})
bufmap(0, 'n', '<LocalLeader>rq', '<Plug>(yarepl-close)', {
desc = 'Quit REPL',
})
bufmap(0, 'n', '<LocalLeader>rc', '<CMD>Yarepl cleanup<CR>', {
desc = 'Clear REPLs.',
})
bufmap(0, 'n', '<LocalLeader>rS', '<CMD>Yarepl swap<CR>', {
desc = 'Swap REPLs.',
})
bufmap(0, 'n', '<LocalLeader>r?', '<Plug>(yarepl-start)', {
desc = 'Start an REPL from available REPL metas',
})
bufmap(0, 'n', '<LocalLeader>ra', '<CMD>Yarepl attach_buffer<CR>', {
desc = 'Attach current buffer to a REPL',
})
bufmap(0, 'n', '<LocalLeader>rd', '<CMD>Yarepl detach_buffer<CR>', {
desc = 'Detach current buffer to any REPL',
})
end,
})
```
With the keybinding setup, prefixing keybindings with <Leader>c ensures that
the text is always sent to the aichat REPL, a REPL for chatgpt.
For maximum flexibility with other programming languages, the maintainer
desires the ability to easily switch between two modes:
1. Sending text from multiple files to a REPL via `2<LocalLeader>s`, regardless
of which buffer the maintainer is visiting. This guarantees that the text is
always sent to `RPEL 2`.
2. Sending text to a dedicated REPL for each buffer. To avoid the hassle of
remembering the exact ID associated with the desired REPL, the maintainer
can use `<LocalLeader>ra` to attach the current buffer to a REPL.
Subsequently, the `<LocalLeader>s` key can be directly used to send the text
to the desired REPL.
# Extensions
The `Extensions` module contains extended functionalities built upon the core
of yarepl.nvim. While not considered as core part of yarepl, it offers valuable
additional features. For comprehensive information about the features, please
refer to [extensions/README.md](extensions/README.md).
Currently, the module includes:
## aider
This module enhances AI-assisted coding capabilities through
[aider.chat](https://aider.chat) integration.
## codex
This module enhances AI-assisted coding capabilities through [OpenAI's Codex
CLI](https://github.com/openai/codex) integration.
## opencode
This module enhances AI-assisted coding capabilities through
[OpenCode](https://opencode.ai) integration. Its extension-specific `<Plug>`
maps follow the same lowercase naming pattern, for example
`<Plug>(yarepl-opencode-exec)`.
## pi
This module enhances AI-assisted coding capabilities through
[pi](https://pi.dev) integration. Its extension-specific `<Plug>`
maps follow the same lowercase naming pattern, for example
`<Plug>(yarepl-pi-exec)`.
## code-cell
This module simplifies the creation of code cell text objects, allowing you to
utilize them with `Yarepl send_operator` or other operators such as paste, delete,
and formatting.
## fzf-lua
This module provides a fuzzy finder interface to preview active REPLs with `fzf-lua`.
## telescope
This module provides a fuzzy finder interface to preview active REPLs with `telescope`.
## Snacks.picker
This module provides a fuzzy finder interface to preview active REPLs with `Snacks.picker`.
# Set up project-level REPLs
You may want to have the ability to control the REPL metas at the project
level. For example, you may want to open `ipython` installed in a conda
environment for one project and a different `ipython` installed in another
conda environment for another project.
One way to achieve this is to:
- Enable the built-in `exrc`, which requires `nvim 0.9` for security reasons.
To enable `exrc`, add the following line to your Neovim config:
```lua
vim.o.exrc = true
```
Then, configure `yarepl` like so:
```lua
vim.g.yarepl_ipython_paths = vim.g.yarepl_ipython_paths or {}
local yarepl = require 'yarepl'
require('yarepl').setup {
metas = {
ipython = {
cmd = function()
local cwd = vim.fn.getcwd()
if vim.g.yarepl_ipython_paths and vim.g.yarepl_ipython_paths[cwd] then
return vim.g.yarepl_ipython_paths[cwd]
else
return 'ipython'
end
end,
},
},
}
```
Now, in the project root directory `~/projects/project1`, create a file
called `.nvim.lua` with the following lines:
```lua
local cwd = vim.fn.getcwd()
if vim.g.yarepl_ipython_paths then
vim.g.yarepl_ipython_paths[cwd] = '~/mambaforge/envs/a-conda-env/bin/ipython'
else
vim.g.yarepl_ipython_paths = {
[cwd] = '~/mambaforge/envs/a-conda-env/bin/ipython',
}
end
```
The first time you open `project1`, Neovim will prompt you to decide whether
you want to load the `.nvim.lua` file. Please allow it.
**Note:** The `.nvim.lua` file will be automatically loaded only once when
Neovim starts. Thus, if you switch working directories during the time Neovim
is running, the `.nvim.lua` file won't be loaded at the new working directory.
To manually load the `.nvim.lua` file after switching to a new working
directory, try `:luafile .nvim.lua`.
# Create persistent REPLs in tmux
If you would like to maintain a persistent REPL process even after exiting
neovim, you can utilize tmux. To achieve this, the following configuration
creates a REPL meta named `ipy_tmux` that attaches to a tmux session named
`ipython`. If the session does not exist, a new tmux session named `ipython` is
created, and an `ipython` REPL is started.
```lua
metas = {
ipy_tmux = {
cmd = 'tmux attach -t ipython || tmux new -s ipython ipython',
formatter = yarepl.formatter.bracketed_pasting,
},
}
```
# FAQ
## Why lazy loading with `lazy.nvim` doesn't work?
We recommend using `event = 'VeryLazy'` to do the lazy loading. If you want to
use `keys` to lazy load this plugin, make sure you are using recursive mapping:
```lua
-- Recommended
return {
'milanglacier/yarepl.nvim',
event = 'VeryLazy',
config = function()
-- add your configs here
end,
}
-- Also works, but use with caution!
return {
'milanglacier/yarepl.nvim',
keys = {
{ '<Leader>s', '<Plug>(yarepl-start)', noremap = false, mode = 'n' },
{ '<LocalLeader>o', '<Plug>(yarepl-start-ipython)', noremap = false, ft = 'python', mode = 'n' },
},
config = function()
-- your config here
end,
}
```
## How do I avoid clutter from the bufferline plugin?
If you are using a bufferline plugin and do not want the REPL buffers to
clutter your bufferline, pass `buflisted = false` in the `setup` function.
In case you have unlisted the REPLs and need to view the running ones, use
`Telescope yarepl_show`.
## Yarepl send_visual is not functioning properly
Refer to [Yarepl send_visual](#yarepl-send_visual)
## `<Plug>(yarepl-send-visual)` Only Sends to First REPL
When using which-key.nvim and binding `<Plug>(yarepl-send-visual)` or its variants
(like `<Plug>(yarepl-send-visual-ipython)`) to keybindings that start with leader
or local leader keys, visual selections will always be sent to the first REPL,
regardless of any numeric prefix entered.
This behavior occurs due to a conflict with which-key.nvim, as it consumes the
count input before it reaches `<Plug>(yarepl-send-visual)`, resulting in a count
value of `0`.
To resolve this issue, you have several options:
1. Disable which-key.nvim in visual mode
2. Bind `<Plug>(yarepl-send-visual)` to key sequences that don't trigger which-key
(e.g., `<A-s>`)
3. Use alternative methods such as `Yarepl attach_buffer` to connect the
current buffer to a REPL other than the first one
# Limitations
- Currently, `yarepl` does not support sending block-wise visual selections. If
a user attempts to send code while in block-wise visual mode, it will
automatically fall back to sending the selection line-wise.
# Acknowledgements
- [iron.nvim](https://github.com/Vigemus/iron.nvim)
- [toggleterm.nvim](https://github.com/akinsho/toggleterm.nvim)
Instalação
Instale a skill a partir de https://github.com/milanglacier/yarepl.nvimEsta skill não está publicada no registro do ClawHub. Cole o prompt no seu agente de código — Claude Code, Cursor, Codex — e ele instalará a skill direto do repositório de origem.
Abrir o repositório