work-plan toolkit

Track-aware work planning for Claude Code and Codex

The work-plan toolkit is a free, MIT-licensed command-line tool and Claude Code / Codex plugin that keeps a live, track-by-track plan of your GitHub issues, so you and your AI agents always know what is in flight, what is blocked and what to pick up next.

It is a pure Python 3.9+ standard-library CLI that re-reads state from gh, git and plain markdown track files on every run, and it ships with a VS Code extension, Work Plan Viewer, that shows the same tracks as a sidebar tree and dependency graph.

Who the work-plan toolkit is for

The work-plan toolkit is for developers who run several AI coding sessions in parallel across many GitHub issues and lose track of which session is doing what.

It is not a Jira, Linear or GitHub Projects replacement. It does not manage sprints, roadmaps or capacity; GitHub stays canonical for issue state.

Key features

The work-plan toolkit turns GitHub issues into tracks and gives each stage of a work session its own command.

Morning snapshot: brief

brief prints a multi-track snapshot of every active track across your configured repos. Run inside a configured repo and it scopes to that repo automatically; --repo=all shows everything.

Fresh-session context: orient

orient <track> (also where-was-i) prints a paste block of about 15 lines with priority, last session, next pick and git state, ready to drop into a new agent session.

End of a work block: handoff

handoff <track> logs what you touched and sets tomorrow's next_up, either by hand with --set-next or algorithmically with --auto-next, which uses no AI.

Next-up ranking presets

set-next-up picks how next-up issues are ranked: flow (milestone, dependency, priority, recency), priority-driven, backlog (oldest first) or a custom order.

Blockers and dependencies

brief and orient mark issues ⊘ blocked by #N from GitHub's native dependency links. A track's depends_on field declares dependencies between tracks.

Weekly cleanup: hygiene

hygiene runs refresh-md, reconcile, dedupe-tiers, milestone-drift and duplicates in one pass so status tables, labels and next-up queues stay honest.

Shared and private tiers

Private tracks live in your local notes_root. Shared tracks live in the repo at .work-plan/, and plan-branch can keep them on one canonical branch.

Diagnostics: doctor

doctor checks Python, git, gh sign-in, mikefarah yq, config and notes_root, then detects config drift after a folder rename or repo move. --fix repairs the safe cases.

Plan and spec liveness: plan-status

plan-status checks each plan document's declared file manifest against git and the filesystem and reports it as shipped, partial, dead, manifest-less or foreign, instead of trusting checkboxes.

Issue and label search

Work Plan Viewer's Search Issues command matches issue titles with % wildcards, and matches GitHub label names with a label: prefix, such as label:priority/%.

How it works

The work-plan toolkit treats GitHub as the source of truth and never mirrors it: track files only reference issue numbers, and every command re-derives the rest live.

  1. Register a repo. work-plan init-repo myproject --github=your-org/myproject adds it to ~/.claude/work-plan/config.yml.
  2. Create tracks. new-track makes one track; group clusters a milestone's issues into tracks with your agent's help; slot adds an issue to a track.
  3. Work the daily rhythm. brief in the morning, orient <track> when you open a session, handoff <track> when you stop, and hygiene once a week.

In Claude Code, the /work-plan skill tells the agent how to run the CLI and to relay the output of brief, handoff, orient and hygiene word for word, so you can copy it into another terminal.

Work Plan Viewer's dependency graph for the track platform-health: next_up arrows to issues #487 and #1556, a depends-on edge to the idea-mode track, and issue #4821 blocking the track. Below it, the detail panel lists issues by milestone with state and assignee, plus blockers, depends-on and next-up chips.
Work Plan Viewer in VS Code: a track's dependency graph and detail panel.

Install

Install the work-plan toolkit as a Claude Code or Codex plugin, as a global npm package, or with the install script; the VS Code extension is a separate install that drives the same CLI.

Claude Code plugin (recommended)

/plugin marketplace add stylusnexus/agent-plugins
/plugin install work-plan@stylus-nexus

Plugin commands are namespaced: /work-plan:brief, /work-plan:handoff, /work-plan:orient, /work-plan:hygiene, /work-plan:status, and /work-plan:run <subcommand> for everything else. Update with /plugin update work-plan@stylus-nexus.

Codex plugin

codex plugin marketplace add stylusnexus/agent-plugins
codex plugin add work-plan@stylus-nexus

Both plugins come from the stylusnexus/agent-plugins marketplace.

npm (standalone CLI for any editor or terminal)

npm install -g @stylusnexus/work-plan

This installs the work-plan command from the @stylusnexus/work-plan npm package. Python, gh and yq must already be on your PATH. The npm package targets macOS and Linux; on Windows, use the install script.

Install script (Cursor, Copilot, direct use)

git clone https://github.com/stylusnexus/work-plan-toolkit.git
cd work-plan-toolkit && ./install.sh   # Windows PowerShell: .\install.ps1

The installer checks for Python 3.9+, gh, git and mikefarah yq first, and seeds ~/.claude/work-plan/config.yml on first run.

VS Code extension: Work Plan Viewer

Install Work Plan Viewer from the VS Code Marketplace or from Open VSX for VSCodium, Cursor and Windsurf, or search for "Work Plan" by publisher stylusnexus.

code --install-extension stylusnexus.work-plan-viewer

The extension needs the CLI installed too. See the Work Plan Viewer page for features and settings.

Requirements

The work-plan CLI needs four tools on your PATH: Python 3.9+, git, the GitHub CLI and mikefarah yq.

Requirements for the work-plan CLI
ToolVersionWhy
Python3.9 or newerRuns the CLI. Standard library only, no pip install step.
gh (GitHub CLI)recent, signed inReads live issue, milestone and label state. Run gh auth login once.
gitany 2.xReads the current branch, commits ahead of upstream and modified files.
yq by mikefarah4.xReads and edits YAML frontmatter and config. The Python yq (kislyuk/yq) is not compatible.

Work Plan Viewer also needs VS Code 1.90.0 or later. Run work-plan doctor at any time to re-check the machine.

Frequently asked questions

What is the work-plan toolkit?

The work-plan toolkit is a free, MIT-licensed command-line tool and Claude Code / Codex plugin for track-aware daily planning over GitHub issues. It groups issues into tracks and tells you and your AI agent what is in flight, what is blocked and what to pick up next.

What is a track?

A track is a markdown file with YAML frontmatter that lists GitHub issue numbers for one workstream, plus fields such as launch_priority, milestone_alignment, next_up, blockers and depends_on. The body holds a session log and a status table that refresh-md keeps in sync with GitHub.

Does the work-plan toolkit work with Codex?

Yes. Install it with codex plugin marketplace add stylusnexus/agent-plugins and then codex plugin add work-plan@stylus-nexus, and invoke it with @work-plan or /skills. The same CLI also runs directly from Cursor, GitHub Copilot or any terminal.

Does it replace Jira, Linear or GitHub Projects?

No. It does not manage sprints, roadmaps or capacity. GitHub stays the source of truth for issues; the toolkit only reads and references them so you and your agent stay oriented.

Does it cache or mirror GitHub data?

No. Every command re-derives state live from gh, git and your track files. There is no daemon, no stored copy of GitHub state and no sync loop, and the toolkit never reads or stores GitHub tokens; it reuses your existing gh auth session.

Does it write to GitHub?

Only when you ask. Issue data comes from read-only gh calls, and routine writes go to local markdown files. Three opt-in, gated commands change GitHub: plan-status --issues creates issues, close-issue closes one, and in-progress adds or removes the work-plan:in-progress label.

What do I need installed?

Python 3.9 or newer, git, the GitHub CLI gh (signed in with gh auth login) and mikefarah yq 4.x, the Go version. The Python yq wrapper does not work. Run work-plan doctor to check the machine and get the fix for anything missing.

Can a team share tracks?

Yes. Shared tracks live inside the repository at .work-plan/<slug>.md and travel with git pull and git push. The plan-branch command can pin them to one canonical branch, by default an orphan work-plan/plan branch, so planning stays out of code branches and pull requests. Private tracks stay in your local notes_root.

Is there a VS Code extension?

Yes. Work Plan Viewer (stylusnexus.work-plan-viewer) is on the VS Code Marketplace and Open VSX. It adds a sidebar tree of repos and tracks, a Mermaid dependency graph, issue search and confirm-gated writes, and it runs the work-plan CLI for every read and write.

Does the CLI call an AI model?

No. The AI-assisted subcommands group, suggest-priorities and auto-triage print a prompt for your agent session, the agent saves a JSON answer, and you re-run the command with --apply. auto-triage --heuristic works offline with no model at all.