petsitter 0.8.4

Intro

Petsitter sits between the tools you already use and the AI provider they talk to.

That's really all it is: a small thing running on your own machine that requests pass through on their way out, and replies pass through on their way back. Your tools don't need to know it's there, and nothing about the way you work has to change.

Once something is sitting in the middle, a few things become possible:

• You can see what's actually being sent. Every request and every reply, as it happens. Most of the time you'll never think about this — right up until something behaves oddly and you'd really like to look. (see how)

• You can help a model along. Some models are shaky at tool calling, or hand back JSON that doesn't quite parse. Petsitter can smooth that over in the middle, so you don't have to change your tools or go find a bigger model. (see how)

• You can keep private things private. API keys and personal details can be taken out before anything leaves your machine. (see how)

None of it is on until you turn it on, and you can take it back out whenever you like — point your tool back where it was and it's as if petsitter had never been there.

uvx petsitter

Nothing else to set up. Have a look around, and if none of it is useful, no harm done.

A bit more precisely

Petsitter is an OpenAI-compatible proxy that layers smart harnesses on top of language models to give them capabilities they don't natively have. It also makes finicky behaviors reliable and dependable.

You install it, point it at a model, load a few example tricks, and suddenly things that model couldn't do before such as tool calling, structured JSON, multi-step reasoning start working. You can also protect secrets, have memory, share server instances across harnesses, and extend the tool trivially.

The built-in tricks are starting points. Tweak them, combine them, or use them as a reference to build something entirely different. Petsitter isn't a turnkey product; it's a kit.

How It Works

Petsitter intercepts every request/response pair and runs it through a pipeline of hooks. Each trick picks which hooks it needs:

1. system_prompt - Inject instructions before the model sees the conversation
2. pre_hook - Modify messages or inject tool definitions before the API call
3. post_hook - Validate, retry, or transform the model's response
4. info - Declare capabilities back to your application

Tricks also have lifecycle hooks (install, startup, shutdown, uninstall) for managing resources across their lifetime.

A trick can be as simple as appending a sentence to the system prompt, or as involved as routing subtasks to three different models in parallel. There's a GUI at / with tabs for managing tricksets and their tricks (Tricks / Models / Agents), a live activity log (Logs), and per-trickset logging configuration (Settings).

The Tricks tab lists your local tricks/*.py alongside community tricks published by other people, and the speech-bubble button in the header opens a Try It panel that sends a message through the pipeline so you can watch which tricks fire.

You can also edit tricks, reorder them, disable, add new ones, and filter them:

Petsitter is part of the DAY50 suite of open-source tools for local AI workflows and constructing better agents.

The core goals of Petsitter are:

• No model changes required - Works with any OpenAI-compatible endpoint
• Pluggable architecture - Write your own tricks in Python. (Skills are included in .agents)
• Transparent to your app - Point your existing code at petsitter instead of the model
• Mix and match - Combine multiple tricks for compound effects

Quick Start

Quickest way:

$ uvx petsitter

Or you can do one off invocation:

# Run petsitter, reading settings from the default config file
# (~/.config/petsitter/config.json, or $PET_CONFIG_DIR)
petsitter -l localhost:8080

# Or point at a specific config file (model, tricksets, etc. all live there)
petsitter -c another_petsitter_config.conf.json -l localhost:8080

Configure the upstream model, tricksets, and modelset via the dashboard at http://localhost:8080 or the pet CLI — everything is persisted to the config file, so a plain petsitter starts the same way next time. pet accepts the same -c flag (before the subcommand, e.g. pet -c another_petsitter_config.conf.json ls) so both tools can target the same config area.

Either way, now you can point your AI applications to http://localhost:8080/v1 and you're going through the petsitter middleware.

Try It

The speech-bubble button in the header opens a conversation panel docked over the dashboard. Type a message and it goes through chat_completions() exactly as a real client's would: same trickset matching, same keyword gating, same hooks, same upstream. It is not a simulation.

What comes back with each reply:

• A pill per trick. Bright means it changed something, and the tooltip lists the stages it ran (Ran: system_prompt, post_hook). Dim means it was loaded but did nothing.
• Why a trick stayed quiet. A keyword-gated trick that didn't fire reads Did not fire, needs keyword: banana.
• Timing and tokens, next to the trickset that handled it.
• The rows light up. Tricks that actually did something pulse in the Loaded Tricks list, so you can watch a reorder or a config change take effect.

Drag the panel by its header to move it, drag its corner to resize, and ⇲ snaps it back to the bottom right. Whether it's open, where it sits, and the conversation itself are all remembered across refreshes.

It targets whichever trickset is selected in the pill bar, so switching tricksets switches what you're testing.

Documentation

• What each bundled trick does — The tricks that ship with petsitter, what each one is for, and how to turn it on.
• Writing your own trick — The four hooks, the data each one gets, and the lifecycle around them.
• Tricksets and routing — Grouping tricks, and deciding which requests they apply to.
• Connecting your coding tools — Pointing Claude Code, Codex and opencode at petsitter, and putting them back.
• Model configuration — Naming upstream models so tricks can reach more than one.
• Command line reference — petsitter's flags and the pet subcommands.
• Community tricks — Installing tricks other people wrote, and publishing your own.
• Proxy behaviour — Host override, the config diagnostic, and the HTTP surface petsitter serves.
• When things go wrong — Known rough edges and how they show up.
• Working on petsitter — Running the tests, and driving petsitter from other code.

License

MIT