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

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—is essential for integrating the tool into AI assistant workflows or downstream data pipelines. This guide examines the routing logic in scripts/last30days.py and the rendering implementations in 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 defines the --emit argument with allowed choices of compact, json, md, context, and path, defaulting to compact:

# 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:

• "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) 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.

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

Typical output structure:

## 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.

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

Sample output:

{
  "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) 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.

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

Output excerpt:

# 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, 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 (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, 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, 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}