# Understanding last30days-skill Output Formats: compact, json, and md Explained

> Explore the compact, json, and md output formats of last30days-skill. Understand how each format serves different use cases from AI synthesis to API integration.

- Repository: [Matt Van Horn/last30days-skill](https://github.com/mvanhorn/last30days-skill)
- Tags: api-reference
- Published: 2026-03-25

---

**The last30days-skill supports five output formats controlled by the `--emit` command-line option, with `compact` (concise markdown), `json` (structured data), and `md` (full articles) serving distinct use cases from AI synthesis to API integration.**

The last30days-skill by mvanhorn aggregates research across Reddit, X, TikTok, and other platforms to generate temporal reports on any topic. Understanding the `compact`, `json`, and `md` output formats—and how they leverage the `Report` dataclass defined in [`scripts/lib/schema.py`](https://github.com/mvanhorn/last30days-skill/blob/main/scripts/lib/schema.py)—is essential for integrating the tool into AI assistant workflows or downstream data pipelines. This guide examines the routing logic in [`scripts/last30days.py`](https://github.com/mvanhorn/last30days-skill/blob/main/scripts/last30days.py) and the rendering implementations in [`scripts/lib/render.py`](https://github.com/mvanhorn/last30days-skill/blob/main/scripts/lib/render.py) to explain exactly how each format structures its results.

## How Output Format Selection Works

The entry point in [`scripts/last30days.py`](https://github.com/mvanhorn/last30days-skill/blob/main/scripts/last30days.py) defines the `--emit` argument with allowed choices of `compact`, `json`, `md`, `context`, and `path`, defaulting to `compact`:

```python

# Argument definition (simplified)

parser.add_argument('--emit', choices=['compact','json','md','context','path'], default='compact')

```

After data collection completes, the main workflow invokes `output_result(report, args.emit, …)` at lines 2048-2060, which routes the `Report` object through the appropriate rendering pathway. The core dispatch logic checks the emit string and delegates to specific render functions in [`scripts/lib/render.py`](https://github.com/mvanhorn/last30days-skill/blob/main/scripts/lib/render.py):

- **`"compact"`** → calls `render.render_compact`
- **`"json"`** → calls `json.dumps(report.to_dict(), indent=2)`
- **`"md"`** → calls `render.render_full_report`
- **`"context"`** → prints `report.context_snippet_md`
- **`"path"`** → prints `render.get_context_path()`

## Compact Mode: Concise Markdown for AI Synthesis

**Compact mode** generates a truncated, markdown-styled summary optimized for direct consumption by AI assistants. This is the default when no `--emit` flag is provided.

The implementation in `render.render_compact` (lines 87-98 in [`scripts/lib/render.py`](https://github.com/mvanhorn/last30days-skill/blob/main/scripts/lib/render.py)) constructs a buffer containing:

- A header with the research topic and date range
- Optional freshness warnings when data is limited
- Mode banners (e.g., **WEB SEARCH MODE** when API keys are missing)
- Cache notices for retrieved results
- A truncated list of top items per source (default limit: 15 items)

Each source section includes the item ID, score, title, URL, and a brief relevance statement. Following the content, `render.render_source_status` (lines 528-534) appends a footer summarizing which sources succeeded, failed, or were skipped due to missing credentials.

```bash
python3 scripts/last30days.py "ai safety" --emit=compact

```

Typical output structure:

```markdown

## Research Results: ai safety

**⚠️ LIMITED RECENT DATA** - Few discussions from the last 30 days.
Only 3 item(s) confirmed from 2024-02-24 to 2024-03-25.

**Date Range:** 2024-02-24 to 2024-03-25
**Mode:** both

### Reddit Threads

**t1a2b3** (score:78) r/AI...
  Title of the thread…
  https://reddit.com/…
  *Why it matters…*

--- source status footer ---

```

## JSON Mode: Structured Data for Programmatic Processing

**JSON mode** serializes the complete `Report` dataclass to a pretty-printed JSON document, exposing all metadata, scoring details, and per-source arrays without truncation. This format bypasses the markdown renderers entirely, calling `json.dumps(report.to_dict(), indent=2)` directly within `output_result` at lines 2052-2053.

The resulting structure includes the topic string, date range, model usage information, and complete arrays for each enabled source (Reddit, X, TikTok, Instagram, Hacker News, etc.), making it ideal for downstream Python scripts, data warehouses, or CI/CD pipelines that need to parse results programmatically.

```bash
python3 scripts/last30days.py "ai safety" --emit=json

```

Sample output:

```json
{
  "topic": "ai safety",
  "range_from": "2024-02-24",
  "range_to": "2024-03-25",
  "mode": "both",
  "reddit": [
    {
      "id": "t1a2b3",
      "title": "Title of the thread…",
      "url": "https://reddit.com/…",
      "score": 78,
      "date": "2024-03-10"
    }
  ],
  "x": [],
  "tiktok": []
}

```

## Markdown Mode: Full-Fledged Research Reports

**Markdown mode** (accessed via `--emit=md`) produces a complete, multi-section article suitable for documentation or human review. The `render.render_full_report` function (lines 702-714 in [`scripts/lib/render.py`](https://github.com/mvanhorn/last30days-skill/blob/main/scripts/lib/render.py)) generates:

- A document title and generation timestamp
- Explicit date ranges and model usage sections
- Detailed per-source sections containing every retrieved item
- Expanded metadata including engagement metrics, confidence scores, top comments, and generated insights

Unlike compact mode, this format does not truncate to 15 items; it includes the complete dataset for comprehensive offline analysis.

```bash
python3 scripts/last30days.py "ai safety" --emit=md

```

Output excerpt:

```markdown

# ai safety - Last 30 Days Research Report

**Generated:** 2024-03-25T12:34:56Z
**Date Range:** 2024-02-24 to 2024-03-25
**Mode:** both

## Models Used

- **OpenAI:** gpt-4-turbo
- **xAI:** Claude-3-Opus

## Reddit Threads

### t1a2b3: Title of the thread

- **Subreddit:** r/AI
- **URL:** https://reddit.com/…
- **Date:** 2024-03-10 (confidence: high)
- **Score:** 78/100
- **Relevance:** …

```

## Additional Output Modes: context and path

Beyond the three primary formats, last30days-skill provides two utility modes for specific integration scenarios:

- **`--emit=context`**: Returns only the generated context snippet stored in `report.context_snippet_md`, produced by `render.render_context_snippet` (lines 650-666). This minimal markdown block is designed for embedding directly into LLM prompts.
- **`--emit=path`**: Prints the filesystem location returned by `render.get_context_path()`, allowing external shell scripts to locate the cached context file without parsing content.

## Summary

- **Compact mode** (default) produces truncated markdown summaries via `render.render_compact` in [`scripts/lib/render.py`](https://github.com/mvanhorn/last30days-skill/blob/main/scripts/lib/render.py), optimized for AI assistant consumption with source status footers.
- **JSON mode** serializes the full `Report` dataclass using `report.to_dict()` and `json.dumps()`, enabling programmatic access to complete datasets without formatting overhead.
- **Markdown mode** generates comprehensive, multi-section reports via `render.render_full_report`, containing uncapped item lists and detailed metadata for human review.
- The `output_result` function in [`scripts/last30days.py`](https://github.com/mvanhorn/last30days-skill/blob/main/scripts/last30days.py) (lines 2048-2060) routes all formatting decisions based on the `--emit` flag values: `compact`, `json`, `md`, `context`, or `path`.

## Frequently Asked Questions

### What is the default output format for last30days-skill?

The default output format is **compact**, which produces a concise markdown summary suitable for direct synthesis by AI assistants. This is defined in the argument parser at lines 1424-1425 in [`scripts/last30days.py`](https://github.com/mvanhorn/last30days-skill/blob/main/scripts/last30days.py), where the `--emit` flag defaults to `"compact"` if not specified by the user.

### How do I consume last30days-skill output in a Python script?

Use **`--emit=json`** to receive a complete JSON serialization of the `Report` object. The JSON includes all fields from the dataclass defined in [`scripts/lib/schema.py`](https://github.com/mvanhorn/last30days-skill/blob/main/scripts/lib/schema.py), allowing you to parse the results with standard `json.loads()` and access per-source arrays (Reddit, X, TikTok, etc.) without parsing markdown text or dealing with truncation limits imposed by compact mode.

### What is the difference between compact mode and md mode?

**Compact mode** truncates results to 15 items per source and includes synthetic summaries and warnings designed for AI consumption, while **md mode** (full markdown) returns an uncapped, detailed report with complete metadata, engagement metrics, and per-item insights formatted as a stand-alone research article. Compact mode uses `render_compact`; md mode uses `render_full_report`, both located in [`scripts/lib/render.py`](https://github.com/mvanhorn/last30days-skill/blob/main/scripts/lib/render.py).

### Where does the context snippet get stored when using --emit=path?

The path mode prints the filesystem location returned by `render.get_context_path()`, which typically resolves to a user-specific data directory such as `~/.local/share/last30days/out/context.md`. This allows external automation scripts to locate and read the cached context snippet file without needing to capture or parse the command output directly.