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:

uv tool install tirekicker
# or: pipx install tirekicker

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

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:

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 a full-page capture for each finding, linked from the report. A run that files no findings leaves this directory empty.
• 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. 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.

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