Ditto is a system-wide ASCII keyboard visualizer that captures global key presses. Even if you're outside the terminal session, the visualizer will still keep updating. Hit the repo with a star if you like this little interactive eye candy app! ⭐

60%	65%

75%	80%

96%	100%

• Motivation
• Installation
• Permissions
• Usage
  • Lists
  • Custom Layouts
• Roadmap
• Contributing
• Acknowledgments
• Note on AI
• License

If you've seen rices over at places like r/unixp*rn, every now and then you'll see some developer layouts where you'd have a code editor, then some eye candy to fill up dead space. I thought it would be nice to have some eye candy that was interactive.

And so, I thought a keyboard visualizer that updates no matter which window has focus would be pretty neat. You code away on your editor, and the ASCII keyboard on the corner lights up!

Practically, it could have a niche use as well, like sharing your screen with other people so you can flex your Vim skills they can see the keys you press as you navigate through your workflow.

For now, this program is only installed through Go. So make sure you have Go installed first:

# Check if Go is installed
go version

# If not, install it from https://go.dev/dl/
# or via your package manager, e.g.:

# sudo pacman -S go            (Arch)
# sudo apt install golang-go   (Debian/Ubuntu)

Once you have Go installed, you can install it directly, or clone if you'd like to mess around with it:

# Install directly
go install github.com/arvingarciabtw/ditto/cmd/ditto@latest

# Or clone and build
git clone https://github.com/arvingarciabtw/ditto.git
cd ditto
go build -o ditto ./cmd/ditto/

Before executing the program with ditto, refer to the permissions section below. You can also specify flags when executing ditto, particularly for locking the keyboard. See the usage section for more details on that.

There are four commands you need to be aware of: l, s, d, and c. Pressing l opens up the layout list, s opens up the size list, and d opens up the standard list. If your active standard is either JIS or KS, you can press c to toggle between the Latin alphabet and the standard's logograms.

If you wish, you can add your own key maps for your custom layouts!

Custom layouts are loaded from JSON files placed in ~/.config/ditto/layouts/.

Each .json file becomes a named layout (the filename without extension). Format:

{
  "map": {
    "A": "A",
    "S": "O",
    "D": "E",
    "F": "U",
    "G": "I",
    "H": "D",
    "J": "H",
    "K": "T",
    "L": "N",
    "Q": "'",
    "W": ",",
    "E": ".",
    // ...
  },
  "shift": {
    "1": "!",
    "2": "@", // ...
  },
}

• map is required — maps physical key labels → remapped labels (same format as the built-in layouts in layouts.go)
• shift is optional — shifted state mappings; falls back to US QWERTY shift if omitted

The layout will automatically appear in the layout list the next time you launch Ditto.

If you're happy with the current layout and want to keep that permanently every time you run the program, you can lock the keyboard with ditto --lock. Locking it means that your visual settings will not work. Bindings for opening up a list, toggling the TUI text with h, or toggling the logograms with c will intentionally not work.

Inversely, you can just do ditto --unlock to unlock the keyboard.

If you prefer, you can also just edit the config file at ~/.config/ditto/config.json to change the value of the locked key.

Some features I'm thinking of implementing in the future, not in order.

• UK layouts
• ANSI and ISO standards
• Additional niche standards (JIS, ABNT, KS)
• Windows support
• Mac support
• Custom layouts via TUI
• Custom finger zones

I'm certainly not much of an experienced programmer, so any contributions you make are greatly appreciated.

As I kept developing this program, I've learned that keyboards actually get pretty deep. For instance, check out this list of QWERTY keyboard language variants. If you'd like to add a specific layout variant to the layout list, I'd appreciate a pull request or opening up an issue about it.

A simple workflow:

1. Fork the project
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add super amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a pull request

When writing my commit messages, I follow the Conventional Commits spec, so I'd be glad if you followed this convention as well for your contributions for the sake of consistency.

If you're liking Ditto, I'd appreciate a star! Thanks again! ⭐

Here is a list of useful resources that I always refer to when developing:

• effective go
• bubble tea docs
• lipgloss docs
• evdev docs
• input interfaces
• setcap
• standards reference

I'm not an experienced programmer and I've only recently picked up Go, so I'm well aware that the codebase is subpar. I still don't have an eye for what is considered idiomatic Go or not.

I've used AI to assist me with making this project, notably for pointing me towards reliable resources like documentation and for easily doing tedious, repetitive tasks (especially so for when I was adding the key matrices for each keyboard standard's size).

In the cases where I couldn't figure out an implementation despite researching on my own, I did lean into AI for suggestions, and sometimes an initial prototype of an implementation. Rest assured that I did my best in reviewing these suggestions, and making appropriate changes along the way.

Of course, I'm certain the code can still be improved a lot more, so I'd be happy to hear any feedback or suggestions. If you'd like to contribute, you can refer to the Contributing section above.

Distributed under the MIT License. See LICENSE for more information.