🕐 SessionPlanner

This tool helps maximize your Claude Code session duration by opening sessions ahead of time. Starting a session earlier ensures that if you hit a usage limit, the next reset time is already much closer (or has already passed), effectively eliminating idle waiting time.

How it works

Schedule "Hello!" Claude Code sessions at times you choose — opening Claude N hours before each target time. Works as a terminal CLI, an npx one-liner, or a Claude Code plugin.

📦 Available on npm: session-planner

The "Session Hack" Explained

Quick start — terminal / npx (no install needed)

npx session-planner hello 1am
npx session-planner hello 9am 2pm 6pm
npx session-planner hello 14:00 --offset 2h
npx session-planner list
npx session-planner remove 2pm
npx session-planner remove --all
npx session-planner help

Install globally (optional)

npm install -g session-planner
session-planner hello 1am

Install as a Claude Code plugin

/plugin marketplace add MahmoudMabrok/SessionPlanner
/plugin install session-planner@mahmoudmabrok-sessionplanner
/reload-plugins

Then inside Claude Code:

/session-planner:hello 1am
/session-planner:hello 9am 2pm --offset 2h
/session-planner:hello-list
/session-planner:hello-remove 2pm

How it works

npx session-planner hello 1am
        │
        ▼
bin/session-planner.js   (Node.js CLI)
        │
        ▼
scripts/hello-scheduler.sh   (bash)
        │
        ├── Target:   1:00 am
        ├── Offset:   4h (default)
        ├── Session:  9:00 pm  ← cron fires claude here
        │
        └── 0 21 * * *  claude --print "Hello! It is now 1:00 am..."

| Layer | What | Persists after terminal close? | |---|---|---| | cron | claude --print at session time | ✅ Yes | | /loop | In-session reminder (Claude Code only) | ❌ Session-bound |

Time formats

| Input | Means | |---|---| | 1am | 1:00 AM | | 12am | Midnight | | 12pm | Noon | | 2:30pm | 2:30 PM | | 14:30 | 2:30 PM |

Options

| Flag | Default | Description | |---|---|---| | --offset Nh | 4h | Open session N hours before target |

Requirements

| Tool | Required for | Notes | |---|---|---| | Node.js ≥ 14 | npx / global install | nodejs.org | | Claude Code | Scheduling sessions | claude must be in PATH — install | | Bash 4+ | Running the script | Pre-installed on Linux; see below for macOS/Windows | | cron | Persistent scheduling | Built-in on macOS & Linux; not available on Windows |

macOS

Everything is pre-installed

Linux

Install cron if it's not already running:

# Debian / Ubuntu
sudo apt install cron
sudo systemctl enable --now cron

# Fedora / RHEL
sudo dnf install cronie
sudo systemctl enable --now crond

For desktop notifications, install libnotify:

sudo apt install libnotify-bin    # Debian / Ubuntu
sudo dnf install libnotify        # Fedora

Windows

[!WARNING] cron is not available on native Windows. Session scheduling will not work in Git Bash or PowerShell.

Use one of these alternatives:

• WSL (recommended): Install WSL 2 with Ubuntu, then use session-planner inside WSL — cron works normally there.
• Task Scheduler: For advanced users, you can create a Task Scheduler entry manually to run claude --print at your chosen time.

🔐 Permissions (macOS)

To ensure session-planner can schedule jobs and show notifications without prompting every time, grant your terminal (Terminal or iTerm) the following:

1. Full Disk Access: Go to System Settings > Privacy & Security > Full Disk Access and add your terminal. This is required for crontab to save your schedule.
2. Notifications & Sound: The tool uses osascript for visuals, afplay for a sound alert, and say for a voice greeting to ensure you don't miss your session start! Ensure your volume is up.

Logs: ~/.claude/session-planner.log

Repo structure

SessionPlanner/
├── scripts/
│   └── hello-scheduler.sh         ← core scheduling logic
├── commands/
│   └── hello.md                   ← command definition
├── session-planner.js             ← npx / global CLI entry
├── package.json
└── README.md

Publish to npm

npm login
npm publish
# users then run: npx session-planner hello 1am

License

MIT