Daily Work Planner

简体中文 | English

A portable work-session preflight system for Codex and other local agents.

Turn scattered files, vague tasks, current-window notes, repo TODOs, and deadlines into a focused work session with milestones, acceptance criteria, buffers, checkpoints, handoff notes, and local memory.

Why This Exists

Most work does not start cleanly. You may know that you need to read papers, revise a Word document, finish a report, debug code, prepare slides, or clean up a repository, but not know what to do first, how long it will take, or what to protect if time runs out.

Daily Work Planner is built for that exact moment before execution begins.

It is not a calendar app and it is not a generic daily todo list. It answers three practical questions:

Core Rule

Planning should accelerate execution. Daily Work Planner limits the planning step to at most 5% of the available work time, with a hard cap:

If the budget is small, the skill creates a minimal plan instead of asking many questions.

Quick Start Case

Suppose you are about to prepare a 5-minute paper-sharing talk and only know the current tasks:

Read two paper abstracts
Draft a 6-slide outline
Create a 5-minute talk checklist

Run the planner without giving a duration:

python -m daily_work_planner start --goal "Prepare a 5-minute paper-sharing talk from two papers" --start 09:00 --window-note "Read two paper abstracts`nDraft a 6-slide outline`nCreate a 5-minute talk checklist" --speed normal --output-dir .\work-session

Daily Work Planner estimates the session and turns that into a concrete plan:

During the session:

python -m daily_work_planner checkpoint --session .\work-session\session.json --now 10:15 --done "Read two paper abstracts" --remaining "Draft a 6-slide outline" --remaining "Create a 5-minute talk checklist"

The checkpoint reports whether the delay is light, medium, or severe, then recommends whether to compress buffer, drop optional scope, or switch to the minimum deliverable. Later, resume tells the user where to continue, and handoff --remember records planned-vs-actual timing for future estimates.

See the full walkthrough: examples/quick-start-case.md.

How It Works

flowchart LR
    A["Goal, files, repo tasks, window notes"] --> B["Task inspection"]
    B --> C["Duration estimate"]
    C --> D["Feasibility score"]
    D --> E["Session plan"]
    E --> F["Checkpoint"]
    F --> G["Resume or reschedule"]
    G --> H["Handoff"]
    H --> I["Local memory"]

Feature Map

Work Modes

Use Cases

Output Package

By default, one start command writes a compact package:

The plan itself can include:

Use --split-files when you also want separate helper files such as session_plan.md, file_context.md, file_priority.md, todo.txt, and plan_validation.md.

Agent Compatibility

This repository now has two agent entrypoints:

For agents that do not have a formal skill system, install this repository as a portable folder and point the agent to daily-work-planner/AGENTS.md. If the agent supports local tools, allow it to run Python scripts from daily-work-planner/scripts/.

Repository Structure

daily-work-planner/
  AGENTS.md
  README.md
  README.zh-CN.md
  install.ps1
  install.sh
  LICENSE
  .gitignore
  pyproject.toml
  .github/
    workflows/
      tests.yml
  examples/
  daily-work-planner/
    AGENTS.md
    SKILL.md
    agents/
      openai.yaml
    scripts/
      plan_day.py
      inspect_tasks.py
      feasibility_score.py
      extract_file_context.py
      classify_work_mode.py
      rank_files.py
      validate_plan.py
      start_session.py
      report_writer.py
      make_todo.py
      make_ics.py
      update_review_log.py
      reschedule_session.py
      checkpoint_session.py
      resume_session.py
      handoff_session.py
      estimate_profile.py
      session_state.py
      task_memory.py
    schemas/
      session.schema.json
    references/
      planning_rules.md
      work_modes.md
      reschedule_rules.md
      privacy_rules.md
      memory_rules.md
    assets/
      daily_plan_template.md
      review_log_template.md
  tests/

The inner daily-work-planner/ folder is both the installable skill folder and the canonical CLI source. Codex reads SKILL.md; generic agents can read AGENTS.md; packaging maps daily-work-planner/scripts/ to the daily_work_planner Python package.

Installation

Option 1: Ask Codex To Install From GitHub

In Codex, ask:

Install this skill: https://github.com/Stephen-studying/daily-work-planner/tree/main/daily-work-planner

Restart Codex after installation.

Option 2: Clone And Install For Codex

Windows PowerShell:

git clone https://github.com/Stephen-studying/daily-work-planner.git
cd daily-work-planner
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Agent codex -Force

macOS / Linux:

git clone https://github.com/Stephen-studying/daily-work-planner.git
cd daily-work-planner
sh ./install.sh --agent codex --force

The installer copies the inner skill folder to:

• Windows default: %USERPROFILE%\.codex\skills\daily-work-planner
• macOS/Linux default: ~/.codex/skills/daily-work-planner
• If CODEX_HOME is set: $CODEX_HOME/skills/daily-work-planner

Option 3: Install For Claude Code, Gemini CLI, Or Another Agent

Named installers use each client's automatically discovered user skill directory:

macOS / Linux:

sh ./install.sh --agent claude --force
sh ./install.sh --agent gemini --force
sh ./install.sh --agent generic --force

Use -Destination / --dest to override a location. Generic clients can read either entrypoint:

You can also set AGENT_SKILLS_HOME and omit -Destination / --dest.

Verify Installation

Windows PowerShell:

Test-Path "$env:USERPROFILE\.codex\skills\daily-work-planner\SKILL.md"

Then restart Codex and try:

Use $daily-work-planner to plan my next 2-hour work session.

Optional CLI Setup

From the cloned repository, install the CLI as a normal package or in editable mode:

python -m pip install .
python -m daily_work_planner --help
python -m daily_work_planner --version

For stronger PDF text extraction, install the optional PDF extra: python -m pip install ".[pdf]". For named IANA timezones on systems without a timezone database, install python -m pip install ".[calendar]"; local, UTC, and floating need no extra package.

Example Prompt

Use $daily-work-planner to plan my 14:00-18:00 work session.
Goal: read two PDFs and create a 1500-word Chinese presentation outline.
Hard deadline: 18:00.
Soft deadline: 17:00.
Files: paper1.pdf, paper2.pdf, notes.docx.

Script Usage

Use the unified CLI:

python -m daily_work_planner --help
python -m daily_work_planner start --goal "Read two papers and draft an outline" --start 14:00 --minutes 240 --hard-deadline 18:00 .\paper1.pdf .\notes.docx --output-dir .\work-session
python -m daily_work_planner session status --session .\work-session\session.json

Inspect open tasks and estimate required time:

python -m daily_work_planner inspect --repo . --goal "Finish the current repo cleanup" --speed normal
python -m daily_work_planner inspect --window-note "Fix login bug`nUpdate README`nRun tests" --goal "Finish current coding task"

Start a session without providing --minutes; the planner estimates the duration:

python -m daily_work_planner start --goal "Finish current coding task" --start 09:00 --scan-repo --repo . --speed normal --output-dir .\work-session

When --hard-deadline is present but --minutes is omitted, the deadline window becomes the actual available time. The required-time estimate remains separate and drives complete/deliverable/minimum/defer feasibility.

Score feasibility before committing to a time box:

python -m daily_work_planner feasibility --goal "Finish the final report" --available-minutes 90 --estimated-minutes 150 --mode writing

The default start package writes:

• work_session.txt
• work_session.docx
• session.ics
• session.json

Use --split-files when you also want separate helper files such as session_plan.md, file_context.md, file_priority.md, todo.txt, and plan_validation.md.

Use review history to adapt buffer:

python -m daily_work_planner start --goal "Build final deck" --start 09:00 --minutes 180 --hard-deadline 12:00 --profile-log .\review-log.md --output-dir .\work-session

Record a checkpoint during execution:

python -m daily_work_planner checkpoint --session .\work-session\session.json --now 10:30 --done "Updated README" --remaining "Run tests" --remaining "Commit changes"

Resume a previous unfinished session:

python -m daily_work_planner resume --session .\work-session\session.json

Create an end-of-session handoff:

python -m daily_work_planner handoff --session .\work-session\session.json --completed "Updated task inspection" --remaining "Publish v1.3 tag" --actual-minutes 145 --remember

Record local task memory after finishing:

python -m daily_work_planner remember --session .\work-session\session.json --actual-minutes 145 --completed "Generated consolidated session report" --habit "Coding cleanup usually needs an extra test pass"

By default this writes .daily-work-planner/memory.jsonl and .daily-work-planner/MEMORY.md. The folder is ignored by Git because it may contain personal work habits.

Manage private memory without editing JSONL manually:

python -m daily_work_planner remember --list
python -m daily_work_planner remember --forget-id ENTRY_ID
python -m daily_work_planner remember --purge-before 2026-01-01
python -m daily_work_planner remember --export .\private-memory-export.json

Extract lightweight context from local files:

python .\daily-work-planner\scripts\extract_file_context.py .\paper1.pdf .\notes.docx .\slides.pptx .\data.xlsx .\src --recursive --max-files 20 --max-chars 1200 --format markdown

Classify work mode:

python .\daily-work-planner\scripts\classify_work_mode.py --goal "Fix the login bug and run tests" .\src\auth.py .\tests\test_auth.py

Rank files:

python .\daily-work-planner\scripts\rank_files.py --goal "Revise final report before submission" .\report.docx .\rubric.pdf .\notes.md

Generate a Markdown plan:

python .\daily-work-planner\scripts\plan_day.py --start 14:00 --minutes 240 --goal "Read two papers and draft an outline" --mode reading --hard-deadline 18:00

Validate a plan:

python .\daily-work-planner\scripts\validate_plan.py --plan .\work-session\session_plan.md --available-minutes 240

Create todo entries from a plan:

python .\daily-work-planner\scripts\make_todo.py --plan .\work-session\session_plan.md --output .\work-session\todo.txt

Create an .ics calendar event:

python .\daily-work-planner\scripts\make_ics.py --title "Paper reading session" --start 2026-06-13T14:00 --end 2026-06-13T18:00 --description "Read papers and draft outline" --alarm-minutes 10 --output session.ics

Reschedule after checkpoint slippage:

python .\daily-work-planner\scripts\reschedule_session.py --goal "Finish the presentation outline" --now 15:40 --hard-deadline 18:00 --minutes-late 25 --mode reading
python .\daily-work-planner\scripts\reschedule_session.py --session .\work-session\session.json --now 15:40 --minutes-late 25 --output .\work-session\rescheduled_plan.md

Append a review-log entry:

python .\daily-work-planner\scripts\update_review_log.py --log review-log.md --goal "Read papers" --planned-minutes 240 --actual-minutes 260 --delay-reason "PDF reading took longer than expected" --next-adjustment "Add 10 percent buffer for dense PDFs"

Build an estimation profile:

python .\daily-work-planner\scripts\estimate_profile.py .\review-log.md

Privacy Model

Daily Work Planner is local-first by default:

• It does not upload user files by itself.
• It does not store full documents, papers, code, or current-window raw text in memory.
• Local memory bounds and redacts free-text fields, stores filenames instead of full paths, and supports list, forget, retention, purge, and export operations.
• .daily-work-planner/ is ignored by Git because it may contain personal working patterns.

Roadmap Ideas

• OCR adapters for scanned PDFs and optional legacy Office conversion.
• Optional GUI wrapper for non-terminal users.
• P50/P80 duration ranges and dependency-aware critical-path planning.
• More work-mode templates for lab work, literature review, grant writing, and interview prep.
• Bidirectional calendar and task-manager adapters with explicit user authorization.

Non-Goals

This skill does not try to:

• Replace calendar software
• Replace long-term project management tools
• Fully summarize every source file during planning
• Read large files deeply before the user begins work
• Produce a plan so detailed that it delays execution

Contributing And Security

See CONTRIBUTING.md for development and test expectations, SECURITY.md for private vulnerability reporting, and CHANGELOG.md for release history.

License

MIT License.