The xxToolbelt is a simple yet powerful system for organizing scripts and tools in various programming and scripting languages entirely written in Bash. It aims to provide a cleaner and more efficient alternative to the traditional giant rc (.bashrc, .zshrc etc.) files that many of us rely on. This tool allows you to manage your custom commands and scripts effortlessly, making your development workflow more streamlined and organized. Remember when you had to write this small script that does X and then you forgot about it? With the xxToolbelt, you can easily manage and share your scripts with others so you won't lose them or forget about them anymore.
xxToolbelt uses symlinks in ~/.local/bin instead of shell aliases, which means your scripts work everywhere — interactive shells, scripts, AI tools (Claude CLI, Copilot, etc.), cron jobs, and any process that uses PATH.
Some of the key features of the xxToolbelt include:
- Works everywhere — not just interactive shells, but AI tools, scripts, cron, etc.
- Zero shell startup overhead — no scanning on every terminal open.
- Support for multiple programming and scripting languages (not limited to bash).
- Easy to extend and customize.
- Mechanism to share snippets with others.
- Adaptability to different shells (bash, zsh, fish, etc.).
- Centralized requirements for all your tools/scripts (e.g., Python requirements.txt).
Check out the demos:
- xxToolbelt
- No dependencies except Bash;
- Works with AI tools (Claude CLI, Copilot, etc.) — not just interactive shells;
- Zero shell startup overhead — scripts are synced once, not on every terminal;
- Can be included in every shell (bash, zsh, fish etc.);
- Support multiple programming and scripting languages (everything, as long as you can create a shebang for it);
- Really easily extendible and customizable;
- You can write and reuse scripts using wide variety of languages;
- Works really well with interpreted languages;
- You can use centralized requirements for all your tools/scripts - ex. Python requirements.txt to save storage;
- Portability - its one file and your scripts folder (optional);
- Easy version control;
- Must maintain a lot of separate files instead of one big rc (might as well be a pro);
- Loading time of compiled languages will be slow and some functionality limited (but still better than the standard way);
In your terminal as the current user type:
cd /tmp; git clone git@github.com:thereisnotime/xxToolbelt.git && mkdir "$HOME/.xxtoolbelt" && mv ./xxToolbelt/* "$HOME/.xxtoolbelt" && echo -ne "# START xxToolbelt\nsource \"$HOME/.xxtoolbelt/xxtoolbelt.sh\"\n# END xxToolbelt" >> "$HOME/.$(ps -p $$ -ocomm=)rc" && source "$HOME/.$(ps -p $$ -ocomm=)rc" && xxtb --sync && echo -ne "\n\e[1;32m======= xxToolbelt was installed. Try 'xxtb'\e[m\n"In your ~/.bashrc or ~/.zshrc or whatever rc file you use paste (prefably in the end of the file):
# START xxToolbelt
source "$HOME/.xxtoobelt/xxtoolbelt.sh"
# END xxToolbeltClone (or symlink) the repository folder to your home directory (or wherever you want). Example:
git clone git@github.com:thereisnotime/xxToolbelt.git
cp -r ./xxToolbelt ~/.xxtoolbeltReload your terminal.
wget -O xxToolbelt.tar.gz https://github.com/thereisnotime/xxToolbelt/archive/main.tar.gz && tar -xf xxToolbelt.tar.gz && mkdir "$HOME/.xxtoolbelt" && mv ./xxToolbelt-main/* "$HOME/.xxtoolbelt" && echo -ne "# START xxToolbelt\nsource \"$HOME/.xxtoolbelt/xxtoolbelt.sh\"\n# END xxToolbelt" >> "$HOME/.$(ps -p $$ -ocomm=)rc" && source "$HOME/.$(ps -p $$ -ocomm=)rc" && xxtb --sync && echo -ne "\n\e[1;32m======= xxToolbelt was installed. Try 'xxtb'\e[m\n"- Remove the lines from your rc file.
- Remove symlinks:
find ~/.local/bin -lname '*/.xxtoolbelt/*' -delete - (optional) Remove the folder for your scripts
rm -rf ~/.xxtoolbelt.
The main configuration is located in xxtoobelt.sh
You can start TUI with:
xxtb
You can view CLI help with:
xxtb -h
- Add the new script with the proper extension to the correct language folder (or create one). It is recommended to use the templates and have the requirements (README.md in the language folder) because the shebang is important.
- Sync scripts:
xxtb --syncExample:
You can export your scripts to a snippet with:
xxtb -e [scriptname]Example:
NOTE: After syncing, you don't need to reload the shell or re-sync when you modify a script — just run it. Re-sync only when adding or removing scripts.
- Create the appropriate folder in /.xxtoolbelt/scripts/
- Whitelist its extension in your RC file in the XXTOOLBELT_SCRIPTS_WHITELIST array.
- Make sure that the shebang you are using works (test with bash ./yourscript.yourlanguage).
- Reload your shell or open a new terminal.
Edit XXTOOLBELT_SCRIPTS_EDITOR in your RC file.
Edit XXTOOLBELT_SCRIPTS_FOLDER in your RC file.
If you have any sensitive information in your scripts and use git, you can add ".private" before the script extension to ignore it for the git repository. Example xxmyscript.sh -> xxmyscript.private.sh. This will not affect the command, you will still call it with xxmyscript.
Belts allow you to manage external toolbelt repositories — either git repos or local folders — and have their scripts automatically synced alongside your core xxToolbelt scripts. This is useful for:
- Organization-specific toolbelts — share scripts across your team
- Project-specific scripts — keep them in the project repo, register as a belt
- Separating concerns — personal scripts vs work scripts vs hobby projects
From a git repository:
xxtb -a mytools git@github.com:myorg/my-toolbelt.gitThis clones the repo to ~/.xxtoolbelt/belts/mytools/ and syncs all scripts.
From a local folder:
xxtb -a localtools /path/to/my/scriptsThis registers the local path (no cloning) and syncs scripts from there.
xxtb -rShows all registered belts with their folders:
work (local) -> /home/user/projects/work-toolbelt
└─ work-bash
└─ work-python
team (git) -> git@github.com:myorg/team-toolbelt.git
└─ team-bash
└─ team-node
Temporarily disable a belt without removing it:
xxtb --disable-belt mytools
xxtb --enable-belt mytoolsDisabled belts are skipped during sync and update but remain registered.
xxtb --remove-belt mytoolsThis removes the registration, cleans up symlinks, and (for git belts) deletes the cloned directory.
When you run xxtb -u, xxToolbelt updates itself and runs git pull on all git-based belts, then re-syncs everything.
A belt repository should have folders containing scripts:
my-toolbelt/
├── bash/
│ ├── xxmy-script.sh
│ └── xxanother.sh
├── python/
│ └── xxpytool.py
└── README.md
Scripts are synced with the belt name as prefix: mytools-bash/xxmy-script.sh becomes available as xxmy-script in your PATH.
You can also manage belts through the TUI menu:
xxtb # then select option 9) Manage beltsBy default it is 2 levels (so you can use nested folders for your script's libraries). You can edit XXTOOLBELT_SCANNING_DEPTH in your RC file.
xxToolbelt v2.0+ uses symlinks in ~/.local/bin instead of shell aliases. This is critical because AI tools don't load .bashrc or .profile — they inherit the PATH environment variable from the terminal session that launched them.
How it works:
- You open a terminal →
.bashrcsourcesxxtoolbelt.sh→~/.local/binis added to PATH - You run an AI tool from that terminal → it inherits PATH → your scripts are available
- The AI tool runs
xxmyscript→ finds the symlink in~/.local/bin→ executes your script
Add to ~/.claude/settings.json:
{
"env": {
"PATH": "${HOME}/.local/bin:${PATH}"
},
"permissions": {
"allow": [
"Bash(xx*:*)"
]
}
}Add to ~/.codex/config.toml:
[shell_environment_policy]
set = { PATH = "/home/youruser/.local/bin:/usr/bin:/bin" }Add to ~/.aider.conf.yml:
set-env:
- PATH=/home/youruser/.local/bin:$PATHAdd to settings.json:
{
"terminal.integrated.env.linux": {
"PATH": "${env:HOME}/.local/bin:${env:PATH}"
},
"terminal.integrated.env.osx": {
"PATH": "${env:HOME}/.local/bin:${env:PATH}"
}
}# crontab
PATH=/home/youruser/.local/bin:/usr/bin:/bin
* * * * * xxmyscript
# systemd unit
[Service]
Environment="PATH=/home/youruser/.local/bin:/usr/bin:/bin"
ExecStart=/home/youruser/.local/bin/xxmyscriptShould work fine with all POSIX compliant shells (and some of the not fully compliant ones). Tested with:
- Debian/Ubuntu/Arch/Manjaro
- bash/zsh
- Create oneliner for the installation of xxToolbelt.
- Add Julia.
- Add Kotlin.
- Add Haskell.
- Add Swift.
- Add Nim.
- Add Fortran.
- Add COBOL.
- Add Clojure.
- Add Scala.
- Add Dart.
- Add Delphi.
- Create dependency examples where they are missing.
- Test on macOS.
- Test on BSD.
- Add support for PowerShell Core.
- Implement architecture that allows easy installation of "script modules" from git repositories by URL (Belts).
- Add examples for .env secrets management for private scripts.
- Create a management menu for managing installed scripts.
- Create a mechanism for easily exchanging scripts with peers.
Here you can find examples of scripts in various languages that you can use with the xxToolbelt:
Check the Python README for more information.
Check the Ruby README for more information.
Check the Rust README for more information.
Check the R README for more information.
Check the PowerShell README for more information.
Check the Perl README for more information.
Check the Nodejs README for more information.
Check the Lua README for more information.
Check the Groovy README for more information.
Check the Java README for more information.
Check the Golang README for more information.
Check the Erlang README for more information.
Check the Elixir README for more information.
Check the Dlang README for more information.
Check the CSharp README for more information.
Check the Cpp README for more information.
Check the Bash README for more information.
Check the TypeScript README for more information.
Check the Janet README for more information.
Check the Zig README for more information.
Check the V README for more information.
We welcome contributions from everyone! See CONTRIBUTING.md for guidelines.
Quick ways to contribute:
- Add scripts in your favorite language
- Test on different shells, terminals, or operating systems
- Improve documentation
- Report bugs or suggest features
- Create and share your own belts
Check the LICENSE file for more information.
- GitHub gitignore