task-scheduler — Claude Code plugin: what it does, how to install
task-scheduler turns a JSON task list into a day-by-day plan that respects due dates, available hours, blocked dates and overflow, then writes it out as markdown.
MIT ★ 1,596 updated 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install task-scheduler@awesome-codex-pluginsWhat task-scheduler does
Feed it a JSON array of tasks, or an object that carries tasks next to planning metadata. Each task has a title, a due date, an hour estimate, a priority from 1 to 5, and optional tags. The metadata sets the window: start date, number of days, default hours per day, dates with no capacity at all, and per-day overrides. Output is markdown split into Summary, Schedule, Follow-Ups and Risks.
scripts/build_schedule.py gives you a draft from the shell. Flags like --start-date, --days and --hours-per-day win over whatever the input file says. For agent work there is a local stdio MCP server with build_task_schedule, analyze_schedule_capacity and build_task_schedule_from_file, so a caller does not have to shell out. A skill at skills/task-planner/SKILL.md handles the conversational side: it pulls constraints out of the chat and flags risks.
.mcp.json starts the server as python ./scripts/mcp_server.py, so Python has to be present and scripts/requirements-mcp.txt installed beforehand — skip that step and the tools never come up.
What it helps with
- turn a JSON task list into a day-by-day plan
- block a date and see the rest of the week reflow
- find out which tasks overflow the planning window
- call the scheduler from another agent over MCP
- get a markdown draft to edit by hand
Example prompts for the agent
- Build a schedule from
scripts/example_tasks.jsonover the next 6 days - Run the capacity analysis and tell me what overflows
- Plan the week, block Saturday, and cap Monday at 4 hours
How to install task-scheduler
Plugin marketplace
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install task-scheduler@awesome-codex-pluginsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about task-scheduler
How do I install task-scheduler in Claude Code?
Use the marketplace: /plugin marketplace add hashgraph-online/awesome-codex-plugins, then /plugin install task-scheduler@awesome-codex-plugins.
What does task-scheduler do?
It balances deadlines, hour estimates and blocked dates into a per-day schedule and returns markdown that names follow-ups and overflow.
What does the MCP server need to run?
Python plus the packages in scripts/requirements-mcp.txt, installed with python -m pip install -r ./scripts/requirements-mcp.txt; the server itself runs as python ./scripts/mcp_server.py.
Source text
task-scheduler-codex-plugin · MIT
# Task Scheduler for OpenAI Codex
Task Scheduler is an OpenAI Codex plugin that turns raw task lists into realistic schedules.
It combines three pieces in one plugin package:
- a Codex plugin manifest and marketplace-ready metadata
- a reusable MCP server that other agents and tools can call
- a local CLI for generating schedule drafts from structured JSON input
The plugin is designed for practical planning. It balances deadlines, available hours, blocked dates, and per-day capacity changes, then returns a markdown plan with follow-ups and risks.

## Highlights
- Converts task JSON into a day-by-day schedule
- Supports blocked dates and daily capacity overrides
- Tracks overflow when tasks do not fit inside the planning window
- Exposes MCP tools so other agents can call the scheduler directly
- Includes a Codex skill for planning-oriented prompts
- Ships with example assets, sample data, and starter plugin metadata
## Who This Is For
- Codex users who want a local productivity plugin
- plugin authors learning how to combine plugin manifests, skills, and MCP
- teams that want a lightweight planning tool agents can call from the same workspace
## Repository Layout
```text
task-scheduler/
|-- .codex-plugin/
| `-- plugin.json
|-- assets/
| |-- icon.png
| |-- logo.png
| `-- screenshot*.png
|-- hooks/
| `-- README.md
|-- scripts/
| |-- build_schedule.py
| |-- example_tasks.json
| |-- mcp_server.py
| |-- requirements-mcp.txt
| `-- task_scheduler_core.py
|-- skills/
| `-- task-planner/
| `-- SKILL.md
|-- .app.json
|-- .mcp.json
|-- hooks.json
`-- README.md
```
## Features
### 1. Local CLI scheduling
Use the CLI when you want a quick schedule from a JSON file:
```powershell
python .\scripts\build_schedule.py `
--input .\scripts\example_tasks.json
```
Optional flags:
- `--start-date YYYY-MM-DD`
- `--days <int>`
- `--hours-per-day <number>`
- `--output <path>`
These flags override the values inside the JSON input file when present.
### 2. MCP tools for agent workflows
The plugin exposes a local stdio MCP server so other agents and tools can call the scheduler without shelling out directly.
Implemented MCP tools:
- `build_task_schedule`
- `analyze_schedule_capacity`
- `build_task_schedule_from_file`
Implemented MCP resources:
- `task-scheduler://sample-input`
- `task-scheduler://readme`
Implemented MCP prompt:
- `schedule_prompt`
### 3. Codex skill support
The included skill at `skills/task-planner/SKILL.md` helps Codex gather constraints, create a realistic plan, and call out risk and overflow clearly.
## Input Format
The scheduler accepts either:
- a plain JSON array of tasks
- a JSON object containing `tasks` plus planning metadata
### Minimal input
```json
[
{
"title": "Finalize project brief",
"due": "2026-04-03",
"estimated_hours": 2.5,
"priority": 5,
"notes": "Needs stakeholder review"
}
]
```
### Full input
```json
{
"start_date": "2026-04-01",
"days": 6,
"hours_per_day": 6,
"blocked_dates": ["2026-04-04"],
"daily_capacity_overrides": {
"2026-04-03": 3.5,
"2026-04-06": 4
},
"notes": "Protect Saturday for admin catch-up.",
"tasks": [
{
"title": "Finalize project brief",
"due": "2026-04-02",
"estimated_hours": 2,
"priority": 5,
"tags": ["strategy", "stakeholders"],
"notes": "Share with stakeholders before noon."
}
]
}
```
### Supported task fields
- `title`: task name
- `due`: due date in `YYYY-MM-DD`
- `estimated_hours`: expected work in hours
- `priority`: integer from 1 to 5
- `notes`: optional detail shown in output
- `tags`: optional string array for categorization
### Supported schedule metadata
- `start_date`: planning window start
- `days`: number of days in the window
- `hours_per_day`: default daily capacity
- `blocked_dates`: dates with zero scheduling capacity
- `daily_capacity_overrides`: per-day hour overrides
- `notes`: planning context echoed into the output
## Example Output
The generated markdown includes:
- `Summary`
- `Schedule`
- `Follow-Ups`
- `Risks`
This makes it readable for humans and easy for agents to refine.
## Installation
### 1. Clone or copy the repository
This repository is structured with the plugin at the repo root.
```text
task-scheduler-codex-plugin/
```
To use it as a Codex plugin inside another workspace, place this repository or a copy of it under:
```text
plugins/task-scheduler
```
### 2. Install the MCP dependency
```powershell
python -m pip install -r .\scripts\requirements-mcp.txt
```
### 3. Verify the plugin manifest
The manifest lives at:
```text
.codex-plugin/plugin.json
```
This plugin already references:
- `./skills/`
- `./hooks.json`
- `./.mcp.json`
- `./.app.json`
### 4. Verify the MCP config
The MCP config lives at:
```text
.mcp.json
```
It starts the local server with:
```json
{
"mcpServers": {
"taskScheduler": {
"command": "python",
"args": ["./scripts/mcp_server.py"],
"cwd": "."
}
}
}
```
### 5. Optional marketplace registration
If you want the plugin to appear in Codex UI ordering, register it in your marketplace file:
```text
.agents/plugins/marketplace.json
```
This repo already includes a starter marketplace entry.
## Quick Start
### Run the CLI
```powershell
python .\scripts\build_schedule.py `
--input .\scripts\example_tasks.json
```
### Start the MCP server directly
```powershell
python .\scripts\mcp_server.py
```
### Use the example data
Sample input lives at:
```text
scripts/example_tasks.json
```
## Documentation
- [Getting Started](./docs/GETTING_STARTED.md)
- [MCP Reference](./docs/MCP_REFERENCE.md)
- [Architecture](./docs/ARCHITECTURE.md)
- [Development Guide](./docs/DEVELOPMENT.md)
- [Publishing Guide](./docs/PUBLISHING.md)
- [Contributing](./CONTRIBUTING.md)
- [Security Policy](./SECURITY.md)
- [Privacy Policy](./PRIVACY.md)
- [Terms of Service](./TERMS.md)
## Current Status
This plugin is a strong local starter and learning reference. It is already useful for local scheduling and MCP-based planning flows, but a few areas are still intentionally starter-level:
- `.app.json` integration details
- runtime hook registrations in `hooks.json`
- final production screenshots and branding assets
## Roadmap Ideas
- add more MCP tools such as automatic overflow rescheduling
- support recurring tasks and dependency chains
- add export formats beyond markdown
- connect planner output to external task systems
- add repository releases and changelog automation
## License
MIT, unless you choose a different license for your public repository.
© zeyad elsharkawy · MIT · hashgraph-online/awesome-codex-plugins