Introduction

floo is a terminal user interface (TUI) to automate workspace setup and access.

If you have a very terminal-centric workflow, you oftentimes have to perform a set of repetitive tasks each time you fire up your machine, before you can start being productive. For me this looks something like the following:

1. cd into the root directory of your project
2. start a tmux session with multiple windows
3. source workspace specific environment configurations (e.g. virtualenv, or just env stuff) in each window
4. run your favorite editor in one window
5. open a webbrowser with some documentation or github issues you are browsing
6. start actually working on your stuff

floo relieves you of all this manual overhead just to jump into a project. Inspired by the floo network from the Harry Potter universe, you can dynamically add or remove fireplaces (project/workspace configurations) to it. Setting up a new fireplace is as easy as pressing n in the TUI and entering a name and root directory of your workspace. You only have to set up a fireplace once, floo will remember it for you afterwards. Once a fireplace is set up, you can simply run floo, select the desired fireplace in the TUI and your shell will be brought into the configured state. For me that typically is a new tmux session, with two windows and all environment configurations sourced and some small project specific adjustments. Configuring the concrete actions you want to have performed is as easy as placing a shell script named .floo into the corresponding project directory. floo will make sure the shell sources this script before passing control back to you, such that all modifications you have defined in your script are applied. floo assists you in setting up these scripts for your fireplaces by providing you with templates that you can modify and apply with ease. You may even add your own templates aligning with your concrete needs, to streamline setting up new fireplaces with your specific workflow.

A first look

Basic usage example of floo, we create a new fireplace which we then use to quicktravel into that directory, any .env or .envrc files of that directory are sources as well.

More advanced usage example, we use a predefined template to define custom floo actions, to let floo know to start a tmux session with two windows when travelling to the fireplace.

For convenience, floo allows you to also track notes for each fireplace, this supports markdown and can help you track where you left off or whatever else you want to remember.

License

Copyright (C) 2026 Leon Degel-Koehn

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Installation

Prerequisites

Currently the preferred way of installing floo is through cargo by running

cargo install floo

Note: We are planning to release to other package managers in the future once floo becomes more stable.

Or alternatively, you may choose to build from source:

git clone 'https://github.com/keyvizsla/floo.git'
cd floo
cargo install --path .

Afterwards, you can verify that this first installation step was successful by verifying that the following prints floo x.x.x, depending on the current version:

floo-bin --version

You are now ready to initialize your shell environment to integrate with floo. Please follow the instructions listed below for the shell that you are using to finish your setup.

Bash

Run the following command:

echo 'eval "$(floo-bin init)"' >> ~/.bashrc

And restart your terminal.

Zsh

Run the following command:

echo 'eval "$(floo-bin init)"' >> ~/.zshrc

And restart your terminal.

Nushell

Run the following command:

floo-bin init --shell nu | save $nu.config-path --append

And restart your terminal.

Note: floo was initially developed with bash in mind. Due to the fundamentally different paradigms of nushell, we havent been able to port its full functionality to this shell, yet. In nushell, you cannot create custom .floo scripts to define custom actions to take when travelling to a fireplace. In nushell, floo will always perform the default action of bringing you into the selected fireplace’s project directory and sourcing any .env/.envrc files in that directory.

Other Shells

If your favorite shell is missing from this list, we are sorry to let you know that floo does not yet support it. Please raise an issue on the GitHub repository so that we know which shell you would like to use floo in and we will try and accomodate you.

Quickstart

Having installed floo on your system, you are now ready to build your floo network. In floo you are able to define fireplaces. Fireplaces equate to projects or workspaces to which you want to be able to travel to and from quickly, with optional additional configurations about what state you want your shell to be brought to once you reach your destination.

Basic setup

When you first run floo in your terminal, you should see this screen:

As prompted, you can now get started setting up your first fireplace by pressing one of n or %. Most of the keybinds in floo should feel natural to you if you have been working with other TUI applications, you are however always welcome to provide alternative suggestions as an issue.

Using tab or your arrow keys, navigate through the dialog, filling in the blanks, to create your first fireplace. For the path to the fireplace, you should put the path to the root directory of your project, for example for projects using git this would be the directory containing the .git directory. For your convenience, floo supports relative paths to where it is currently being executed, that means if you ran floo from the root of the directory in which you want to have a fireplace, you can just put . as path to fireplace. On future executions, floo will correctly resolve the path regardless of which directory you call floo from. Alternatively, if you already are in the directory where you want to create a fireplace, you can also run floo create which will start floo with a prefilled fireplace creation dialog, so you don’t have to manually insert your path.

You have now successfully created your first fireplace and are all set to travel.

Defining custom actions

You can define the specific actions that floo should take to transport you to a selected fireplace, by placing a .floo file in the corresponding directory of that fireplace. This script should be a script that your shell can source, upon which it will then be in the state that floo will later also bring the shell into. If floo cannot find such a script, it will perform its default actions, which correspond to

cd <fireplace directory>
source .env # or .envrc whichever is available

For a gentle introduction, you can for example take a cargo project of yours and place a .floo script at its root that contains the following:

cd $FLOO_DIR
alias run='cargo run'

If you now set up a fireplace in floo for this project and select it, your terminal should now be in that projects root directory and you should be able to call run instead of having to type out cargo run. This is of course just a small example of what one could do, the possibilities are limitless.

You may have noticed that we accessed the FLOO_DIR variable in this script. floo exposes certain details about the fireplace you are traveling to via environment variables (more on which variables are available in the templating section of these docs). In this way, you can avoid hard-coding things into your scripts. This also facilitates the re-usability of such scripts. If you were to want the same alias available for other cargo projects, you could just place the exact same .floo script in those directories and it would work out of the box due to this injection of environment variables. When you are at this point that you have found a common workflow that you want in multiple projects, you might want to consider turning this into a template, which allows floo to take care of inserting the .floo file for you. Check out the templating section for that.

Troubleshooting

We will keep updating this section with common issues users run into and their fixes. Please help us in improving this documentation by raising an issue where you describe your troubles. If you were able to resolve your troubles, even if you think no one else would make that mistake, we always appreciate PRs updating this troubleshooting guide.

Keybindings

This page explains how you move around in floo.

Working with templates

Templates allow you to re-use .floo configurations for different workspaces. Going back to the running example of a terminal-based tmux workflow, regardless whether or not you want to work on a python project, a rust project, a latex project or whatever it may be, you would likely want a similar setup each time: Create a named tmux session that has a certain number of open windows, where each window starts running a certain process automatically. A template for this sort of workflow comes pre-packaged with floo. Floo will tell you, when a fireplace has no .floo configuration, yet. By pressing e in the info view, you can select from the list of templates installed on your system to get started from. Once you have selected a template, floo will open your systems $EDITOR, where you can then tweak the exact contents of the template for the fireplace you are setting up.

An example usage of the default tmux template

Creating new templates

Creating a new template happens in two steps:

1. Write and test the .floo script
2. Declare the script as a template

The first step we have outlined in the quickstart section of this guide. For the second step you simply run

floo template [path] [name]

where the path is the filepath of the .floo script you want to turn into a template and the name is the name under which floo will list your new template in all future template selection screens.

Using floo variables

To keep templates generic, you can make use of specific environment variables, which floo guarantees to you to be set every time before a .floo script is executed. This applies to the following variables:

Check out the default tmux template to see how to use these in practice.

Command-line interface

floo is mainly intended to be used as a TUI, but comes with a small set of cli commands:

Contributing to Floo

Hey there, thanks four your interest in becoming involved with the development of floo. We will help you with any technical issues and help you improve your contribution if at all necessary.

How to Contribute

For now, we operate on a system of mutual trust and good judgment. Please open issues with bugs you have found or features you feel are missing from the application. Just make sure to provide some context on how we would be able to reproduce the bug. If you find something that you know how to fix or you proactively implemented a feature you were missing, please go ahead and submit a PR!

You can contribute in many different ways. You can either open an issue on GitHub describing a bug you have encountered or a feature that floo is missing to suit your needs. We don’t expect you to be an expert, so don’t worry if you are unsure or don’t know how to actually implement the feature you are describing, we can figure things out together.

Contributing Code to floo

Code contributions should be straightforward to you if you have done this kind of thing before. If you don’t yet quite know where to start, here is a good guide on how you can forward your code to us: GitHub guide

When opening a pull-request, please make sure that you either link to an existing issue or provide an adequate description of what feature your pull-request implements, what issue it solves and which parts you would like further guidance on, should you need any.

Testing

Please make sure that you add tests for new features that you have implemented or a regression test for the bug that you have fixed. floo uses 3 types of tests to verify its correct behavior:

Unit tests: These are fairly straightforward, written in the rust source files themselves and you should add them if your code touches some standalone function that doesn’t directly depend on the TUI itself.

Snapshot tests: These act to ensure that there are no unexpected changes to the TUI. The ratatui docs provide a nice introduction to these types of tests. To see an example of how these tests are implemented in floo you can take inspiration from the start_screen component.

To run the current suite of unit/snapshot tests you can use the following command from the root of the floo repository:

docker run --rm -v $(pwd):/app ghcr.io/keyvizsla/floo-linux:latest

Integration / E2E tests: These check that the full chain from the user perspective of spinning up floo and being transportet into the correct shell state does indeed work. You generally won’t have to write or alter these kinds of tests. Adding new tests to this domain is only necessary for major changes like adding support for a new shell type. We will let you know should your changes prompt the creation of such a test and assist you in writing those tests, should you need any help.

To run the end-to-end tests use the following command:

docker run --rm -v $(pwd):/app ghcr.io/keyvizsla/floo-linux:latest bash -c " \
  cargo install --path .; \
  python tests/e2e_test_base.py;
"