Metadata-Version: 2.4
Name: heya-agent
Version: 0.0.4
Summary: A single, local-first, model-agnostic, tool-using AI agent.
Author: Shameem Reza
License-Expression: MIT
Project-URL: Homepage, https://github.com/shameemreza/heya
Project-URL: Repository, https://github.com/shameemreza/heya
Keywords: ai,agent,cli,local-first,woocommerce,wordpress,support
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: rich>=13
Requires-Dist: prompt_toolkit>=3
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == "browser"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Requires-Dist: keyring>=24; extra == "mcp"
Provides-Extra: dev
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: mcp>=1.0; extra == "test"
Requires-Dist: trustme>=1.0; extra == "test"
Dynamic: license-file

<div align="center">

[![PyPI version](https://img.shields.io/pypi/v/heya-agent?label=PyPI)](https://pypi.org/project/heya-agent/)
[![CI](https://img.shields.io/github/actions/workflow/status/shameemreza/heya/ci.yml?branch=main&label=CI)](https://github.com/shameemreza/heya/actions/workflows/ci.yml)
[![License](https://img.shields.io/github/license/shameemreza/heya)](LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/heya-agent)](https://pypi.org/project/heya-agent/)

# Heya

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

[Website](https://shameemreza.github.io/heya) · [Docs](https://shameemreza.github.io/heya/docs/getting-started.html) · [Changelog](CHANGELOG.md)

![Heya in action](demo.gif)

</div>

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`.

```bash
pipx install heya-agent
```

[pipx](https://pipx.pypa.io) 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:

```bash
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:

```bash
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

```bash
git clone git@github.com:shameemreza/heya.git
cd heya
python3 -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/python -m pytest
```

## Quickstart

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

A few things it is good at:

```bash
# 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](docs/guide/getting-started.md)
- [Commands and usage](docs/guide/commands.md)
- [Configuration reference](docs/guide/configuration.md)
- [The diagnostic workflow](docs/guide/diagnostic-workflow.md)
- [Connect an MCP server](docs/guide/mcp.md)
- [Host your Claude skills, plugins, and tools](docs/guide/hosting-claude-ecosystem.md)
- [WordPress development guidance](docs/guide/wordpress-guidance.md)
- [Background agents](docs/guide/background-agents.md)
- [Connect a WordPress site](docs/guide/wordpress-sites.md)
- [Tools and safety](docs/guide/tools-and-safety.md)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). The [changelog](CHANGELOG.md) records what
changed between releases.

## License

MIT. See [LICENSE](LICENSE).
