Tellme - Stop Watching Long-Running Server Jobs

中文说明 / Chinese README

---

Running something large on a remote server, like downloading a model, installing packages over a slow network, or building a project, usually means one annoying tradeoff: either stay at the terminal and keep checking, or walk away and risk forgetting the result.

Tellme solves that problem.

Tellme is a lightweight CLI tool that wraps a long-running command, waits for it to finish, and then sends you a notification with the result: success or failure, exit code, elapsed time, a tail summary of stdout/stderr, and session hints so you can inspect the full output later.

Notifications are powered by Apprise, so you can route them to services like Telegram, PushMe, and many other channels. See the Apprise wiki for all supported notification providers.

Install

The recommended way to install it is with pipx:

pipx install tellme-notify

Upgrade later with:

pipx upgrade tellme-notify

Install directly from this repository:

pipx install .

Usage

Quick start

Run a command and get notified when it finishes:

tellme wget https://example.com/large-model.bin

For a quick one-shot notification without wrapping a command:

tellme echo "Task finished"

If the wrapped command itself starts with - flags, use -- to separate Tellme's arguments from the target command:

tellme -- wget -q https://example.com/file

When the command exits, Tellme sends a message containing the command, exit code, duration, tail output summary, and session information.

Configure notification targets

Use the interactive configuration screen to add your Apprise URLs:

tellme --configure

Inside the configurator, the single-key actions are:

• a: add an Apprise URL
• r: remove a URL
• e: enable or disable a URL
• c: clear all targets
• t: toggle WSL Windows Toast support
• m: set the max stdout/stderr summary length
• s: save config
• q: quit

The default config path is ~/.config/tellme/config.yaml.

Example Apprise URLs:

• Telegram: tgram://<BOT_TOKEN>/<CHAT_ID>/
• PushMe: pushme://<TOKEN>

For safety, avoid putting tokens directly into shell history. Tellme stores config with private permissions where possible.

Session management

Tellme provides session management similar to screen:

Start a named session:

tellme -N my-task long-running-command

Later, attach to it:

tellme -a -s my-task

Inside an attached session, press Ctrl+A then D to detach.

List all sessions:

tellme --sessions

Show the full output of one session:

tellme -s <SESSION_ID_OR_NAME>

Clean up exited session records:

tellme --clean

Direct notifications with echo

For quick one-shot notifications without session overhead:

tellme echo "Build finished successfully"

This sends a notification immediately without creating a session or recording logs.

Agent Skill Support

Tellme includes a built-in skill for AI agents. Install it to your project directory:

tellme --install-skill

This copies the bundled TellUser skill into your current directory. AI assistants can then use tellme echo to notify you when long tasks complete.

Diagnostics

Run environment and config diagnostics:

tellme --doctor

WSL Windows Toast

When running inside WSL, Tellme can send native Windows toast notifications through powershell.exe, without requiring a separate Windows-side app.

On non-WSL Linux systems, that channel is safely skipped.

Contributing

If you find a bug or want to suggest an improvement, feel free to open an Issue or a Pull Request.

License

This project is released under the MIT License.

---

Acknowledgement: notification delivery is powered by Apprise.