session-planner

🕐 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

!session_planner_hack_infographic_1775344203921 !session_planner_hack_final_illustration_1775343574461

---

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