by tidalcycles

tidalcycles /vim-tidal

Vim plugin for TidalCycles

138 Stars 33 Forks Last release: 6 months ago (1.4.8) MIT License 108 Commits 5 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:


A Vim/NeoVim plugin for TidalCycles, the language for live coding musical patterns written in Haskell.

This plugin by default uses tmux, a known and loved terminal multiplexer, for communicating with between Vim and the Tidal interpreter. It was originally based on vim-slime.

New: If you are using NeoVim, you can now use the Terminal instead of tmux. Read the Configuration section on how to enable it.

Getting Started

  1. Start livecoding with Vim by simply running:
   $ tidalvim

This creates a tmux session with Vim and Tidal running on different panes.

  1. Write something like this:
   d1 $ sound "bd sn"
  1. While being on that line, press
     (Control + E) to evaluate it.

You should see Vim flash that line for a second and a chunk of text appear on your Tidal interpreter. If you already have SuperDirt or other synth running, you should hear a kick and a snare :)


Make sure you have TidalCycles installed, with SuperDirt running. See the Tidal wiki for more information.

Install tmux


You can install it from the main repos:

$ sudo apt-get install tmux


$ brew install tmux


There seems to be a Cygwin package for tmux, but I haven't tested this plugin on Windows anyway, so you are on your own here.

If you happen to make it work, let me know so I can update this section!

Install plugin

I recommend using a Vim plugin manager like Plug. Check the link for instructions on installing and configuring. If you don't want a plugin manager, you can also download the latest release here and extract the contents on your Vim directory (usually


For example, with Plug you need to:

  • Edit your
    file and add these lines:
Plug 'tidalcycles/vim-tidal'
  • Restart Vim and execute
    to automatically download and install the plugins.

Finally, go to the plugin repository and run

make install
$ cd ~/.vim/plugged/vim-tidal
$ sudo make install

This creates symlinks on

scripts. You can remove them later if you want with
make uninstall

Make sure to have the

filetype plugin on
setting on your .vimrc, otherwise plugin won't be loaded when opening a .tidal file.

Older Tidal versions (pre 1.0)

Tidal 1.0 introduces some breaking changes, so if haven't upgraded yet, you can still use this plugin with an older version. Just point your Plug entry to use the


First change your Plug line on your

Plug 'tidalcycles/vim-tidal', {'branch': 'tidal-0.9'}

Then on Vim run

to update your plugin.


This plugin comes bundled with two Bash scripts:



starts a tmux session with the screen horizontally splitted, having Vim on the upper pane and the Tidal interpreter on the lower pane. This is the simplest way to start using Tidal with Vim.

You don't have to use

necessarily. If you have a more complex setup or just want to use Vim outside of tmux, you can use
. See below.


fires up GHCi (the Glasgow Haskell interpreter) and runs a bootstrap file that loads Tidal up.
uses this script to start the Tidal interpreter on the lower pane. You can even use it standalone (without Vim) by simply running
from your shell.
$ tidal
GHCi, version 7.10.3:  :? for help
tidal> d1 $ sound "bd sn"
tidal> :t density 2 $ n "0 1"
density 2 $ n "0 1" :: Pattern ParamMap

So, in case you don't want to use

, just run the following on another terminal:
tmux new-session -s tidal tidal


does is actually run
with the argument
. Tidal.ghci is found at the root of the repository, and is responsible for bootstraping Tidal. See Configure section for more on how to customize Tidal bootstraping process. Any extra arguments when running
will be delegated to


These are some of the commands that can be run from Vim command line:

  • :TidalSend
    : Send a
    of lines. If no range is provided the current line is sent.
  • :TidalSend1 {text}
    : Send a single line of text specified on the command line.
  • :TidalConfig
    : Configure tmux socket name and target pane
  • :TidalSilence [num]
    : Silence stream number
    by sending
  • :TidalPlay [num]
    : Send first ocurrence of stream number
    ] from the current cursor position.
  • :TidalHush
    : Silences all streams by sending
  • :TidalGenerateCompletions {path}
    : Generate dictionary for Dirt-Samples completion (path is optional)

Default bindings

Using one of these key bindings you can send lines to Tidal:

  •  (Control+E), 
    : Send current inner paragraph.
  • s
    : Send current line or current visually selected block.

 can be called on either Normal, Visual, Select or Insert mode, so it is
probably easier to type than 

There are other bindings to control Tidal like:

  • s[num]
    : Call
    :TidalPlay [num]
  • [num]
    : Call
    :TidalSilence [num]
  • h
    : Call 



 key is a special key used to perform commands with a sequence of
keys.  The 
 key behaves as the 
 key, but is local to
a buffer.  In particular, the above bindings only work in buffers with the
"tidal" file type set, e.g. files whose file type is 

By default, there is no

 set.  To define one, e.g. for use with
a comma (
), write this on your
let maplocalleader=","

Reload your configuration (or restart Vim), and after typing

on a few lines of code, you should see those being copied onto the Tidal interpreter on the lower pane.


Default bindings

By default, there are two normal keybindings and one for visual blocks using your

 key.  If you don't have one defined, set it on your
script with
let maplocalleader=","
, for example.

If you don't like some of the bindings or want to change them, add this line to disable them:

let g:tidal_no_mappings = 1

See section Mappings on ftplugin/tidal.vim and copy the bindings you like to your

file and modify them.

tmux target

You can configure tmux socket name and target pane by typing

. This will prompt you first for the socket name, then for the target pane.

About the target pane:

  • ":"
    means current window, current pane (a reasonable default)
  • ":i"
    means the ith window, current pane
  • ":i.j"
    means the ith window, jth pane
  • "h:i.j"
    means the tmux session where h is the session identifier (either session name or number), the ith window and the jth pane

When you exit Vim you will lose that configuration. To make this permanent, set

on your
. For example, suppose you want to run Tidal on a tmux session named
, and the GHCi interpreter will be running on the window 1 and pane 0. In that case you would need to add this line:
let g:tidal_default_config = {"socket_name": "default", "target_pane": "omg:1.0"}

NeoVim Terminal target

If you are using NeoVim, you can ditch tmux and use the terminal. Add the following line on your configuration file:

let g:tidal_target = "terminal"

Open a file with a

suffix, write and send a line of code to tidal, and the tidal terminal will open in a window below your editor.

Use standard vim window navigation controls to focus the terminal (ie


Quick overview of the terminal:

  1. The terminal defaults to insert mode.
  2. Enter terminal insert mode using eg.
  3. Exit terminal insert mode with
  4. You'll probably want to apply the
     mappings mentioned in 
    :help terminal


When sending a paragraph or a single line, vim-tidal will "flash" the selection for some milliseconds. By default duration is set to 150ms, but you can modify it by setting the


For customizing the startup script for defining helper functions, see below.


is just an example script. You can copy and customize it as much as you want. See
man tmux
if you want to know more about its options.

For example, if you want to split horizontally instead of vertically, change the

option in the
- split-window -v -t $SESSION   \; \
+ split-window -h -t $SESSION   \; \

Both scripts have some options that you can specify as environment variables. For example:

TIDAL_TEMPO_IP= SESSION=whatever tidalvim

This would start Tidal synced to another Tidal on, and it would try to attach or create a tmux sesssion called


The following is a list of all variables that can be changed:

  • FILE
    : File name to open with Vim (default:
    $(date +%F).tidal
    , e.g.
    ). The
    extension is important (you can run
    :setfiletype haskell.tidal
    in case you won't use a .tidal file here).
    : tmux session name (default:
    : Tidal Bootstrap file, a .ghci file (default:
    : Tells Tidal to sync tempo with another Tidal instance on the specified IP (default:
    , i.e. use local)
  • VIM
    : Vim command (default:
  • GHCI
    : GHCi command (default:
  • TMUX
    : tmux command (default:

Customizing Tidal startup

In case you have defined some helper functions, and/or you want to import other modules into Tidal, you can edit the

found at the root of the repository.

However doing this could eventually cause conflicts when trying to upgrade vim-tidal, so instead I recommend that you define a different

file that first loads
and includes all your custom definitions.

Here is an example. Suppose you define a

file on your home directory like this:
--file: ~/myStuff.ghci

-- Bootstrap Tidal -- Replace this path if you have vim-tidal installed elsewhere :script ~/.vim/bundle/vim-tidal/Tidal.ghci

:{ let foo = every 4 $ within (0.75, 1) (density 4) bar = n "<0 1 2 4>" :}

Then, you would run

pointing to your new script file:
TIDAL_BOOT_PATH=~/myStuff.ghci tidalvim

Please note that this a

script, not a Haskell module. So multiline definitions need to be wrapped around
, as shown in the example above.


Here is a list of common problems.

I press

 but it moves the screen down by one line, and nothing else happens


 is used to move the screen forward by one line, but vim-tidal remaps
this to sending current paragraph. If this is happening you either:

  1. Opened a file without
    extension, or changed file type accidentally. Solution: Reopen Vim or set filetype for current buffer with
  2. Have
    setting on your
    . This disables all mappings. Solution: Remove
     binding, or rebind to something else.

It could also be that you do not have

filetype plugin on
setting in your .vimrc. Make sure you have that setting defined.

I press

 and nothing else happens

This means that vim-tidal is sending text to tmux, but to the wrong session/window/pane. Solution: Check that you have configure the socket name and target pane correctly. See the Configure section above for more information.

If you have any question or something does not work as expected, there are many channels you can go to:


Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


Refer to the LICENSE file

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.