reference

Reference

Installing, configuring and testing Agent Utils. The long-form guides for each extension live in the repository's docs/.

Install

The Pi package installs every extension, prompt template and theme at a tagged release:

pi install git:github.com/harryaskham/agent-utils@v1

The standalone tools are flake packages:

nix build .#ag              # fleet speech, images, audio, questions and healthnix build .#pi-session      # fork sessions between machinesnix build .#skill-search    # skill and MCP discovery (also skill-server)nix build .#durable-extensions  # speech and media modules for pi-daemon sessions

The 41 extensions

Family	Extensions
speech	`read-aloud` `tts-narration` `tts-queue` `audio-providers` `realtime-agent` `force-agent-speech` `audio-reel` `pipe`
screens	`kitty-image-preview` `shared-images` `image-413-recovery` `pi-graphics` `editor-chips` `tendril-share` `macos-native` `android` `xvfb` `firecracker-vm`
sessions	`choice` `omni-input` `ring-input` `herdr-input-state` `compaction-continue-guard` `compact-next` `self-compact` `endless` `after` `session-fork` `scrub` `git-behind-warning` `copilot-auth-refresh` `copilot-model-identity` `pi-self-update` `effort` `m` `nix-devshell` `cacophony-runtime` `cacophony-mcp`
work	`web-search` `app-automation` `slack-mcp`

Settings

Agent Utils reads its own subtree of Pi's settings.json and never rewrites Pi's or other packages' settings.

Key	Configures
`agentUtils.audio.providers`	Named speech providers for every voice surface
`selfModelSelection.models`	Which models agents may switch to themselves
`agentUtils.cacophony.autoRegister`	Whether unmanaged sessions register with the agent orchestrator
`agentUtils.globalShellExpansion.enabled`	Typed special forms resolved in memory at start-up
`piSelfUpdate`	Opt-in package auto-update at start-up, and reload after it

Environment

Variable	Used for
`PI_TTS_QUEUE_DIR`	The machine-wide speech spool
`PI_AGENT_UTILS_STATE_DIR`, `PI_TTS_MUTE_PATH`	Durable archives and the speech mute policy
`PI_AUTO_UPDATE_ON_STARTUP`, `PI_AUTO_RELOAD_AFTER_UPDATE`, `PI_OFFLINE`	Start-up updates
`DISABLE_PI_CACO`	Turn off every orchestrator integration
`PI_DISABLE_AHP`	Turn off Agent Host Protocol integration
`WEB_SEARCH_MODEL`, `WEB_SEARCH_MAX_OUTPUT_TOKENS`, `WEB_SEARCH_*`	Web search model, limits, proxy and token sources
`AG_CONFIG`	The `ag` configuration file

Working with a session host

Every extension must work on its own. When the Paratenic session host is present, portable features are also offered to its remote clients through the Agent Host Protocol, under a few rules:

Agent Utils owns the behaviour, user interface, policy and device adapters; the host's Pi plugin is only a thin, generic transport.
Agent Utils discovers a versioned structural bridge rather than importing the host's code.
Local and remote input enter the same state machine, with exactly-once correlated commands; there is never a second copy of the state.
Images shared into context become durable host attachments; local previews stay local.
A capability is advertised only after it works end to end and passes conformance tests.

Testing

npm test                 # 179 test files on Node's built-in runner, no frameworksnpm run check            # lint workflows and validate this sitecargo test               # the Rust cratesnpm run test:choice-ui   # real-terminal checks of the choice interface

Extensions keep their Pi, process and terminal surfaces thin and put logic in pure modules that tests import directly. Slow or environment-dependent checks, such as a real kitty preview reload or a model-restore process, are opt-in behind environment variables.

This site is built from site/ by scripts/site/build.py and checked by scripts/check-site.py.