Tool Tray

System tray app to manage and update Python tools from private GitHub repos via uv.

Quick Start

For Users

Install:
```
uv tool install tool-tray
```
Run the tray:
```
tooltray
```
On first run, setup dialog opens automatically - paste your config code

For Admins

Generate a config code to share with your team:

tooltray encode --token ghp_xxx --repo myorg/myapp
# Output: TB-eyJ0b2tlbi...

Each repo must have a tooltray.toml manifest (see below).

Commands

Command	Description
`tooltray`	Run tray app
`tooltray setup`	Configure via CLI (paste config code)
`tooltray reset`	Remove config and start fresh
`tooltray init`	Create `tooltray.toml` template in current dir
`tooltray encode`	Generate config code for sharing
`tooltray autostart`	Manage system startup
`tooltray logs`	View log file
`tooltray cleanup`	Remove orphaned desktop icons
`tooltray --help`	Show help
`tooltray --version`	Show version

Encode Options

tooltray encode --token TOKEN --repo ORG/REPO [--repo ...] [--prefix PREFIX]

Examples:

# Single repo (default TB- prefix)
tooltray encode --token ghp_xxx --repo myorg/myapp

# Multiple repos
tooltray encode --token ghp_xxx \
  --repo acme/cli \
  --repo acme/api

# Custom prefix for branding
tooltray encode --prefix ACME --token ghp_xxx --repo acme/cli

Autostart

tooltray autostart --enable   # Add to system startup
tooltray autostart --disable  # Remove from startup
tooltray autostart --status   # Check if enabled

Logs

tooltray logs           # Show last 50 lines
tooltray logs -f        # Tail in real-time
tooltray logs --path    # Print log file path

Cleanup

Remove orphaned desktop icons (icons for tools no longer in config):

tooltray cleanup --dry-run  # Show what would be removed
tooltray cleanup            # Prompt and remove
tooltray cleanup --force    # Remove without prompting

When not configured:

Item	Description
`[!] Not configured`	Status indicator
Setup...	Open setup dialog
Quit	Exit the app

When configured:

Item	Description
`> myapp 1.0.0`	Click to launch
`> myapp 1.0.0 -> 1.1.0 *`	Update available, click to launch
`myapp (not installed)`	Not yet installed
Orphaned Icons	Shows icons needing cleanup (if any)
Clean Up (n)	Remove orphaned icons
Update All	Install/update all tools
Check for Updates	Refresh version info
Configure...	Open setup dialog to reconfigure
Quit	Exit the app

Project Manifest (`tooltray.toml`)

Each managed repo must have a tooltray.toml in its root:

name = "databridge"           # Display name (required)
type = "uv"                   # uv | git (required)
launch = "databridge"         # Command to launch (optional)
build = "npm install"         # Build command for git type (optional)
desktop_icon = true           # Create desktop shortcut (default: false)
icon = "assets/icon.png"      # Path to icon in repo (optional)
autostart = false             # Add to system autostart (default: false)

Repos without tooltray.toml are skipped.

Config Code Format

The config code is a prefix + base64-encoded JSON:

TB-eyJ0b2tlbiI6ImdocF94eHgiLCJyZXBvcyI6WyJteW9yZy9teWFwcCJdfQ==

Decodes to:

{
  "token": "ghp_xxx",
  "repos": ["myorg/myapp"]
}

Config is stored at:

Windows: %LOCALAPPDATA%\tooltray\config.json
macOS: ~/Library/Application Support/tooltray/config.json
Linux: ~/.config/tooltray/config.json

Requirements

Python 3.12+
uv

Development

# Run directly
uv run tooltray

# Test encode command
uv run tooltray encode --token test123 --repo myorg/myapp

# Type check
uv run basedpyright src/

License

MIT

Metadata

Release files for tool-tray 0.3.19

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tool-tray 0.3.19
File	Size	Uploaded
tool_tray-0.3.19.tar.gz	16.8 kB	Jan 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for tool-tray 0.3.19
File	Interpreter	ABI	Platform	Reset
tool_tray-0.3.19-py3-none-any.whl 23.6 kB Jan 23, 2026	Python 3	none	any	Details

Total release size: 40.3 kB

Release files / tool_tray-0.3.19.tar.gz

Download URL	tool_tray-0.3.19.tar.gz
Size	16.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`04bcafab0118b466c5a7a6b80dec522205885dae61196aa4a013a0b677847b41`
BLAKE2b-256 checksum How to use checksums	`687f54b29b1a039cbd5ca4440494cc56a7fd8b4ce490fb1785690ec8cedd17b0`
Upload date	Jan 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"EndeavourOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / tool_tray-0.3.19-py3-none-any.whl

Download URL	tool_tray-0.3.19-py3-none-any.whl
Size	23.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`df60a9faa40734dbe2ef6b143b0317e96631e5ab4e808c4ca4e3d57818b89310`
BLAKE2b-256 checksum How to use checksums	`54319f4fdf61be278951649fb8edaae8f01f70470a0bedf98b3cbfc1bc664949`
Upload date	Jan 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"EndeavourOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`