ICS Manager
Read or edit .ics files from a local path or HTTP(S) URL.
Setup (one-time only)
uv run scripts/check_dependencies.py --install
# Set ICS_SOURCE and optional ICS_RANGE_START/ICS_RANGE_DAYS in .env or ~/.config/ics-manager/.env
Do NOT run check_dependencies.py on every invocation. uv run resolves dependencies automatically. Only run it once during initial setup or when the environment may be broken.
Commands
All operations go through scripts/ics_manager.py:
| Command |
Key flags |
Notes |
list-events |
--source (repeatable), --start, --end, --contains, --format json |
Default window: active configured range, else 14 days |
summarize-hours |
--source (repeatable), --group-by day|week, --contains |
Aggregates event durations across all sources |
overview |
--source (repeatable), --start, --end, --contains, --format json |
Count, total hours, busiest day, per-source counts — use this instead of combining list-events + summarize-hours |
add-event |
--source, --summary, --start, --end |
Local files only |
update-event |
--source, --uid, --summary |
Local files only |
delete-event |
--source, --uid |
Local files only; .bak backup written by default |
Remote URLs are read-only. Use --uid for update/delete.
ICS_SOURCE can contain multiple calendars separated by commas or new lines. You can also repeat --source on read commands:
uv run scripts/ics_manager.py overview \
--source ~/calendar/work.ics \
--source ~/calendar/team.ics
To make Scrum check-ins default to the current sprint window, set these once in .env:
ICS_RANGE_START=2026-05-01
ICS_RANGE_DAYS=14
With that configuration, list-events, overview, and summarize-hours automatically use the active 14-day window starting from the configured anchor. You only need --start or --end when overriding the default sprint window.
Efficiency rules
- One command per task: use
overview when the user asks for a schedule summary or total hours; only call list-events when full event details are needed.
- Never run the same command twice: do not call
list-events --format json followed by list-events in plain format; pick one.
- Prefer configured sprint defaults: when
ICS_RANGE_START/ICS_RANGE_DAYS are set, use that active window without asking for a start date again.
- Skip setup: do not call
check_dependencies.py before each command.
Resources
scripts/ics_manager.py - Parse, summarize, and modify ICS filesreferences/workflows.md - Prompt patterns and caveats.env.example - Environment configuration template
1---2name: ics-manager3description: Manage local or remote ICS calendar sources to inspect upcoming meetings, summarize work hours, and add, update, or delete calendar events when users need a quick operational view of their schedule.4---56# ICS Manager78Read or edit `.ics` files from a local path or HTTP(S) URL.910## Setup (one-time only)1112```bash13uv run scripts/check_dependencies.py --install14# Set ICS_SOURCE and optional ICS_RANGE_START/ICS_RANGE_DAYS in .env or ~/.config/ics-manager/.env15```1617> **Do NOT run `check_dependencies.py` on every invocation.** `uv run` resolves dependencies automatically. Only run it once during initial setup or when the environment may be broken.1819## Commands2021All operations go through `scripts/ics_manager.py`:2223| Command | Key flags | Notes |24|---|---|---|25| `list-events` | `--source` (repeatable), `--start`, `--end`, `--contains`, `--format json` | Default window: active configured range, else 14 days |26| `summarize-hours` | `--source` (repeatable), `--group-by day\|week`, `--contains` | Aggregates event durations across all sources |27| `overview` | `--source` (repeatable), `--start`, `--end`, `--contains`, `--format json` | Count, total hours, busiest day, per-source counts — **use this instead of combining list-events + summarize-hours** |28| `add-event` | `--source`, `--summary`, `--start`, `--end` | Local files only |29| `update-event` | `--source`, `--uid`, `--summary` | Local files only |30| `delete-event` | `--source`, `--uid` | Local files only; `.bak` backup written by default |3132Remote URLs are read-only. Use `--uid` for update/delete.3334`ICS_SOURCE` can contain multiple calendars separated by commas or new lines. You can also repeat `--source` on read commands:3536```bash37uv run scripts/ics_manager.py overview \38 --source ~/calendar/work.ics \39 --source ~/calendar/team.ics40```4142To make Scrum check-ins default to the current sprint window, set these once in `.env`:4344```dotenv45ICS_RANGE_START=2026-05-0146ICS_RANGE_DAYS=1447```4849With that configuration, `list-events`, `overview`, and `summarize-hours` automatically use the active 14-day window starting from the configured anchor. You only need `--start` or `--end` when overriding the default sprint window.5051## Efficiency rules5253- **One command per task**: use `overview` when the user asks for a schedule summary or total hours; only call `list-events` when full event details are needed.54- **Never run the same command twice**: do not call `list-events --format json` followed by `list-events` in plain format; pick one.55- **Prefer configured sprint defaults**: when `ICS_RANGE_START`/`ICS_RANGE_DAYS` are set, use that active window without asking for a start date again.56- **Skip setup**: do not call `check_dependencies.py` before each command.5758## Resources5960- `scripts/ics_manager.py` - Parse, summarize, and modify ICS files61- `references/workflows.md` - Prompt patterns and caveats62- `.env.example` - Environment configuration template
hsiangjenli