Metool
A Propagation Tray for Ideas
Installation
npx metoolAsk AI about Metool
Powered by Claude Β· Grounded in docs
I know everything about Metool. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
alias: metool
MeTool (mt) β A Propagation Tray for Ideas

MeTool (mt) is a modular system for organizing all my code, scripts, and configuration. Each piece of functionality lives in its own package with a clear structure, making it easy to find, edit, share, and evolve my tools over time.
Whether capturing a quick shell hack, building a complete application, or managing system services, metool keeps everything organized and accessibleβfor both humans and AI assistants.
Packages can include a SKILL.md file that gives AI assistants like Claude Code the knowledge to help work with that package's tools and workflows.
Key Features
- Instant Access: Jump to any function's source with
mt cdor edit withmt edit - Self-bootstrapping & Modular: Built as a module itself, making it easy to understand and extend
- Environment Separation: Maintain distinct personal, public, and work modules
- Unix Philosophy: Leverages symlinks and simple directory structures for maximum flexibility
Core Commands
cd- Change to MT_ROOT, module, package, or executabledeps- Check metool dependencies (--install to auto-install on macOS)doctor- Run system health diagnosticsedit- Edit function, executable or filegit- Git repository management commands:add- Add repository to .repos.txt manifestclone- Clone a git repository to a canonical locationpull- Pull repositories from repos.txt manifest filepush- Push local commits for repositories in manifestrepos- List git repositoriestrusted- Check if repository is trusted
module- Module management commands:list- List modules in working setadd- Add module to working setremove- Remove module from working setedit- Edit moduleupdate- Update module(s) from git remote
package- Package management commands:list- List packages in working setadd- Add package to working setremove- Remove package from working setedit- Edit packageinstall- Install package componentsuninstall- Uninstall package (remove symlinks)new- Create new package from templateservice- Manage package services
reload- Reload metoolupdate- Update metool from git
Use -h or --help for command usage.
Real-World Value
- Capture Ideas Fast: Turn quick hacks into organized, reusable packages
- Share Selectively: Keep private packages private, share what's useful
- Stay Organized: Never lose track of where useful code lives
- Works at Any Scale: From shell functions to complete applications with systemd/launchd services
MeTool brings structure to code while keeping everything accessible and hackable.
Prerequisites
Metool requires the following tools:
- GNU coreutils (for
realpath)- macOS:
brew install coreutils - Ubuntu/Debian: Usually pre-installed
- macOS:
- GNU Stow 2.4.0+ (for
mt install)- macOS:
brew install stow - Ubuntu/Debian:
apt install stow(ensure version 2.4.0 or later) - Required: Version 2.4.0 or later for proper
dot-directory support
- macOS:
- bash-completion (optional, for alias completion support)
- macOS:
brew install bash-completion@2 - Ubuntu/Debian:
apt install bash-completion
- macOS:
- GNU ln (optional, for relative symlinks)
- macOS: Included with coreutils
- Ubuntu/Debian: Pre-installed
- bats-core (optional, for running tests)
- macOS:
brew install bats-core - Ubuntu/Debian:
npm install -g batsorapt install bats
- macOS:
Checking Dependencies
Use mt deps to check if all dependencies are installed:
# Check dependencies
mt deps
# On macOS with Homebrew, offer to install missing dependencies
mt deps --install
Note: mt install automatically checks for required dependencies before installing metool.
Quickstart
Option 1: One-line installer (Recommended)
curl -sSL https://raw.githubusercontent.com/mbailey/metool/master/install.sh | bash
This will:
- Bootstrap metool using metool itself
- Clone metool to its canonical location (
~/Code/github.com/mbailey/metoolby default) - Install required dependencies (with your permission)
- Configure your shell (.bashrc or .zshrc)
- Provide next steps
Option 2: Manual installation
-
Clone and install MeTool:
git clone https://github.com/mbailey/metool.git cd metool ./install.sh -
Reload your shell:
source ~/.bashrc # or ~/.zshrc for zsh users -
Verify installation:
mt --help # if using bash mtbin --help # works in any shell
Install additional packages
mt clone https://github.com/mbailey/metool-packages.git
mt install metool-packages/*
For zsh users
If you use zsh (default on modern macOS), use the mtbin command instead of mt:
mtbin install package-name
mtbin deps --install # Check and install dependencies
Metool modules
A Metool Module is a collection of Metool Packages.
A typical metool module with packages might look like this:
~/mt-public/ # A metool module directory
βββ neovim/ # A metool package
β βββ bin/ # (Optional) Executable scripts
β β βββ nvim-config-check
β β βββ nvim-update-plugins
β βββ config/ # (Optional) Configuration files
β β βββ dot-config/ # Maps to ~/.config/
β β βββ nvim/ # Maps to ~/.config/nvim/
β β βββ init.lua
β β βββ lua/
β βββ docs/ # (Optional) Documentation
β β βββ keybindings.md
β βββ lib/ # (Optional) Library files used by bin scripts
β β βββ nvim-helpers.sh
β βββ README.md # Package documentation
β βββ shell/ # (Optional) Files to be sourced
β βββ aliases # Shell aliases
β βββ env # Environment variables
β βββ functions # Shell functions
βββ tmux/ # Another metool package
βββ bin/
βββ config/
βββ README.md
When you run mt install ~/public/neovim, metool will:
- Create symlinks from the package's bin/ directory to ~/.metool/bin/
- Create symlinks from config/ to their respective locations (e.g., dot-config/ to ~/.config/)
- Create symlinks from shell/ to ~/.metool/shell/
A metool module can contain multiple packages, and you can selectively install packages from different modules.
Using Metool from Scripts
Since mt is implemented as a shell function (to enable environment modifications), it cannot be called directly from scripts. For script usage, metool provides the mtbin wrapper:
#!/bin/bash
# Example: Installing packages from a script
# Use mtbin instead of mt for script usage
mtbin install dev/git-tools
mtbin install personal/shell-utils
# All mt commands work through mtbin
mtbin list
mtbin sync dev
The mtbin script is installed in metool's bin/ directory and sources the metool function before executing commands.
