---
name: logshq
description: Keep your human in the loop while you work. Use at the start of any long-running or multi-step task - create an encrypted logshq stream, tell the human the watch URL, then post status updates and log lines as you go. Also use when asked to "log to logshq", "stream progress", or "keep me posted".
---

# logshq — keep your human in the loop

Your human can't see your terminal. logshq gives them a live, E2E-encrypted view
of what you're doing: a pinned status (current phase + progress) and a scrolling
log. Post as you work; they glance.

## Setup (once per task)

```bash
eval "$(logshq new)"        # creates stream, exports LOGSHQ_* env
echo "Watch me live: $LOGSHQ_WATCH"
```

Give the human `$LOGSHQ_WATCH` immediately — it's the whole point. The key in
the `#fragment` never reaches the server; only key holders can read the stream.

If `LOGSHQ_STREAM` is already set in your environment, a stream exists — don't
create another. If the `logshq` CLI is missing, install it first:

```bash
curl -fsSL https://logshq.com/cli -o ~/.local/bin/logshq && chmod +x ~/.local/bin/logshq
```

If that fails, say so and skip logging; never send plaintext logs anywhere
else instead.

## While you work

```bash
logshq status "<phase>" [progress 0..1] [detail]   # update the pinned status
logshq log "<one line of what just happened>"      # append a log line
```

Cadence:

- **Task start:** `logshq status "starting" 0`
- **Every phase change:** `logshq status "running tests" 0.4 "unit suite"`
- **Meaningful steps:** `logshq log "compiled 12 modules"` — aim for one line
  per real step, not per loop iteration. A quiet stream reads as a stalled agent;
  post at least every couple of minutes during long phases.
- **Failures:** `logshq post log '{"v":1,"type":"log","level":"error","ts":"...","msg":"tests failed: 3"}'`
- **Task end:** `logshq status "done" 1 "<one-line summary>"` — or
  `logshq status "failed" 1 "<what broke>"`. Always close the loop.

## Rules

- Messages are one line, plain language, written for a human glancing at a phone.
- Never post secrets, tokens, or credentials — encrypted or not.
- The JSON schema is `{v, type, ts, msg, phase, progress, level}` — additive
  only; extra fields are fine and show as expandable details in the viewer.
- Streams expire (sliding TTL, default 1h after last event). For tasks longer
  than that, keep posting — every event renews the clock.