io.github.aibenyclaude-coder/kira

Set the telemetry consent level for kira_report. level='off' disables all uploads (local log still written). level='basic' uploads only anonymous core (skill_id, status, anonymous UUID, version, OS family, Node major). level='full' additionally uploads sanitized free-text note/context. Call with no arguments to query the current state. See PRIVACY.md for the exact wire format and redaction rules.

Get the full instructions for a specific skill or scar by ID. Call this AFTER kira_lookup to retrieve the step-by-step instructions for the skill you've chosen. lookup returns summaries (no instructions) to save tokens — use this tool to get the full details.

Look up skills (how to do it) AND scars (what to avoid) for a given keyword. Returns matching skills (community first, then vendor) and scars (critical first; your own recorded failures before shared ones, then by frequency). Personal scars recorded by kira_record_failure on this machine fire here too. The agent MUST: 1. Read ALL returned scars first — these are past failures. Avoid repeating them. 2. Read returned skills and choose the best fit for the project context. 3. ANNOUNCE the chosen skill's 'declaration' field to the user BEFORE executing. 4. Follow the skill's instructions step by step, watching for scar patterns.

Surface your most recent PERSONAL scars — the private, local-only failure notes recorded by kira_record_failure under ~/.kira/personal-scars/. Call this at the START of a session (ideally from a SessionStart hook) so you begin already aware of the walls you hit last time on this machine. Returns the top-N scars by recency (most recent first), each with its mistake and what to do instead. Pass 'limit' to change how many, and 'contexts' to keep only scars relevant to the current project. Personal scars are LOCAL-ONLY — this reads them from disk and never touches the network.

Run a PRE-MORTEM before starting a task. Given a goal (and optional project context), return a heat map of the past failure patterns (scars, shared and personal) most likely to bite — ranked worst-first: critical before warning, your own recorded failures before the shared corpus, then by how many times the wall has been recorded (hit_count). Each hotspot includes the mistake, the fix ('instead'), a relative heat score, and estimated minutes saved by avoiding it, plus an aggregate prevention value. When nothing matches strictly, 'near_scars' lists the closest recorded scars instead. Call this FIRST for any non-trivial task to surface known traps up front, then read each hotspot's 'instead' and use kira_lookup / kira_route to plan the actual work.

Capture a retry or exception you just hit as a PERSONAL scar — a private, local-only failure note stored under ~/.kira/personal-scars/. Call this immediately after a task needed extra attempts or threw an error, so future runs on this machine can avoid the same wall. Provide 'title' (what went wrong), 'mistake' (what was done / the exception), and ideally 'instead' (what to do next time). All free text is sanitized (keys, paths, emails redacted) before it touches disk; the response's 'redactions' field reports anything that was rewritten, so check it and re-record if a redaction hit something that was not a secret. A 'malformed' field means this call's parameters were glued together in transport and a field's text was lost — re-record with one long field at a time. A 'folded' field means this was merged into an EXISTING scar as a recurrence: the returned scar is that older one and your title/mistake were not stored, so check 'folded.into_title' and re-record if it describes a different failure. Personal scars are LOCAL-ONLY — they are never uploaded, on any tier.

Report the outcome of applying a Kira skill. ALWAYS call this after completing (or failing) a task guided by a Kira skill. Statuses: 'success' = worked first try, 'retry' = needed extra attempts, 'failure' = gave up. For 'retry' and 'failure', include a note describing what went wrong — this feeds the scar system so other agents don't repeat the same mistake.

Plan a complete route for a goal. Instead of looking up individual skills, describe what you want to achieve (e.g., 'build a web app', 'add payments') and Kira returns an ordered sequence of steps, each with its Skill and Scars. Use this FIRST when the user describes a broad goal rather than a specific task. Then execute each step in order, calling kira_report after each one.

Promote one of YOUR personal scars into a community submission so every Kira user stops hitting that wall. Takes a personal scar id (from kira_personal_brief / kira_lookup), re-sanitizes it, generalizes it to the community scar shape, and returns a prefilled GitHub issue URL plus a gh CLI fallback. NOTHING is uploaded by this tool — show the result to the user and let them submit. Accepted scars earn contributor status (see RECIPROCITY notes in the repo).

Report what's currently loaded and configured: kira version, tier (free/pro), telemetry consent level, counts of skills/scars/routes available, and where the local report log lives. Call this whenever you need to know the install state without exhausting the keyword search via lookup.