cheaphelp 1.0.0__tar.gz

cheaphelp-1.0.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

cheaphelp-1.0.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+<!-- insertion marker -->
+## [1.0.0](https://github.com/jacotay7/cheaphelp/releases/tag/1.0.0) - 2026-06-14
+
+<small>[Compare with first commit](https://github.com/jacotay7/cheaphelp/compare/4e6e0365dc8de03ebbfd97a3d418cb181608799d...1.0.0)</small>
+
+### Features
+
+- `--linger` flag to enable lingering during install (#102) ([544c7d5](https://github.com/jacotay7/cheaphelp/commit/544c7d58a6f61bcba8bf9d2fe7fb6a9fe68baa15) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- repair a failing quality gate with a fixer before replanning (#101) ([9210638](https://github.com/jacotay7/cheaphelp/commit/92106383bfae50347649e397dbbf66960c0063a4) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- include per-issue cost breakdown in opened PR descriptions (#100) ([ada7503](https://github.com/jacotay7/cheaphelp/commit/ada7503da108be365431b35c579e97d7b4d9515b) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- surface service run result in `systemd status` (#94) ([cecc993](https://github.com/jacotay7/cheaphelp/commit/cecc9930d8d5fe57ceac855b285d57834c813f39) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- show today's spend vs daily budget footer (#95) ([29d8c5d](https://github.com/jacotay7/cheaphelp/commit/29d8c5df8db95c79b6b98a3855368e1d196eccbe) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- persist unparseable agent output to last_unparsed_<role>.log (#93) ([4ca4aaa](https://github.com/jacotay7/cheaphelp/commit/4ca4aaa89cf12b7298f7ef153bed62c0cbbf6c16) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- report systemd timer/service health in cheaphelp doctor (#92) ([f2958c2](https://github.com/jacotay7/cheaphelp/commit/f2958c248a77372561988b6cd5d3a17368d01cb2) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- add daily spend budget guardrail with warn/exceeded comments (#74) ([728aaf6](https://github.com/jacotay7/cheaphelp/commit/728aaf60f61e27f18719b5a168cfdb7bad0431f5) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- Label needs-human on comment; route back to responder on human reply (#73) ([3f3c493](https://github.com/jacotay7/cheaphelp/commit/3f3c49315b2a87f072edd588f986584ac07b5138) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- Allow `cheaphelp run` for many ticks (`-n` / `--continuous`) (#75) ([5b52ed9](https://github.com/jacotay7/cheaphelp/commit/5b52ed9586b24c3c257982bf2cc8765ac854c2bc) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- Add `cheaphelp retry` to un-stick issues labeled needs-human (#72) ([c1bead1](https://github.com/jacotay7/cheaphelp/commit/c1bead1fcabb762ee818fb1c257230af366eabe4) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- Act on PR review feedback instead of leaving issues stuck in-review (#68) ([25f5f3f](https://github.com/jacotay7/cheaphelp/commit/25f5f3fdca0735b00a6c6d95f003660865670d56) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- Add `cheaphelp config` subcommand (show/get/set) with auto-regen (#63) ([1d26895](https://github.com/jacotay7/cheaphelp/commit/1d26895af99eab3f8ea4af08b4ae118d140ff0bb) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>, Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- track token usage and cost per tick, per role, and per issue (#64) ([e087550](https://github.com/jacotay7/cheaphelp/commit/e0875507cf49aa6fdca30315183296292e7fe6ec) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>, Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- retry transient GitHub and OpenRouter failures with backoff (#62) ([2daca10](https://github.com/jacotay7/cheaphelp/commit/2daca1020f7ce4156e314d6b0927dd17d7594645) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- add `cheaphelp logs` subcommand for viewing and following run activity (#61) ([f3e99a3](https://github.com/jacotay7/cheaphelp/commit/f3e99a30252320c1122909d1c90ca549947c1a86) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- Blast-radius guardrail caps PR diff size (max files/lines) (#60) ([6037d91](https://github.com/jacotay7/cheaphelp/commit/6037d913867c2cb145e9928b97d0e8b98d47957a) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- Let agents follow a project's own contribution conventions (#59) ([7a8e8be](https://github.com/jacotay7/cheaphelp/commit/7a8e8bed6f699d7fa755a032bcf061494f481328) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- Prune build clones for closed issues; add `cheaphelp clean` (#45) ([302eec9](https://github.com/jacotay7/cheaphelp/commit/302eec9601892308fa0983f22660b8af0d2f7828) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- Retry timed-out tasks; re-prompt agents that emit no decision (#44) ([17e8ab6](https://github.com/jacotay7/cheaphelp/commit/17e8ab6b7cf95f4cfccb1ec9d93ba2863fc85a67) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- Hold issues until their dependencies close (#35 part 2) (#43) ([4aeb146](https://github.com/jacotay7/cheaphelp/commit/4aeb14659313a4b63ce8c2fa90226980024566e4) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- Parallel ticks via per-issue locks (#35 part 1) (#42) ([0ba4a4e](https://github.com/jacotay7/cheaphelp/commit/0ba4a4ecc83cf14da46048247880464c4262fc7d) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- Log each agent step as it starts; trim crash logs (#40) ([01efe1b](https://github.com/jacotay7/cheaphelp/commit/01efe1bb735bed7789245365522875dd7f6cbcd2) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- Cap worker tasks run per issue per tick (max_tasks_per_tick) (#39) ([5c7b138](https://github.com/jacotay7/cheaphelp/commit/5c7b138c75ee543690ce33d39671202639dad488) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- Cap issues processed per tick (--max-issues / max… (#38) ([a34dbfd](https://github.com/jacotay7/cheaphelp/commit/a34dbfd325067bb8ecbf20e72f9447cdfbd48251) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- Add cheaphelp status command (#27) ([96e0cb6](https://github.com/jacotay7/cheaphelp/commit/96e0cb645b172b79d090a0327d4e92d7e76ccecc) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- add workspace run-lock to serialise overlapping ticks (#25) ([bfc4778](https://github.com/jacotay7/cheaphelp/commit/bfc477837280eaa3aa82c923cc47dbfe6eff1fe2) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>, Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- make opencode agent subprocess timeout configurable (#21) ([62a4e7a](https://github.com/jacotay7/cheaphelp/commit/62a4e7a81c2eb66c9bc2a7efd16bd6a50368b099) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- add `cheaphelp repo set` to update checks/autofix in place (#19) ([6f66999](https://github.com/jacotay7/cheaphelp/commit/6f669994b642016ebbed484ff37a2ea665a927f7) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- Prefix every GitHub message with a cheaphelp attribution header (#17) ([c001847](https://github.com/jacotay7/cheaphelp/commit/c0018477f42d4501ab3f230106da47de049e1671) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- Hand the exact quality-gate commands to the worker (#12) ([a5ddec5](https://github.com/jacotay7/cheaphelp/commit/a5ddec5d42f291d998912893a24d5fa915cff2db) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+
+### Bug Fixes
+
+- stop finalize replies promising a 'spec below' (#99) ([942db6e](https://github.com/jacotay7/cheaphelp/commit/942db6e1b54a8fa416d98be6198c1e89f8034a08) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- balance-brace JSON extraction and retry unparseable clean exits (#98) ([1232a80](https://github.com/jacotay7/cheaphelp/commit/1232a805d58d6f22d254535f1cc0eca1572b541f) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- Drop stale bot_login args from responder test call sites (#69) ([e9be0c0](https://github.com/jacotay7/cheaphelp/commit/e9be0c0f76105340d90af285821b9b5432cee62c) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- Identify bot comments by marker only, not by author login (#67) ([e554d7b](https://github.com/jacotay7/cheaphelp/commit/e554d7bf5f43f0727ceb27fcd2705e43073534cc) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- Route push failures to needs-human; require workflow PAT scope (#65) ([587b8d5](https://github.com/jacotay7/cheaphelp/commit/587b8d598ae80aeb1dd1e2db3ac3241c727d2ee1) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- Re-validate issue state under its lock so overlapping ticks don't double-act (#58) ([24c279e](https://github.com/jacotay7/cheaphelp/commit/24c279e0ce4888f050b52a792ab34b17cd14aa1e) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+- distinguish `repo set` no-op from real update (#34) ([264cd6c](https://github.com/jacotay7/cheaphelp/commit/264cd6c8243821527ad208a64bb0982b9157e5f7) by Jacob Taylor). Co-authored-by: cheaphelp[bot] <cheaphelp@users.noreply.github.com>
+- Keep the spec at requirements altitude, ask only material questions (#14) ([04a9010](https://github.com/jacotay7/cheaphelp/commit/04a9010a347e90c536bf4b8670b73cd2dcc35de5) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
+
+### Code Refactoring
+
+- Don't run the full quality gate after every task (#29) ([cf0de8e](https://github.com/jacotay7/cheaphelp/commit/cf0de8e5a3c658ee9b9987ffb6c52217ce11b340) by Jacob Taylor). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

cheaphelp-1.0.0/CLAUDE.md

@@ -0,0 +1,127 @@
+# CLAUDE.md
+
+Guidance for AI agents working in this repository.
+
+## What this is
+
+`cheaphelp` is an AI software-engineer for GitHub repos. It installs as a
+background service (systemd timer), watches registered repos, and runs a team of
+narrow agents — via the **opencode** harness against cheap **OpenRouter** models
+— to triage issues, plan, implement, and open PRs for human review.
+
+The pipeline is a label-driven state machine. Each tick polls open issues and
+dispatches by label:
+
+```
+(no pipeline label) + human spoke last  -> responder  refine scope -> issues.md, label :ready
+:ready / :needs-replan                  -> planner    issues.md -> tasks,      label :planned
+:planned, tasks pending                 -> worker     implement one task on the issue branch
+:planned, all tasks done                -> quality gate -> reviewer  open PR (label :in-review) or replan
+                                           (gate fails -> fixer repairs + re-runs gate before replanning)
+:in-review                              -> rework     address new PR review feedback, or no-op
+:needs-human, human replied             -> responder  re-engage a stuck issue
+:needs-human, no new reply / :rejected  -> (idle)
+```
+
+A daily USD spend cap (`daily_budget_usd`, `spend.py`) can halt new agent turns
+for the rest of the UTC day; see `orchestrator.tick` budget handling.
+
+## Workflow (IMPORTANT: branch protection)
+
+`main` is protected. **Never commit or push to `main` directly.** All changes
+land through a pull request:
+
+1. Branch off `main`: `git switch -c <type>-<short-name>` (e.g. `feat-json-output`).
+2. Make the change with tests.
+3. `make format && make check && make test` (all must pass).
+4. Commit (see convention below), push the branch, open a PR.
+
+## Dev commands
+
+```bash
+make setup     # install deps (uv sync)
+make format    # auto-format (ruff format + ruff --fix)
+make check     # lint + types + docs + api checks
+make test      # pytest
+make run cheaphelp [ARGS...]   # run the CLI
+```
+
+Direct equivalents (no direnv):
+
+```bash
+uv run ruff check src tests duties.py scripts --config config/ruff.toml
+uv run ruff format src tests duties.py scripts --config config/ruff.toml
+uv run python -m pytest -q
+uv run cheaphelp <subcommand>
+```
+
+Lint is `ruff` with `select = ["ALL"]` (config in `config/ruff.toml`); it is
+strict (e.g. COM812 trailing commas, ANN annotations, D docstrings). Run
+`make format` before `make check`. Python target is 3.10+.
+
+## Layout
+
+All product code is under `src/cheaphelp/_internal/`:
+
+| Module | Responsibility |
+|--------|----------------|
+| `config.py` | `Workspace` paths + `config.json` (`Config`) |
+| `env.py` | `.env` secret parsing/writing (chmod 600) |
+| `github.py` | minimal GitHub REST client (httpx) |
+| `registry.py` | registered-repo store (`repos.json`) |
+| `gitutil.py` | clones, commit, push, diff helpers |
+| `lock.py` | per-repo file locks so concurrent ticks don't collide |
+| `spend.py` | daily USD spend tracker for the budget guardrail |
+| `conventions.py` | reads `CHEAPHELP.md`/`AGENTS.md`/`CONTRIBUTING.md` into agent context |
+| `pr_state.py` | persists PR <-> issue link state for the rework stage |
+| `opencode.py` | generate `opencode.json`, run agents headlessly, parse decisions |
+| `templates/*.md` | bundled agent prompts (responder/planner/worker/reviewer/rework/fixer) |
+| `tasks.py` | task manifest + per-issue task-state store |
+| `responder.py` / `planner.py` / `worker.py` / `reviewer.py` / `rework.py` / `fixer.py` | per-role turn logic |
+| `orchestrator.py` | one tick of the state machine (`tick()`, `classify()`, stage dispatch) |
+| `cleanup.py` | prune build clones for closed issues / unregistered repos (keeps state) |
+| `systemd.py` | user service + timer install (continuous-mode by default) |
+| `commands.py` / `cli.py` | argparse CLI (`cmd_*` per subcommand) |
+
+Tests live in `tests/`, one file per `src/cheaphelp/_internal/` module (plus
+`test_cli_*.py` per CLI subcommand and `test_api.py`); shared fixtures in
+`tests/conftest.py`.
+
+## Key conventions & invariants
+
+- **Agents communicate via a single final ```json block.** Each role parses the
+  last fenced JSON block from agent output (`opencode.extract_decision`). If you
+  change a role's output contract, update both its prompt in `templates/<role>.md`
+  and the parser/`apply_*` logic in the matching module.
+- **Workspace is the source of truth at runtime**, default `~/.cheaphelp`
+  (override `CHEAPHELP_HOME`): `config.json`, `.env`, `repos.json`, `agents/`
+  (editable prompt overrides), `opencode/opencode.json` (generated),
+  `state/<owner>__<repo>/issue-<n>/` (issues.md, plan.md, tasks.json, tasks/,
+  cost.json, pr_state.json), `state/daily_spend.json`, `clones/`, `logs/`.
+  After editing models/prompts/sandbox, regenerate with `cheaphelp agents sync`.
+- **`tasks.json` is authoritative; the `.md` files are readable mirrors.** Use
+  `TaskStore` for all task state transitions.
+- **cheaphelp owns git remotes**: workers/reviewer never push; the orchestrator
+  does (`gitutil.push_branch`). Agent bash is sandboxed (see `opencode.py`
+  `_READER_BASH` / `_WORKER_BASH`); only `worker` may edit files.
+- **Defaults live in `config.py`** (`DEFAULT_MODELS`, `DEFAULT_LABELS`,
+  `DEFAULT_VARIANTS`, `DEFAULT_SANDBOX`). `Config.from_dict` merges over them, so
+  new keys must be added to the defaults *and* `from_dict`/`to_dict`.
+- **Network isolation in tests**: never make real network/API calls; mock the
+  GitHub client and the agent layer. Set `CHEAPHELP_AGENT_MOCK=/path/to/decision.json`
+  to make `run_agent` return canned output instead of invoking opencode.
+- **Fake GitHub clients**: use `tests.conftest.FakeGitHubClient` (a real
+  `GitHubClient` subclass) instead of writing a new ad-hoc duck-typed class —
+  ad-hoc fakes don't satisfy `ty`'s `GitHubClient` parameter types and need
+  `# ty: ignore[invalid-argument-type]` on every call. Seed `.issues`,
+  `.comments`, `.labels`, etc. and build payloads with `make_issue`/
+  `make_comment`/`make_pr_state`, also in `tests/conftest.py`.
+- **Per-issue failures must not abort a tick** — `_process_repo` guards each
+  stage; preserve that resilience.
+
+## Commit messages
+
+Angular/Karma convention: `<type>[(scope)]: Subject` (capitalized, no trailing
+period). Types: `build`, `chore`, `ci`, `deps`, `docs`, `feat`, `fix`, `perf`,
+`refactor`, `style`, `tests`. Don't update `CHANGELOG.md` (generated). Link the
+related issue in the PR body (`Closes #<n>`).

cheaphelp-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at jacobataylor7@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+

cheaphelp-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# Contributing
+
+Contributions are welcome, and they are greatly appreciated. Every little bit helps, and credit will always be given.
+
+**Please always create an issue before working on a new feature or a bug fix, so that we can discuss the implementation and make sure that your work will be merged.**
+
+## Environment setup
+
+Install [uv](https://github.com/astral-sh/uv) and [direnv](https://direnv.net/), fork and clone the repository, then:
+
+```bash
+cd cheaphelp
+direnv allow
+make setup
+```
+
+You now have the dependencies installed.
+
+You can run the application with `make run cheaphelp [ARGS...]`.
+
+Run `make help` to see all the available actions!
+
+## Tasks
+
+The entry-point to run commands and tasks is the `make` Python script, located in the `scripts` directory. Try running `make` to show the available commands and tasks. The *commands* do not need the Python dependencies to be installed, while the *tasks* do. The cross-platform tasks are written in Python, thanks to [duty](https://github.com/pawamoy/duty).
+
+If you work in VSCode, we provide [an action to configure VSCode](https://pawamoy.github.io/copier-uv/work/#vscode-setup) for the project.
+
+## Development
+
+As usual:
+
+1. create a new branch: `git switch -c feature-or-bugfix-name`
+1. edit the code and/or the documentation
+
+**Before committing:**
+
+1. run `make format` to auto-format the code
+1. run `make check` to check everything (fix any warning)
+1. run `make test` to run the tests (fix any issue)
+1. if you updated the documentation or the project dependencies:
+    1. run `make docs`
+    1. go to http://localhost:8000 and check that everything looks good
+1. follow our [commit message convention](#commit-message-convention)
+
+If you are unsure about how to fix or ignore a warning, just let the continuous integration fail, and we will help you during review.
+
+Don't bother updating the changelog, we will take care of this.
+
+## Commit message convention
+
+Commit messages must follow our convention based on the [Angular style](https://gist.github.com/stephenparish/9941e89d80e2bc58a153#format-of-the-commit-message) or the [Karma convention](https://karma-runner.github.io/4.0/dev/git-commit-msg.html):
+
+```
+<type>[(scope)]: Subject
+
+[Body]
+```
+
+**Subject and body must be valid Markdown.** Subject must have proper casing (uppercase for first letter if it makes sense), but no dot at the end, and no punctuation in general.
+
+Scope and body are optional. Type can be:
+
+- `build`: About packaging, building wheels, etc.
+- `chore`: About packaging or repo/files management.
+- `ci`: About Continuous Integration.
+- `deps`: Dependencies update.
+- `docs`: About documentation.
+- `feat`: New feature.
+- `fix`: Bug fix.
+- `perf`: About performance.
+- `refactor`: Changes that are not features or bug fixes.
+- `style`: A change in code style/format.
+- `tests`: About tests.
+
+If you write a body, please add trailers at the end (for example issues and PR references, or co-authors), without relying on GitHub's flavored Markdown:
+
+```
+Body.
+
+Issue #10: https://github.com/namespace/project/issues/10
+Related to PR namespace/other-project#15: https://github.com/namespace/other-project/pull/15
+```
+
+These "trailers" must appear at the end of the body, without any blank lines between them. The trailer title can contain any character except colons `:`. We expect a full URI for each trailer, not just GitHub autolinks (for example, full GitHub URLs for commits and issues, not the hash or the #issue-number).
+
+We do not enforce a line length on commit messages summary and body, but please avoid very long summaries, and very long lines in the body, unless they are part of code blocks that must not be wrapped.
+
+## Pull requests guidelines
+
+Link to any related issue in the Pull Request message.
+
+During the review, we recommend using fixups:
+
+```bash
+# SHA is the SHA of the commit you want to fix
+git commit --fixup=SHA
+```
+
+Once all the changes are approved, you can squash your commits:
+
+```bash
+git rebase -i --autosquash main
+```
+
+And force-push:
+
+```bash
+git push -f
+```
+
+If this seems all too complicated, you can push or force-push each new commit, and we will squash them ourselves if needed, before merging.

cheaphelp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacob Taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cheaphelp-1.0.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: cheaphelp
+Version: 1.0.0
+Summary: An AI software-engineer that triages GitHub issues, plans, implements, and reviews changes on your repos using cheap OpenRouter models via the opencode harness.
+Author-Email: Jacob Taylor <jacobataylor7@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://jacotay7.github.io/cheaphelp
+Project-URL: Documentation, https://jacotay7.github.io/cheaphelp
+Project-URL: Changelog, https://jacotay7.github.io/cheaphelp/changelog
+Project-URL: Repository, https://github.com/jacotay7/cheaphelp
+Project-URL: Issues, https://github.com/jacotay7/cheaphelp/issues
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# cheaphelp
+
+[![ci](https://github.com/jacotay7/cheaphelp/actions/workflows/ci.yml/badge.svg)](https://github.com/jacotay7/cheaphelp/actions/workflows/ci.yml)
+[![documentation](https://img.shields.io/badge/docs-zensical-FF9100.svg?style=flat)](https://jacotay7.github.io/cheaphelp/)
+
+An AI software-engineer for your GitHub repositories. cheaphelp installs as a
+background service on your machine, watches the repos you register, and runs a
+team of narrow AI agents — powered by **cheap [OpenRouter](https://openrouter.ai)
+models** through the **[opencode](https://opencode.ai)** terminal harness — to
+triage issues, plan work, implement it, and open pull requests for human review.
+
+> **Status: full pipeline wired and exercised live.** All roles run end-to-end
+> against a real repository; expect to keep tuning prompts and hardening edge
+> cases.
+
+## Install
+
+The recommended way to install the `cheaphelp` CLI on your machine:
+
+```bash
+pipx install cheaphelp
+# or, if you don't use pipx:
+pip install --user cheaphelp
+```
+
+For development (running from a clone, contributing, or testing unreleased
+changes), use `uv sync` inside the clone and invoke the CLI as
+`uv run cheaphelp …` — see [Quick start](#quick-start) step 1.
+
+## Quick start
+
+```bash
+# 1. (Development install — end users should `pipx install cheaphelp`, see
+#    the Install section above.) Clone, sync deps, and install the
+#    `cheaphelp` command globally.
+git clone https://github.com/jacotay7/cheaphelp.git
+cd cheaphelp
+uv sync                                          # install deps (needed before tool install)
+uv tool install --from . cheaphelp              # puts `cheaphelp` on $PATH
+
+# 2. Create your machine-local workspace (~/.cheaphelp) and store secrets.
+#    Prompts for your tokens, or pass them as flags / set them later.
+cheaphelp init
+
+# 3. Check everything is wired up.
+cheaphelp doctor
+
+# 4. Register a repo to work on.
+cheaphelp repo add owner/name
+cheaphelp repo list
+
+# 5. Dry-run one tick (shows what it *would* do, no changes).
+cheaphelp run --dry-run
+
+# 6. Run it for real (responder engages open issues).
+cheaphelp run
+
+# 7. Or drain the whole backlog now: repeat ticks until one is idle.
+cheaphelp run --continuous
+
+# 8. Install the background timer (default every 10 minutes; each firing
+#    runs `cheaphelp run --continuous` by default, see the docs).
+cheaphelp systemd install --interval 10m
+cheaphelp systemd status
+```
+
+> **Upgrading.** After pulling new code, re-run `uv tool install --from . --reinstall cheaphelp` to refresh the global command. A plain `git pull` updates the source tree but does NOT refresh the installed binary, and `uv run cheaphelp` would then diverge from your checkout.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) — install, requirements, running modes
+- [Pipeline](docs/pipeline.md) — how the agents collaborate and the quality gate
+- [Configuration](docs/configuration.md) — `config.json` fields, models, budget knobs
+- [Workspace](docs/workspace.md) — files cheaphelp writes to disk
+- [Sandboxing](docs/sandboxing.md) — how agents are isolated and its limits
+- [Cost tracking](docs/cost-tracking.md) — daily budget and per-issue cost reporting
+- [Background service](docs/background-service.md) — running under the systemd timer
+- [Dev guide](docs/dev-guide.md) — for contributors (testing, source layout, mocking opencode)
+
+## For contributors
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Dev guide](docs/dev-guide.md).

cheaphelp-1.0.0/README.md

@@ -0,0 +1,82 @@
+# cheaphelp
+
+[![ci](https://github.com/jacotay7/cheaphelp/actions/workflows/ci.yml/badge.svg)](https://github.com/jacotay7/cheaphelp/actions/workflows/ci.yml)
+[![documentation](https://img.shields.io/badge/docs-zensical-FF9100.svg?style=flat)](https://jacotay7.github.io/cheaphelp/)
+
+An AI software-engineer for your GitHub repositories. cheaphelp installs as a
+background service on your machine, watches the repos you register, and runs a
+team of narrow AI agents — powered by **cheap [OpenRouter](https://openrouter.ai)
+models** through the **[opencode](https://opencode.ai)** terminal harness — to
+triage issues, plan work, implement it, and open pull requests for human review.
+
+> **Status: full pipeline wired and exercised live.** All roles run end-to-end
+> against a real repository; expect to keep tuning prompts and hardening edge
+> cases.
+
+## Install
+
+The recommended way to install the `cheaphelp` CLI on your machine:
+
+```bash
+pipx install cheaphelp
+# or, if you don't use pipx:
+pip install --user cheaphelp
+```
+
+For development (running from a clone, contributing, or testing unreleased
+changes), use `uv sync` inside the clone and invoke the CLI as
+`uv run cheaphelp …` — see [Quick start](#quick-start) step 1.
+
+## Quick start
+
+```bash
+# 1. (Development install — end users should `pipx install cheaphelp`, see
+#    the Install section above.) Clone, sync deps, and install the
+#    `cheaphelp` command globally.
+git clone https://github.com/jacotay7/cheaphelp.git
+cd cheaphelp
+uv sync                                          # install deps (needed before tool install)
+uv tool install --from . cheaphelp              # puts `cheaphelp` on $PATH
+
+# 2. Create your machine-local workspace (~/.cheaphelp) and store secrets.
+#    Prompts for your tokens, or pass them as flags / set them later.
+cheaphelp init
+
+# 3. Check everything is wired up.
+cheaphelp doctor
+
+# 4. Register a repo to work on.
+cheaphelp repo add owner/name
+cheaphelp repo list
+
+# 5. Dry-run one tick (shows what it *would* do, no changes).
+cheaphelp run --dry-run
+
+# 6. Run it for real (responder engages open issues).
+cheaphelp run
+
+# 7. Or drain the whole backlog now: repeat ticks until one is idle.
+cheaphelp run --continuous
+
+# 8. Install the background timer (default every 10 minutes; each firing
+#    runs `cheaphelp run --continuous` by default, see the docs).
+cheaphelp systemd install --interval 10m
+cheaphelp systemd status
+```
+
+> **Upgrading.** After pulling new code, re-run `uv tool install --from . --reinstall cheaphelp` to refresh the global command. A plain `git pull` updates the source tree but does NOT refresh the installed binary, and `uv run cheaphelp` would then diverge from your checkout.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) — install, requirements, running modes
+- [Pipeline](docs/pipeline.md) — how the agents collaborate and the quality gate
+- [Configuration](docs/configuration.md) — `config.json` fields, models, budget knobs
+- [Workspace](docs/workspace.md) — files cheaphelp writes to disk
+- [Sandboxing](docs/sandboxing.md) — how agents are isolated and its limits
+- [Cost tracking](docs/cost-tracking.md) — daily budget and per-issue cost reporting
+- [Background service](docs/background-service.md) — running under the systemd timer
+- [Dev guide](docs/dev-guide.md) — for contributors (testing, source layout, mocking opencode)
+
+## For contributors
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Dev guide](docs/dev-guide.md).

cheaphelp-1.0.0/config/coverage.ini

@@ -0,0 +1,25 @@
+[coverage:run]
+branch = true
+parallel = true
+source =
+  src/
+  tests/
+
+[coverage:paths]
+equivalent =
+  src/
+  .venv/lib/*/site-packages/
+  .venvs/*/lib/*/site-packages/
+
+[coverage:report]
+precision = 2
+omit =
+  src/*/__init__.py
+  src/*/__main__.py
+  tests/__init__.py
+exclude_lines =
+  pragma: no cover
+  if TYPE_CHECKING
+
+[coverage:json]
+output = htmlcov/coverage.json

cheaphelp-1.0.0/config/git-changelog.toml

@@ -0,0 +1,9 @@
+bump = "auto"
+convention = "angular"
+in-place = true
+output = "CHANGELOG.md"
+parse-refs = false
+parse-trailers = true
+sections = ["build", "deps", "feat", "fix", "refactor"]
+template = "keepachangelog"
+versioning = "pep440"