---
name: eck:history
version: "0.7.4"
description: "Display project activity history from .claude/activity.log with filtering and formatting."
disable-model-invocation: false
---

# History

Read-only skill that displays formatted activity history from `.claude/activity.log`.

$ARGUMENTS

---

## Visual Framework

Follow the visual framework defined in the `output:visual-framework` primitive.

---

## Usage

```bash
/eck:history                   # Last 10 entries
/eck:history --all             # Full log
/eck:history --skill develop   # Filter by skill
/eck:history --errors          # Errors only
/eck:history --today           # Today only
```

### Flags

| Flag             | Description                          |
| ---------------- | ------------------------------------ |
| `--all`          | Show all entries (no limit)          |
| `--skill <name>` | Filter by skill name (partial match) |
| `--errors`       | Show only failed entries             |
| `--today`        | Show only today's entries            |

---

## Behavior

### Stage 1: Read Activity Log

1. Read `.claude/activity.log` (JSONL format) from the current project.
2. If the file does not exist or is empty, display:

```bash
source $ECK_HOME/colors.sh
echo ""
printf '%b\n' "${DIM}No activity log found. Run a lifecycle skill to start tracking.${RESET}"
echo ""
```

3. Parse `$ARGUMENTS` for flags:
   - `--all`: do not limit results
   - `--skill <name>`: filter entries where `skill` field contains `<name>`
   - `--errors`: filter entries where `outcome` is `failed`
   - `--today`: filter entries where `ts` starts with today's date (YYYY-MM-DD)
   - Default (no flags): show last 10 entries

4. Parse each JSONL line. Each entry has:
   ```json
   {"ts":"...","skill":"...","feature":"...","outcome":"...","duration_sec":...,"summary":"...","step":"..."}
   ```

### Stage 2: Display Formatted Output

1. Group entries by date (YYYY-MM-DD extracted from `ts`).
2. Display using this format:

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Project History${RESET}"
echo ""

# For each date group (most recent first):
printf '%b\n' "  ${BOLD}{YYYY-MM-DD}${RESET}"
echo ""

# For each entry in that date group (most recent first):
# outcome icon: [x] = success (GREEN), [!] = failed (RED), [~] = partial (YELLOW), [-] = cancelled (DIM)
printf '%b\n' "  {ICON} {HH:MM}  {SKILL}     {SUMMARY}"

echo ""
printf '%b\n' "  ${DIM}Showing {N} of {TOTAL} entries${RESET}"
```

3. Format the time as `HH:MM` from the ISO timestamp.
4. Pad skill names to 20 characters for alignment.
5. Map outcome to icon:
   - `success` -> `${GREEN}[x]${RESET}`
   - `failed` -> `${RED}[!]${RESET}`
   - `partial` -> `${YELLOW}[~]${RESET}`
   - `cancelled` -> `${DIM}[-]${RESET}`

---

## Error Handling

| Condition            | Behavior                                |
| -------------------- | --------------------------------------- |
| No activity log file | Display "No activity log found" message |
| Malformed JSONL line | Skip the line silently                  |
| Empty log            | Display "No entries found"              |
| Invalid filter flag  | Ignore and show all entries             |

---

## Related Documents

- [log-activity.js](../../scripts/log-activity.js) — activity log writer
- [eck:spec skill](../spec/SKILL.md) — lifecycle skill that writes to activity log
