Metadata-Version: 2.4
Name: task-hopper
Version: 2.0.0
Summary: A shell-native, plugin-based CLI for working smarter in your terminal.
Project-URL: Homepage, https://github.com/task-hopper/task-hopper
Project-URL: Source, https://github.com/task-hopper/task-hopper
Project-URL: Issues, https://github.com/task-hopper/task-hopper/issues
Author: Josh Crank
License: MIT
License-File: LICENSE
Keywords: cli,environment,productivity,shell,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: jinja2>=3.1
Requires-Dist: packaging>=24.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# 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

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

Then reload your shell:

```bash
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:`:

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

Then run them:

```bash
hop serve
hop logs
```

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

```yaml
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`:

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

**Official carrots:**
- [warren](https://github.com/task-hopper/task-hopper-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`:

```yaml
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](LICENSE)
