mtg - Meeting Buffer CLI

A fast macOS command-line tool that shows time until your next meeting. Answers: "Do I have time to start this task?"

$ mtg
🟢 47m until 1:1 with Sarah (2:00 PM)

Why?

You're about to start debugging something. Is it worth it? Do you have 2 hours or 12 minutes? One quick command tells you.

Installation

From Source

Requires Xcode Command Line Tools.

git clone https://github.com/mrf/meeting-buffer.git
cd meeting-buffer
make install

Manual

swift build -c release
cp .build/release/mtg /usr/local/bin/

Usage

mtg              # Quick view: time until next meeting
mtg --detail     # Detailed view with upcoming events
mtg --json       # JSON output for scripting
mtg --no-color   # Plain text (for shell prompts)
mtg --config     # Show config file location
mtg --help       # Show help

Output Examples

Default:

🟢 47m until 1:1 with Sarah (2:00 PM)

Detail view (mtg --detail):

┌──────────────────────────────────────────┐
│  Next: 1:1 with Sarah                    │
│  in 47 minutes (2:00 PM)                 │
│  ──────────────────────────────────────  │
│  After that:                             │
│  3:00 PM  Sprint Planning (1h)           │
│  4:30 PM  Eng Sync (30m)                 │
│  ──────────────────────────────────────  │
│  🟢 You have time for a medium task      │
└──────────────────────────────────────────┘

Time Colors

Color	Time Until	Meaning
🟢 Green	> 1 hour	Deep work time
🟡 Yellow	30-60 min	Medium task ok
🟠 Orange	10-30 min	Quick task only
🔴 Red	< 10 min	Wrap up
🔵 Blue	In meeting	Currently busy

Task Suggestions

Based on available time:

Buffer	Suggestion
> 2h	Deep work: architecture, complex bugs
1-2h	Medium task: feature work, code review
30m-1h	Small task: PR review, quick fix
10-30m	Quick wins: emails, Slack, small PRs
< 10m	Prep for meeting, grab coffee

Configuration

Config file is optional. Searched in order:

1. ./config.json
2. ~/.config/mtg/config.json
3. ~/.mtgrc.json

Example config:

{
  "hoursAhead": 12,
  "calendars": {
    "include": null,
    "exclude": ["Birthdays", "US Holidays", "Siri Suggestions"]
  },
  "ignoredEventPatterns": [
    "Focus Time",
    "Lunch",
    "OOO",
    "Out of Office",
    "Blocked",
    "Hold",
    "Tentative"
  ]
}

Integrations

Shell Prompt

Add to .bashrc or .zshrc:

mtg_prompt() {
  mtg --no-color 2>/dev/null || echo ""
}
PS1='$(mtg_prompt) \w $ '

tmux Status Bar

Add to .tmux.conf:

set -g status-right '#(mtg --no-color 2>/dev/null)'

Watch Mode

watch -n 60 mtg --detail

Scripting with JSON

# Get minutes until next meeting
mtg --json | jq '.bufferMinutes'

# Get next meeting title
mtg --json | jq -r '.nextEvent.title'

How It Works

Uses Apple's EventKit framework to read calendar data directly. This is the same data source Calendar.app uses, so any calendars synced there (Google, Exchange, iCloud, etc.) are automatically available.

Fast: ~0.3 seconds (vs 30+ seconds with AppleScript)

Private: All data stays local. No external API calls.

Requirements

• macOS 13.0+
• Calendar access permission (granted on first run)
• Xcode Command Line Tools (for building)

Development

make build      # Build debug version
make release    # Build optimized release
make run        # Build and run
make test       # Run all output modes
make clean      # Clean build artifacts
make help       # Show all targets

License

MIT License - see LICENSE

Contributing

Contributions welcome! See CONTRIBUTING.md