# Oslog

> Read, stream, and analyze Apple unified logs (OSLog) for iOS/macOS apps. Auto-detects subsystem from Logger usage or bundle identifier. Supports live log show, real-time streaming, and .logarchive analysis with full predicate reference. Use when the user asks to check app logs, stream console output, debug with OSLog, or analyze .logarchive files on iOS/macOS.

- **Type:** Skill
- **Install:** `agentstack add skill-artemnovichkov-skills-oslog`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [artemnovichkov](https://agentstack.voostack.com/s/artemnovichkov)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [artemnovichkov](https://github.com/artemnovichkov)
- **Source:** https://github.com/artemnovichkov/skills/tree/main/skills/oslog
- **Website:** http://skills.sh/

## Install

```sh
agentstack add skill-artemnovichkov-skills-oslog
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# oslog

Read, stream, and analyze Apple unified logs for iOS/macOS apps.

## When to Use

Activate when the user asks to:
- Check, read, show, or debug app logs
- Stream logs in real time
- Analyze `.logarchive` files
- Filter system logs by process, subsystem, or message content
- Investigate crashes, errors, or unexpected behavior via logs

## Step 1 — Detect Subsystem

Auto-detect the OSLog subsystem from the project. Try these sources in order:

1. **Source code** — search for `Logger(subsystem:` in Swift files to find the actual subsystem string used in code
2. **`project.pbxproj`** — fall back to `PRODUCT_BUNDLE_IDENTIFIER` build setting (common convention is to use bundle ID as subsystem)
3. **`Info.plist`** — read `CFBundleIdentifier` value (resolve `$(PRODUCT_BUNDLE_IDENTIFIER)` if needed)
4. **Ask the user** — if all detection fails, ask for the subsystem string

Store the detected subsystem for reuse within the session.

## Step 2 — Determine Mode

### Mode A: Show Recent Logs

Query recent logs from the live system log store.

```bash
/usr/bin/log show --last m --info --debug --no-pager \
  --predicate 'subsystem == ""' | head -100
```

- Default to `--last 5m`, adjust based on user request
- Always pipe through `head` on first query to avoid flooding output
- Increase `head` limit or remove it only if the user asks for more

### Mode B: Stream Live Logs

Stream logs in real time from a running app.

```bash
/usr/bin/log stream --info --debug \
  --predicate 'subsystem == ""'
```

- Note: `--no-pager` is not needed here — `log stream` is inherently streaming and has no pager
- Run via Bash with `run_in_background` — the stream is continuous
- Notify the user when output is available
- Stop the stream when the user is done or the task changes

### Mode C: Analyze `.logarchive`

Query an exported log archive bundle.

**Locate the archive:**
```bash
ls .logarchive/Info.plist
```

**Determine time range:**
```bash
/usr/bin/log show --style ndjson --no-pager  | head -1
/usr/bin/log show --style ndjson --no-pager  | tail -1
```

**Query the archive:**
```bash
/usr/bin/log show --info --debug --no-pager \
  --predicate 'subsystem == ""'  | head -50
```

**Export a new archive (requires sudo):**
```bash
# Path must not already exist — log collect creates the directory
sudo /usr/bin/log collect --last 30m --output .logarchive
```

## Critical Rules

- **Always use `/usr/bin/log`** — bare `log` conflicts with zsh builtin
- **Always include `--no-pager`** — interactive pagers hang in non-interactive contexts
- **Always pipe through `head -N`** on initial queries — archives and log stores can contain millions of entries
- **Include `--info --debug`** — by default only Default and Error/Fault levels are shown
- **Use `--style ndjson`** for programmatic parsing/counting, `--style default` for human-readable output

## Predicate Reference

See `PREDICATES.md` for the full predicate field table, comparison operators, and NSPredicate syntax. Key shorthand examples:

```bash
's=com.example.app'                                # filter by subsystem
's=com.example.app AND c=networking'               # subsystem + category
's=com.example.app AND type>=error'                # errors and faults only
's=com.example.app AND m:"timeout"'                # message contains keyword
```

## Common Workflows

**Show all errors/faults from the app:**
```bash
/usr/bin/log show --last 10m --no-pager \
  --predicate 's= AND type>=error' | head -50
```

**Show logs for a specific category:**
```bash
/usr/bin/log show --last 5m --info --debug --no-pager \
  --predicate 's= AND c=networking' | head -100
```

**Search for a keyword in messages:**
```bash
/usr/bin/log show --last 5m --info --debug --no-pager \
  --predicate 's= AND m:"timeout"' | head -50
```

**Count events by type in an archive:**
```bash
/usr/bin/log show --no-pager --style ndjson \
  --predicate 's= AND type=error'  | wc -l
```

**List unique categories from the app:**
```bash
/usr/bin/log show --last 30m --info --debug --no-pager --style ndjson \
  --predicate 's=' | head -500 | \
  grep -o '"category":"[^"]*"' | sort -u
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [artemnovichkov](https://github.com/artemnovichkov)
- **Source:** [artemnovichkov/skills](https://github.com/artemnovichkov/skills)
- **License:** MIT
- **Homepage:** http://skills.sh/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-artemnovichkov-skills-oslog
- Seller: https://agentstack.voostack.com/s/artemnovichkov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.