task-hopper 2.0.0

A shell-native, plugin-based CLI for working smarter in your terminal.

Task Hopper

Task Hopper is a shell-native, plugin-based CLI for working smarter in your terminal. Out of the box it works as a configurable command shortcut tool — and is extended into something more powerful through plugins called carrots. It runs commands in your current shell session — so things like cd, environment variables, and shell state actually take effect.

Installation

curl -fsSL https://raw.githubusercontent.com/task-hopper/task-hopper/main/install.sh | bash

Then reload your shell:

source ~/.bashrc  # or ~/.zshrc

The installer creates an isolated venv at ~/.hop/venv, writes a shim to ~/.local/bin/hop, and automatically sources the shell integration into your ~/.bashrc or ~/.zshrc. Running the installer again is safe — it won't duplicate anything.

Security note: hop sources its shell integration directly into your session, and carrots can emit directives that are evaluated in your shell. Only install carrots from sources you trust.

Usage & Configuration

After installing, run hop -h to see available commands. On a bare install, hop comes with a handful of built-in commands — the rest comes from carrots and your own config.

Define command shortcuts in ~/.hoprc under commands::

# ~/.hoprc
commands:
  serve: uv run pserve app.ini --reload
  logs: tail -f /var/log/myapp.log

Then run them:

hop serve
hop logs

Values support Jinja2 templating, so you can reference other keys in your config:

my_port: 3000

commands:
  serve: uv run pserve app.ini --port {{ my_port }}

Carrots

Carrots are plugins that extend hop with new commands and functionality. A bare install of hop has no domain-specific commands — everything comes from carrots.

Carrots can be official (maintained by the task-hopper project), third-party (from GitHub or a URL), or local (a directory on your machine).

Install a carrot by adding it to your ~/.hoprc:

carrots:
  - path:/absolute/path/to/carrot   # local
  - github:user/repo                 # third-party
  - warren                           # official

Official carrots:

• warren — manage development projects, navigate directories, and handle environment variables

Building a carrot

Run hop carrot scaffold to generate a new carrot interactively.

A carrot is a directory with two things:

• carrot.toml — declares the carrot's metadata and maps command names to Python modules
• One or more Python modules, each with a register(app) function that adds commands to the hop CLI

Install your carrot locally by adding it to ~/.hoprc:

carrots:
  - path:/absolute/path/to/your-carrot

Diagnosing your installation

If something isn't working, run hop doctor to check the health of your installation, config, and carrots.

License

MIT — see LICENSE