heya-agent 0.0.4

A single, local-first, model-agnostic, tool-using AI agent.

Heya

A local-first, model-agnostic terminal AI agent for WordPress and WooCommerce support engineers and developers.

Website · Docs · Changelog

Heya reads a request, decides what to do, calls tools, and loops until the task is done. The model is a configuration choice: it runs against a small local model through Ollama, a frontier cloud model through OpenRouter, OpenAI, or Anthropic, or anything that speaks the OpenAI chat API. Your prompts and your data stay on your machine, and it is built in plain Python with no agent framework, so you can read exactly what every tool does.

Why you might use it

Most agents are general. Heya is general too, but it carries a real specialty: a WordPress and WooCommerce diagnostic assistant that takes a bug from a ticket to a proven answer. Because it is model-agnostic and local-first, you run all of that on your own models, with no vendor lock-in and nothing leaving your machine. And it hosts the Claude Code ecosystem, so your existing Claude skills, plugins, hooks, commands, and sub-agents work in Heya with no re-install.

What it can do

• Diagnose a WordPress or WooCommerce bug end to end. Give Heya a bug report, a ticket, or a log. It reproduces the issue on a disposable WordPress Playground or a dev site, finds the root cause, proposes and verifies a fix, and hands you a paste-ready triage comment with a verdict, impact, evidence, and a repro link. Every stage is evidence-gated: no evidence, no verdict. It can rank a backlog into a pick-list too.
• Edit, plan, and undo. Surgical edit_file and multi_edit change files without rewriting them. Plan mode (/plan) researches and proposes a plan without touching anything. Git-free checkpoints let you /undo the last turn's changes or /rewind to an earlier point, never touching your git.
• Act on a live WordPress and WooCommerce site. heya wp connect links a dev or staging site and acts on it through the official Abilities API (query orders, update status, manage products) under the site's own permission checks, writes behind the approval prompt.
• Web and domain diagnostics. Look up DNS records, a domain's registrar and host (RDAP), whether a domain looks available, and what stack a site runs (WordPress, WooCommerce, server, CDN) from its headers.
• Background agents. Launch sub-agents that run while you keep working, each with an exclusive folder lease so concurrent agents never collide.
• Host your Claude ecosystem. Your ~/.claude skills and plugins become tools, lifecycle hooks run (off by default), and Claude sub-agent and command definitions become Heya roles and commands.
• Git, done your way. Inspect a repo with git_status/git_log/git_diff and commit with a tool that strips any AI-attribution footer in code. Heya commits only when you ask and never auto-commits.
• Connect MCP servers over stdio or HTTP, with OAuth, sampling, elicitation, and logging.
• Script it. heya --json "task" prints one JSON object (result, tokens, cost, tools) and nothing else, so you can pipe a backlog through it in CI.
• Stay cheap and resilient. A dollar cost in /cost, an optional cheaper model for forgiving work, a fallback model that takes over if the primary errors, a per-task token budget, and context compaction so long sessions keep working on small-window local models. Switch models mid-session with /model.
• Remember, review, and update. Facts persist across sessions in plain markdown you can edit; a deterministic code-review pipeline reports real issues instead of inventing them; heya update upgrades in place.
• Files, shell, web, and a real browser, all behind an allow-list and an approval gate: reads run on their own, writes and commands ask first.

Install

You need Python 3.11 or newer. The package is heya-agent; the command is heya.

pipx install heya-agent

pipx installs it into its own isolated environment and puts heya on your PATH. Plain pip install heya-agent works too. Then run heya init to set up a model.

On macOS or Linux you can use Homebrew instead:

brew tap shameemreza/heya https://github.com/shameemreza/heya
brew install heya

Newer Homebrew (5.x and up) asks you to trust a third-party tap once. If you see an "untrusted tap" error, run brew trust shameemreza/heya and then brew install heya again. It is a one-time step; brew upgrade heya needs it only that first time.

The browser tools are optional (they pull in Playwright and a Chromium binary), as is the MCP client:

pipx install "heya-agent[browser]"   # then: python -m playwright install chromium
pipx install "heya-agent[mcp]"       # to connect MCP servers

Heya runs fine without them; the extras only add the tools they name.

From source

git clone [e-mail]:shameemreza/heya.git
cd heya
python3 -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/python -m pytest

Quickstart

heya init                                          # pick a model, once
heya "summarize what changed in the last 3 commits"

A few things it is good at:

# Triage a bug end to end
heya "triage this: variation coupons apply to the parent price at checkout on WP 6.5 / WC 8.7"

# Plan first, change nothing until you approve
heya --plan "add a settings page to my plugin"

# Act on a connected staging store
heya wp connect
heya "list the last 10 failed orders on my staging store"

# Machine-readable output for scripts and CI
heya --json "triage this ticket: ..." | jq .result

Docs

• Getting started
• Commands and usage
• Configuration reference
• The diagnostic workflow
• Connect an MCP server
• Host your Claude skills, plugins, and tools
• WordPress development guidance
• Background agents
• Connect a WordPress site
• Tools and safety

Contributing

See CONTRIBUTING.md. The changelog records what changed between releases.

License

MIT. See LICENSE.