Search this site





keynav - retire your mouse.

What is keynav?

Another episode in the revolution against mouse-requisite interfaces. It's one more step towards impulse-driven computing.

Enough marketing jargon. keynav is a piece of an on-going experiment to make pointer-driven interfaces easier and faster for users to operate. It lets you move the pointer quickly to most points on the screen with only a few key strokes.

Note that I said pointer, not mouse. The mouse simply drives the pointer. We can drive the pointer with other devices too. keynav turns your keyboard into an fast pointer mover.

What does it do?

You select a piece of the screen. The screen is initially wholely selected. One move will cut that region by half. A move is a direction: up, down, left, and right.

Once you're done moving, you simply indicate (with a key stroke) that you want to move. Boom, cursor moves.

Why it is fast?

keynav is geared towards selecting a piece of the screen very quickly.

Recall from above that you are selecting a region by cutting the previous region by half. This gives us logarithmic scaling. High resolution screens incur about the same number of moves to select an area as smaller screens do.

For example, to select any pixel on a screen with resolution 1920x1200 it would take 21 moves. 21 moves is horrible. There is a bright side!

How often do you really want to click on a single specific pixel on your screen using your mouse? Never, right? Well, maybe almost never. Most of the time you want to:
  • Raise a window and give it focus: 80x80 pixel target (worst: 9 moves)
  • Click on an "OK" button: 60x25 pixels (worst: 11 moves)
  • Click on a text widget to activate it: 80x25 or larger

Watch the demo!

Bored of reading? How about a screencast demonstration? Click here or the image below.
Hopefully the demo gives you a good idea of what keynav does.

Mailing list

The keynav users mailing list is: [email protected]

I'll be announcing new versions on this mailing list. Additionally, if you want help or want to contribute patches to keynav, the mailing list is a good place to go.

Supported Platforms

keynav is currently written in C and only works in X11 (Unix graphics environment). I am planning on porting keynav to both Windows and OS X. If you are interested in helping me with this, please contact me! Known working:
  • FreeBSD + Xorg 6.9.0
  • FreeBSD + Xorg 7.2.0
  • Ubuntu Dapper + Xorg 7.0.0
  • Ubuntu Feisty + Xorg 7.2.0
  • Ubuntu Hardy + Xorg 7.2.0
  • Cygwin + Xorg 6.8.x
  • Fedora 9
I've seen strong interest in this software working on other platforms, so I'm doing the best I can. Again, if you're a .NET (or just Windows) or OS X coder, and are willing to help port this, let me know. It's only 200 lines of C in Xlib, so it can't be more than a one-day-long project.

Download it!


Looking for an older version? Try the keynav releases archive


  • glib >= 2.0
  • libxdo (from xdotool) (or, if you build static, libX11 libXtst and libXext)
  • Xinerama (comes with xorg)
  • XSHAPE (comes with xorg)

Build instructions

make keynav

The above should be all you need to do. Keynav comes with xdotool (required library) and will build static if is not found on your system.

  • Debian users can install this package via apt-get install keynav
  • FreeBSD users can install this from ports in x11/keynav

How to use it

Run keynav, and activate it by pressing Control+Semicolon. You should see a thin frame on the screen with a cross in it.

The following is the default configuration:
  • h : select the left half of the region
  • j : select the bottom half of the region
  • k : select the top half of the region
  • l : select the right half of the region
  • shift+h : move the region left
  • shift+j : move the region down
  • shift+k : move the region top
  • shift+l : move the region right
  • semicolon : Move the mouse to the center of the selected region
  • spacebar : Move the mouse and left-click
  • escape : Cancel the move

Configuration file

Your config file must live in ~/.keynavrc. Such as /home/jls/.keynavrc

The config file format consists of a keysequence followed by a comma-separated list of commands. For example:
space warp,click 1,end
This would move the mouse, click left mouse button, and finish (close the keynav selector) when you hit spacebar while keynav was active. A sample config file comes with the distribution as 'keynavrc'.

The following is a list of key modifiers: shift, ctrl, alt, or any valid X Keysym, such as Shift_L, etc.

List of commands:
Activate keynav
Deactivate keynav
cut-left, cut-right, cut-up, and cut-down
Cut half of the selection in a given direction. For example, cut-left will select the left half of keynav selector region. If you attempt to cut the window too small, the operation will abort. Cut can take a percentage value to cut by. The default is ".5"
move-left, move-right, move-up, move-down
Move the selector window a given direction. The movement amount is equal to the width or height of the selector depending on the direction. You cannot move the window outside the bounds of the screen. Move can take percentage value that specifies the distance relative to the size of the window. The default is "1.0"
Move the mouse to the center of the selector
click <button>
Click the given mouse button once. 1 == left, 2 == middle, 3 == right.
doubleclick <button>
Click the mouse button twice, quickly. This can also be achieved by doing "click 1,click 1" in your command sequence.
drag <button> [keyseq]
Toggle dragging mode for the given button. If keyseq is given then that keysequence is held during the initial mouse button down event. This is useful in invocations such as 'drag 1 alt' to do a alt+click-drag on a window to move it.
grid <rows>x<columns> [Added 20080509]
Change the grid layout of the selection. For example, specifying 'grid 3x3' will divde the screen selection into 9 cells, 3 rows and 3 columns. Specifying 'grid 2x3' will divide the screen selection into 6 cells, 2 rows and 3 columns.
cell-select <row>x<column> OR cell-select <cell> [Added 20080509]
Select a specific cell in the grid. The NxM syntax selects the specific row and column. The single number syntax selects the cell numbered counting from the top left to the bottom left. For example, a 3x3 grid would be numbered this way:
1 2 3
4 5 6
7 8 9
grid-nav <on or off>
Activates grid navigation. This is also describable as 'battleship navigation' if you are familiar with that classic game. This will make all cells visibly labeled by a two letters which are used as coordinates to type. For example, 'grid 5x5,grid-nav on' will give you a 5x5 grid with grid nav enabled, making all cells labeled starting AA, AB, AC ... AE, BA, BB ... EE.
sh <command>
Execute a command. This is run as /bin/sh -c <command >. For example:
run xterm,end
This will start an xterm and end keynav selection. This allows you to use keynav as a general-purpose key-binding tool.
Go back one step in the movement history. Keynav keeps track of your keynav activity and this command allows you to step backwards. For example, if you cut-right, move-left, cut-up, then invoke history-back 3 times, your movements/cuts will be undone, in order.
Tell keynav to exit
record [filename]
Record activities and save it to a register. This is very similar to vim's 'q' command which lets you record things.

Optional argument is a filename to save the recordings to for persistence across keynav runs. A single file will hold multiple recordings.

Example in keynavrc to bind 'q' to record to ~/.keynav_macros: q record ~/.keynav_macros

Works similar to vim recording.

  1. Hit record once
  2. Type the key you want to record to
  3. Do things in keynav you want recorded.
  4. Any 'end' operation or hitting record again will terminate and save this recording.
Recordings only persist if you specify a file to save to, otherwise they are lost across keynav restarts.
Makes the keynav window the same size and position as the current active application window.
cursorzoom <width> <height>
Centers the keynav window on the cursor with the given size.