Skip to main content
plugin CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install task-scheduler@awesome-codex-plugins
Open on GitHub

What 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.json over 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-plugins

Step 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.

![Task Scheduler logo](./assets/logo.png)

## 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

Similar plugins

All plugins for Notes, tasks and projects →

From the same set391

The whole set →
tokrepo-search The tokrepo-search plugin for Claude Code searches TokRepo for installable skills, prompts, MCP configs, and workflows. It bundles a skill and an MCP server. CX Codex ★ 1,596repo stars tokenchronicle tokenchronicle stores your work history in a local archive so you can search past sessions, track token usage, and resume interrupted work without rerunning costly prompts. CX Codex ★ 1,596repo stars thermal-fluid-research-workflow The thermal-fluid-research-workflow plugin for Claude Code and Codex checks CFD calculations and uncertainty and supports manuscript preparation for thermal-fluid research. CX Codex ★ 1,596repo stars teaching-skills teaching-skills is a Claude Code plugin for course design, lesson planning, and assessment. Its router selects from 15 workflows based on the request. CX Codex ★ 1,596repo stars talivia-agent-kit talivia-agent-kit integrates Talivia analytics via Claude Code, letting the agent embed the tracker for your framework, test incoming events, and tie traffic to revenue. CX Codex ★ 1,596repo stars taisly-agent-kit The taisly-agent-kit plugin gives agents Taisly posting tools and a guided social media workflow. Use it to check connected accounts and publish short videos after confirming the post. CX Codex ★ 1,596repo stars tablejourney The plugin wires TableJourney's food travel data into Claude Code: checked places to eat, food festival dates and ready-made itineraries across 200+ cities. CX Codex ★ 1,596repo stars sysknife sysknife turns plain-English sysadmin requests into typed Linux actions with risk ratings. Runs operations through a privileged daemon only after explicit terminal approval. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open