Metadata-Version: 2.4
Name: tirekicker
Version: 0.1.0
Summary: A persona-driven autonomous evaluator for web apps.
Project-URL: Homepage, https://github.com/greentechgear/tirekicker
Project-URL: Repository, https://github.com/greentechgear/tirekicker
Project-URL: Issues, https://github.com/greentechgear/tirekicker/issues
License-Expression: MIT
License-File: LICENSE
Keywords: agent,browser,evaluation,llm,playwright,testing,ux
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: playwright>=1.40
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# TireKicker

TireKicker is a persona-driven evaluator for web apps. Give it a skeptical user, a target URL, and a real browser; it walks the product, records objective browser signals, files persona-voiced findings, and renders a report of what worked, what broke, and what would make that user bounce.

## 60-second quickstart

Install the published tool with either `uv` or `pipx`:

```console
uv tool install tirekicker
# or: pipx install tirekicker
```

From a checkout, use `uv tool install .` instead. Then create a project configuration:

```console
kick init
# If this machine has not been authenticated already:
codex login
kick run organizer
```

The default path uses the locally installed Codex CLI and the operator's existing Codex login. It needs zero API keys. Edit `tirekicker.yaml` and the persona before pointing a run at a real target; `kick doctor` checks the setup and explains missing pieces.

## Alternate backend: OpenAI-compatible

For OpenAI-compatible endpoints or gateways, set the backend and its environment variables:

```console
export TIREKICKER_LLM_BASE_URL=https://gateway.example/v1
export TIREKICKER_LLM_MODEL=your-model
export TIREKICKER_LLM_API_KEY=your-key
kick run organizer --brain openai_compat
```

The endpoint can be a hosted service, a local server, or a compatible gateway. Keep keys in the environment, never in a persona or checked-in YAML, and run `kick doctor` to verify the configured 1-token health check. The request timeout defaults to 120 seconds; local reasoning models such as Ollama + Qwen may need `brain.openai_compat.timeout_s: 300` or higher.

## What a run leaves behind

Each run creates a timestamped directory under `runs/`:

- `report.md` is the readable seven-section evaluation with severity-grouped findings and relative screenshot links.
- `findings.json` is the structured record, including goal outcomes, the final verdict, and objective signals.
- `transcript.jsonl` records every observation, action, result, and snapshot digest.
- `screenshots/` contains step captures and full-page captures attached to findings.
- `console.log` and `network.har` preserve browser console/page errors and network evidence.
- `llm/` retains failed backend request material for diagnosis; add `--debug-llm` to `kick run` to retain every decide/reflect prompt and response, including successful calls.

## Authoring a persona

Persona files are Markdown with a YAML frontmatter block. Start from `kick init` or copy [`personas/organizer.md`](personas/organizer.md). Give the persona an id, role, credential mode, one or more concrete goals, optional discovery hints, a disposition, limits, a test card, and a `never` list. Put the persona's voice and domain knowledge in the Markdown body; that body is passed verbatim to the evaluator. Use `fresh_signup` with a disposable `tk-*` email pattern, or `provided` with a credential environment prefix. Hints should help the evaluator judge the experience, not turn the run into a hard-coded script.

## Safety and target setup

Run only against a target you are authorized to evaluate. Use test accounts, test payment cards, isolated mail and payment integrations, and an explicit cleanup plan. The live-MVP and staging guidance is in [`examples/target-setup.md`](examples/target-setup.md).

TireKicker is MIT-licensed and intentionally keeps the browser, LLM, and report artifacts visible so a human can review what happened.
