(c) 2017 Finn Ellis. Free to use, copy, modify, etc. under the MIT license. See included LICENSE file.
Screenguppy is a little friend to keep you company in your GNU screen session. Specifically, it adds an extra line at the bottom (in the caption field, above the hardline if you have one) with a text-based fish that swims back and forth.
If you're not running screen or don't want to put a fish there, you can also just run it in a bash loop (or use similar logic to add it to your i3 status bar or anywhere else that you can insert script output). See Running Screenguppy Without Screen.
If you'd like to use Screenguppy with tmux, there are partial instructions in an open pull request. If you can improve them, please leave comments!
Contributions of both code and ideas to Screenguppy are welcome. Check out the issue tracker to see what's already planned and suggest other things.
- Installing Screenguppy
- Running Screenguppy Without Screen
- Adding Screenguppy to Screen
- Advanced Customization
- Removing Screenguppy
Install screen, if necessary.
sudo apt-get screen
Clone this repository.
git clone https://github.com/relsqui/screenguppy.git
(You can use the SSH address instead if you have SSH keys configured on Github already.)
Make yourself a bin directory if it doesn't already exist, and then link the Screenguppy executable into it.
mkdir -p ~/bin
ln -s ~/screenguppy/screenguppy ~/bin
(Replace the first path with wherever you cloned screenguppy, if it's not your home directory.)
Make sure that ~/bin
is already in your $PATH
by trying to run:
screenguppy
If it prints a single line with a fish on it, you're golden. If not,
add this line to your ~/.bashrc
file:
export PATH="$PATH:$HOME/bin"
And then re-execute that file:
source .bashrc
Now you should be able to run screenguppy
and see one fish.
If you just want to watch the animated fish without setting it up in your screen caption line (or you already have a caption line, don't use screen, etc.) then you can run the script independently in a bash loop, like so:
while true; do
clear
screenguppy
sleep 1
done
Type ctrl-c
to stop.
Open your ~/.screenrc
file in a text editor. Do a quick search for any
lines that already have the command backtick
in them. If you don't find any
(including if the file is brand new), add these lines to the end of the file:
backtick 1 1 1 screenguppy
caption always '%{yk}%=%1`%='
If there are some backtick lines, find the highest number that appears right
after the word backtick
, then add one to it and note the result. For example,
if you saw backtick 1
and backtick 2
, note 3
.
Add the following lines to the end of the file, substituting your noted number
for N
in both places (once per line).
backtick N 1 1 screenguppy
caption always '%{yk}%=%N`%='
NOTE: If you already have a caption
command in your .screenrc
file,
that line and Screenguppy can't work at the same time. If you're not sure
which one you want to keep, you can comment out the other one temporarily
by adding a # at the beginning of that line.
Finally, if you're already running a screen, refresh the configuration
by typing C-a :
and then source ~/.screenrc
. If you see errors about
the screenguppy command not being found, type C-a :
again and then
setenv PATH "$PATH:$HOME/bin"
.
If you're not running a screen yet, type screen
to start one.
Enjoy your fishy friend!
- The
%{yb}
part of the caption line in.screenrc
defines the fish and background colors. See the String Escapes section of the GNU Screen Manual for other options. - The
fish_options
block near the top of thescreenguppy
executable provides quick access to several configuration choices:- Screenguppy assumes your terminal is at least 80 characters wide and uses no
more of it than that. You can give your fish more or less room to swim by
editing the value for
max_range
. - Screenguppy will try to display Unicode art, and revert to ASCII if it
fails. You can force ASCII output by setting
use_unicode
toFalse
.- You can also change the details of the art by editing the values of
unicode_art
andascii_art
which are initialized in theFish
class. Each one should be an array of two strings showing the right-facing variant and the left-facing variant, respectively.
- You can also change the details of the art by editing the values of
- You can change the fish's speed by changing the value for
speed
. This doesn't change how often it moves (which is capped at once per second by screen itself), but how far it moves each time.- The speed doesn't have to be an integer, but the distance will always be rounded.
- If the speed is less than 1, the fish will sometimes skip its move.
- If the speed is negative, the fish will swim backwards.
- Screenguppy assumes your terminal is at least 80 characters wide and uses no
more of it than that. You can give your fish more or less room to swim by
editing the value for
You can remove Screenguppy from your screen by deleting the two lines you added
to your .screenrc
file. If you have a screen open that you would like to keep
running, refresh its configuration by typing C-a :
and then
source ~/.screenrc
.
You can also delete Screenguppy entirely just by removing the directory it's in and the link you created:
rm -rf ~/screenguppy # or wherever you cloned it
rm ~/bin/screenguppy