Hermes Agent - Calendar Skill

Read calendar events from Nextcloud instances via CalDAV. Supports own and shared calendars.

Features

• List own and shared calendars
• Read events from own or shared calendars
• Create new events
• JSON output for seamless Hermes Agent integration

Installation

# Clone this repo
git clone <repo-url> ~/git/hermes-tools
cd ~/git/hermes-tools/calendar

# Install dependencies
pip install -r scripts/requirements.txt

# Copy to Hermes skills directory
cp -r scripts ~/.hermes/skills/calendar/

# Run setup
python3 ~/.hermes/skills/calendar/scripts/setup.py

Setup

The setup script prompts for:

1. Nextcloud URL (no trailing slash)
2. Username
3. App Password (create one at Settings → Security → App passwords)

Credentials are saved to ~/.hermes/calendar.env (mode 600).

Alternatively, set environment variables manually:

export NEXTCLOUD_URL="https://nextcloud.example.com"
export NEXTCLOUD_USER="your_username"
export NEXTCLOUD_TOKEN="your-app-password"

Usage

CALENDAR="python3 ~/.hermes/skills/calendar/scripts/calendar.py"

# Verify connection
$CALENDAR check

# List calendars (own + shared)
$CALENDAR list

# List events from your calendar
$CALENDAR list-events
$CALENDAR list-events --calendar "Work"
$CALENDAR list-events --from "2026-07-01T00:00:00Z" --to "2026-07-07T23:59:59Z"

# List events from a shared calendar
$CALENDAR shared-events --share-url "https://nextcloud/remote.php/dav/calendars/owner/calendar-id"

# Create event
$CALENDAR create --summary "Team Standup" --start "2026-07-01T09:00:00Z" --end "2026-07-01T09:30:00Z" --location "Office"

Output

All commands return JSON:

{"status": "success", "data": [...]}
{"status": "error", "message": "..."}

Hermes Agent Integration

This is a Hermes Agent skill. The skill.md file in the calendar/ directory tells the agent what this tool can do.

License

MIT