Kobo Tweaks

A beginner-friendly addon for customizing Kobo eReaders.

🔥 1. Features

• Customize various UI elements and features of Kobo eReaders (similar to KoboPatch, can be used with patched firmware)
  • Reduces header and footer's heights
• Add Battery and Clock widgets while reading a book (similar to NickelClock)
• Customize bookmark image
• More to come...

Difference from KoboPatch:

• Beginner-friendly, "patches" can be customized without reinstalling firmware (just edit and reboot)
• No need to wait for patch updates when a new firmware is released (most of the time)
• Downside: not all patches can be implemented, and it requires more work to add a new tweak

Difference from NickekClock:

• Uses its own widgets for clock & battery instead of Kobo's built-in ones (reduce the likelihood of encountering unwanted bugs)
• Clock & battery only update after a page turn
• Supports Dark mode
• Downside: it conflicts with NickelClock. You can uninstall NickelClock manually, or let Kobo Tweaks handle the uninstallation automatically.

Changes: Reduced header and footer's heights Clock and Battery widgets Custom bookmark image	Settings used: [Reading] BookmarkImage=bongo_cat.png HeaderFooterHeightScale=60 HeaderFooterMargins=50   [Reading.Widget] BatteryShowWhenBelow=100 BatteryStyle=Icon BatteryStyleCharging=LevelIcon Clock24hFormat=true FooterLeft= FooterRight=Battery HeaderLeft=Clock HeaderRight=

🛠️ 2. Installation

Kobo Tweaks should be compatible with any Kobo eReader running a recent 4.x firmware.

Follow these steps to install Kobo Tweaks:

1. Connect your Kobo eReader to your computer
2. Download the latest KoboRoot.tgz file and place it inside the hidden .kobo folder on your Kobo eReader

.kobo/
├─ KoboRoot.tgz

• The file name must be KoboRoot.tgz (don't unzip it)
• If you're using macOS and don't see the .kobo folder in Finder, press the combination Cmd + Shift + .

3. Eject the device safely to avoid data corruption

After it installs and reboots, open a book and you'll see new Clock and Battery widgets on the header. To customize Kobo Tweaks, check the Customization section below.

Important

Since Kobo Tweaks cannot be used with NickelClock, it automatically detects and uninstalls NickelClock for you. If this dialog appears when opening a book and the layout is broken, restart the device once again before continuing. If it doesn't work, try to uninstall NickelClock manually.

There are a few new files and folders in your Kobo eRreader:

.adds/
├─ tweaks/
│  ├─ images/
│  ├─ DELETE_TO_UNINSTALL.txt
│  ├─ settings.ini

Important

If these files appear in your library, see the Troubleshooting section for the fix.

🗑️ Uninstallation

To uninstall Kobo Tweaks, delete the DELETE_TO_UNINSTALL.txt file and restart the device. The file also contains the currently installed Kobo Tweaks version. Please include that information when reporting a bug.

💃 3. Customization

Settings can be customized by editing the .adds/tweaks/settings.ini file on your Kobo eReader.

[Reading]

Applies after reopening the book

Setting and description	Values
BookmarkImage --- Custom bookmark image file name, including extension, located in the .adds/tweaks/images 🐞 Known bug: it only works when reading Kepub books at the moment (see #20)	String
HeaderFooterHeightScale --- Percentage-based scaling factor applied to the original header and footer height. For example, a value of 66 means the header and footer are rendered at 66 percent of their original height.	Unit: % Range: 50-100 Default: 100
HeaderFooterMargins --- Sets the left and right margins for both header and footer	Range: 0-100 Default: 50

🐶👂 Bookmark image

• There are bookmark templates and images in resources/bookmarks/
• Bookmark image must be in PNG format with a transparent background
• If an additional image exists with the same base name and the _dark suffix, that image is used when Dark mode is active

  For example, if BookmarkImage=bongo_cat.png, then bongo_cat_dark.png will be used in Dark mode, if it exists

  .adds/
  ├─ tweaks/
  │  ├─ images/
  │  │  ├─ bongo_cat.png
  │  │  ├─ bongo_cat_dark.png

• There are no restrictions on the dimension, but it's recommended to use dimensions similar to the original. Below are the dimensions of Kobo's default bookmark image.

Note

This info needs to be verified

Device/Dimensions	57x54	64x61	102x97	116x110	133x126
Mini Touch 2.0	x
Aura, Aura Edition 2 Glo Nia		x
Aura H2O, Aura HD Clara 2E, Clara BW, Clara Colour, Clara HD Glo HD			x
Libra 2, Libra Colour, Libra H2O				x
Aura One Elipsa, Elipsa 2E Forma Sage					x

[Reading.Widget]

Applies after reopening the book

Setting and description	Values (case-insensitive)
HeaderLeft, HeaderRight, FooterLeft, FooterRight --- Defines the widget position and type	Battery, Clock or leave it blank to show nothing
BatteryStyle, BatteryStyleCharging --- Specifies the battery style for normal and charging states	IconLevel, LevelIcon, Icon, Level
BatteryShowWhenBelow --- Shows the battery widget only when the battery level is less than or equal to this value	Unit: % Range: 10-100 Default: 100 (always visible)
Clock24hFormat --- Enables or disables 24-hour time format	true, false, on, off

• All widgets support Dark mode
• The Battery widget updates only when you turn a page or unlock the device.
• The Clock widget updates when you turn a page, when the device is unlocked, and every two minutes after the last update.
• ⚠️ If you place a widget in the HeaderRight position, you may see a visual glitch when opening a book if the first page is already bookmarked. Turn the page forward and back to fix it.

👩‍🔧 4. Troubleshooting

1. Kobo Tweaks' files appear in my library

You need to edit Kobo's setting file to prevent it from scanning hidden folders.

1. Connect your Kobo eReader to your computer
2. Open the .kobo/Kobo/Kobo eReader.conf file with a text editor
3. In the [FeatureSettings] section, replace the line that starts with ExcludeSyncFolders= with the following (insert it if not found):

ExcludeSyncFolders=(\\.(?!kobo|adobe).+|([^.][^/]*/)+\\..+)

4. Save and eject the device safely
5. Restart the device

🧑‍💻 5. Development

To build Kobo Tweaks: install Docker, then run the build.sh file

🤝 6. Acknowledgements

• Thanks to @pgaskin and @shermp for reviewing and improving the code
• Thanks to the shermp/NickelClock project for giving me the idea of how to add widgets to the Reading view.
• And thank you for using!

✨ 7. Other Kobo addons from me

Nickel Screensaver is an addon that brings the transparent screensaver feature to Kobo eReaders, similar to the one on KOReader.

Transparent overlay + book screenshot	Transparent overlay + book cover	Transparent overlay + wallpaper