heya

Commands and usage

Heya runs in two modes and takes a few flags. Inside an interactive session, slash commands control the model, your saved sessions, and what is loaded.

Run it

heya                          # an interactive session
heya "fix the failing test"   # run one task and exit
heya init                     # set up a model, local or cloud

Attach a file or an image by writing @ and the path. With a vision model, Heya reads a screenshot directly:

heya "what is failing here? @debug.log @error.png"

Flags

JSON output

Pass --json with a task and Heya prints one JSON object to stdout on exit:

heya --json "triage this: ..." | jq .result

The object has five fields: result (the agent's answer, or null on error), tokens ({"session": N, "weak": N}), cost (dollars, float), tools (list of tool events that ran), and error (a string if something went wrong, else null). Stdout carries only that object: no banner, no trace, no streamed tokens. The exit code is non-zero on error. --json without a task is an error.

heya update

Upgrade Heya in place. It detects how Heya was installed and runs the right upgrade: pipx upgrade heya-agent for a pipx install, or pip otherwise. A development checkout is left alone with a note to use git. Start Heya again afterward to use the new version.

When a newer version is on PyPI, Heya also shows a one-line notice at startup (see the [update] config to turn it off).

Slash commands

Type these inside an interactive session. Type / and Heya completes the command names (with a short description each); a typo like /mdl still finds /model. Type @ to complete a file path.