# Luku
> Agent-native website analytics. The coding agent installs it, proves it works, queries it, and acts on it. No human dashboard. The human should never open a verify link or look at charts.
Base URL: https://luku.io
Ingest: https://a.luku.io (or the `data-api` on the snippet)
CLI: `npx @lukuio/cli`
JS helper: `npm i @lukuio/js`
## Trigger
User says things like “add luku”, “add analytics”, “what are people doing on the site”. You run the loop. Ask only for missing context (live URL, framework). Do **not** ask the human to run verify, open `verify_url`, or confirm `page_view`.
## Quickstart
```bash
npx @lukuio/cli init --name "My site" --url https://example.com
```
Or:
```bash
curl -X POST https://luku.io/api/v1/quickstart \
-H 'content-type: application/json' \
-d '{"name":"My site","url":"https://example.com"}'
```
Returns: `token` (`lk_…`), `write_key` (`wk_…`), `site.id`, HTML `snippet`, `ownership.claim_url`, MCP config.
## Loop (agent executes)
1. create / quickstart → persist `lk_` token + wire MCP
2. add snippet to site `` (never put `lk_` / `wk_` in client code)
3. call `verify` → **you** HTTP-GET `verify_url` (it has `?luku_verify=vs_…`) until `page_view` succeeds; optionally use `check_install`
4. ask which business outcomes matter → `define_event` + instrument `luku.track(...)` → verify those events the same way
5. relay `ownership.claim_url` to the human (billing / recovery only)
6. `mark_release` on every deploy; answer questions with `overview` / `pages` / `events` / `attention` / `friction` / `diagnose`
## Rules
- Never ask for email — use `git config user.email` or omit
- Never ask the human to open `verify_url` — fetch it yourself
- Always verify after install before claiming success
- Always `mark_release` on deploy
- Prefer named business events over click soup
- Relay `ownership.claim_url` to the human
- When responses include `note` about sampling, report it verbatim
- Analytics is **live production traffic only**. Localhost / private LAN is fine for `verify`, but it is never recorded as visitors or views — deploy and open the real URL for real numbers
- Treat human behavior and bot / AI-crawler traffic separately; default reads are humans. Use friction, attention, and named events to prioritise design changes in chat
## MCP
Merge into `~/.cursor/mcp.json`:
```json
{
"luku": {
"url": "https://luku.io/mcp",
"headers": { "Authorization": "Bearer lk_…" }
}
}
```
## Tools
| Tool | Purpose |
|---|---|
| create_site | Create site + snippet |
| list_sites | List sites |
| get_install | Platform-specific install recipe |
| check_install | Server-side HTML tag check |
| verify | Prove events arrive (returns verify_url — agent fetches it) |
| define_event | Register business event meaning |
| overview | Views, visitors, referrers, devices |
| pages | Per-path breakdown |
| events | Named event counts |
| attention | Per-section attention table |
| friction | Dead/rage clicks + JS errors |
| mark_release | Mark a deploy |
| compare | Diff two releases |
| diagnose | Deterministic anomaly findings |
## Periods
`today` · `yesterday` · `24h` · `7d` · `28d` · `90d` · `all` · `release:rel_…`
## Event naming
`signup_started`, `signup_completed`, `purchase_completed` — lowercase snake_case.
## Track (browser)
```html
```
Or after the beacon loads: `luku.track('signup_completed')`.