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

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

cargo install floo

Afterwards, add the following to your shell’s rc file (.bashrc/.zshrc):

eval "$(floo-bin init)"

And restart your terminal.

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

Building from source

To build from source, the same workflow applies via a local cargo installation flow:

git clone https://github.com/keyvizsla/floo.git
cargo install --path floo
echo 'eval "$(floo-bin init)"' >> ~/.bashrc

Make sure to also restart your terminal for the local installation to take effect.

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.

Because we are in the early stages, we don’t have a rigid, massive contribution guide yet. We are still figuring out the exact workflow, and we want to keep things lightweight and flexible.

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!

The Only “Rule”

All we ask is that your contributions are of acceptable quality to the best of your judgment.

What does that mean?

-> You don’t have to worry about being scrutinized for your code changes, just make sure you don’t introduce trivial compiler warnings and such. If you are unsure whether or not your code meets the standards, go ahead and open that PR, we can always discuss your changes and help you align it to our expectations.

As the project grows, we will refine this guide together. Until then, use your best judgment, have fun, and welcome aboard!