Skip to main content
Glama

Work Plan (work-plan)

A zero-ops, fully local Antigravity plugin for a single developer managing large, multi-day engineering projects across sequential or concurrent chats — with no backend servers, no external databases, and no runtime dependencies.

Why Work Plan?

  • Large Project Management with Knowledge & Memory Organization: Break complex codebases into persistent dependency-tracked task trees (up to 500 tasks, depth 8) paired with structured Project Memory and portable Knowledge Packs (OKF bundles & single Markdown files).

  • Empirical ~60% Token Savings & 2–3× Time Savings: Eliminates repetitive context re-explaining and redundant repo re-scans across sessions via SHA-deduped [WORK PLAN] turn briefs, progressive-disclosure Knowledge Packs, structured task handoffs, and safe parallel multi-chat execution with live file-edit guards.

Capability

Impact

Large Project Management + Knowledge & Memory

Keep multi-day specs, task DAGs, durable memories, and OKF/Markdown Knowledge Packs organized in one local SQLite WAL store.

~60% Empirical Token Savings

Injects only the focused task brief, upstream handoffs, file-matched memories, and progressive-disclosure KP summaries (SHA-256 deduped per turn).

2–3× Empirical Time Savings

Launch ready tasks in parallel chats with one click while automatic same-folder/worktree edit guards prevent silent overwrites.

Screenshots

Task Tree & Inspector

Task Tree and Inspector

Interactive Dependency Graph

Interactive Dependency Graph

Knowledge & Memory — Memory

Knowledge and Memory — Memory View

Knowledge & Memory — Knowledge Pack (OKF & Single Markdown)

Knowledge and Memory — Knowledge Pack

Live Active-Edits Guard

Live Active-Edits Guard

Related MCP server: ctxfile

Features

  • Persistent Multi-Session Task Tree & Dependency DAG: Hierarchical tasks (up to depth 8, 500 tasks/project) with automatic parent status roll-up, cycle/paradox prevention via dual-node Kahn topological validation, and Ready vs. Waiting filtering.

  • Structured Task-to-Task Handoffs: Record concise handoff_notes when completing a task; downstream chats receive them automatically via task_start and SHA-deduped PreInvocation turn briefs.

  • Automatic Live-Edit Guard: Zero-ceremony PreToolUse + PostToolUse + Stop lifecycle hooks prevent silent same-folder overwrites (force_ask) across parallel Antigravity chats and warn on shared lockfiles/schemas across Git worktrees (ask), clearing locks the instant a turn finishes.

  • Project-Scoped Working Notes: Store decision, gotcha, spec, and note entries alongside the project; pin critical invariants (pinned: true) into turn briefs.

  • Knowledge & Memory (Knowledge & Memory tab: Memory + Knowledge Pack): Combines durable, categorized cross-session Memory cards with a Knowledge Pack (KP) setting supporting both OKF (Open Knowledge Format) bundles (index.md + frontmatter concept files) and single Markdown files (.md), with automatic [WORK PLAN] turn-brief injection and 1-click import/export.

  • Interactive Dual-Mode Aux Pane UI (sidecars/work_plan/ + ui://work-plan/app.html): Ships both an Antigravity Sidecar Aux Pane (sidecars/work_plan/sidecar.json → SIDECAR_UI_ENTRYPOINT_AUX_PANE) for zero-flag out-of-the-box side pane support and a single-file SEP-1865 MCP App (ui://work-plan/app.html) sharing the same local SQLite WAL store. Features a responsive master-detail Task Tree + Inspector, interactive left-to-right SVG Dependency Graph with hover tooltips, Notes manager, Knowledge & Memory tab, Active Edits tab, built-in Light / Dark theme toggle, and one-click Run in New Chat / Run Next Ready.

Knowledge & Memory

The Knowledge & Memory tab includes a Memory | Knowledge Pack sub-switch and a persistent Knowledge Pack status bar:

  • Memory: Store durable, categorized project knowledge (architecture, convention, command, constraint, pitfall, context, fact) with idempotent key upserts, always / file-matched on_demand / disabled injection modes, confidence tracking (confirmed, inferred, stale), 1-click Markdown export, and agent repo scanning.

  • Knowledge Pack (KP): Link a portable, git-native knowledge source on disk via Browse Folder… or Browse .md…:

    • OKF (Open Knowledge Format) Bundle: Point to an OKF directory or its root index.md (with okf_version frontmatter and Markdown links to concept .md files carrying YAML frontmatter type, title, description, resource, tags, files).

    • Single Markdown File: Point to any standalone .md file (e.g., KNOWLEDGE.md, AGENTS.md, ARCHITECTURE.md) to parse its headings and sections.

    • Auto-Injection & 1-Click Sync: Active KPs automatically inject progressive-disclosure summaries (prioritizing concepts/sections matching the bound task's files) into [WORK PLAN] turn briefs. Use ⬇ Import KP to Memory (or per-card + To Memory) to pull items into Memory, or ⬆ Export Memory as OKF / ⬆ Export Memory as .md to write your Memory cards out to disk as a standards-compliant OKF v0.2 bundle (index.md, <category>/<slug>.md, log.md) or a single Markdown file.

Before vs. After (Why ~60% Token Savings & 2–3× Speed)

Managing a large codebase across multiple AI coding agent chats usually breaks down because every new conversation starts cold:

Workflow Pain Point

Without Work Plan

With Work Plan

Starting a new chat on a large codebase

Re-paste architecture docs, re-read 5–10 files, and re-explain project conventions every session.

SHA-256-deduped [WORK PLAN] brief injects only the bound task, upstream handoff_notes, file-matched memories, and progressive-disclosure OKF / Markdown Knowledge Pack summaries.

Multi-day task tracking & dependencies

Lost in long chat scrollback or stale TODO lists; hard to tell what is blocked vs. ready next.

Persistent SQLite task tree + DAG (Ready / Waiting badges, interactive SVG graph, automatic parent roll-up).

Running parallel AI coding sessions

Concurrent chats silently overwrite the same files or clash on package.json / schemas across worktrees.

Automatic PreToolUse / PostToolUse / Stop live-edit guards catch same-folder (force_ask) and cross-worktree (ask) collisions in real time, letting you safely run 2–3 tasks in parallel.

Installation (Antigravity)

Clone this repository directly into Antigravity's global plugins folder (no npm install or build step required for end users because ui/app.html is pre-bundled):

git clone https://github.com/minyaozhu/work-plan.git ~/.gemini/config/plugins/work-plan

Once installed:

  • Open Work Plan from the conversation side pane + menu, or ask the agent "Open Work Plan" to receive a one-click [Work Plan](sidecar://work-plan/work_plan/) pill.

  • If the plugin was already loaded before updating, toggle work-plan off and back on in Customizations (or restart Antigravity) to reload the aux pane.

Try It in 10 Seconds (Examples & Local Browser Preview)

This repository ships ready-to-use samples in examples/:

  • examples/PLAN.md — seed a multi-phase project immediately via + New Project → Markdown plan.

  • examples/okf-knowledge-pack/ — link a standards-compliant OKF v0.2 bundle in Knowledge & Memory → Knowledge Pack.

  • Want to preview the UI in any browser without Antigravity? Run:

npm run start:sidecar
# open http://127.0.0.1:8765

Requirements

  • Node.js >= 22.5 (for built-in node:sqlite WAL storage), or Antigravity's bundled agy-node fallback (bin/run.mjs detects and re-execs automatically).

  • Optional: git (for canonical repo/worktree normalization and branch metadata) and gh CLI (for seeding from GitHub issue URLs).

MCP Tools

  • Agent tools: project_list, project_create, project_get, task_plan, task_start, task_update, note_save, note_list, memory_save, memory_list, memory_delete

  • UI entrypoints: open_work_plan (aux_pane and global MCP App views) + sidecars/work_plan/ (SIDECAR_UI_ENTRYPOINT_AUX_PANE at /)

  • App-only UI tools (visibility: ["app"]): ui_get_state, ui_select_project, ui_bind_conversation, ui_create_project, ui_update_project, ui_archive_project, ui_delete_project, ui_create_task, ui_update_task, ui_move_task, ui_delete_task, ui_set_dep, ui_save_note, ui_delete_note, ui_save_memory, ui_delete_memory, ui_clear_active_edit, ui_browse_dir

Lifecycle Hooks (hooks.json)

  • PreToolUse (pre-edit): Fast-exits outside workspace / os.tmpdir() / ~/.gemini/; checks active sibling edits (force_ask on same-folder collision, ask on cross-worktree shared manifests/schemas).

  • PostToolUse (post-edit, post-mcp, post-command): Records approved edit locks, binds conversations to tasks after task_start/project_create, and opportunistically records branch_name / pr_url.

  • PreInvocation (pre-invocation): Injects SHA-256-deduped [WORK PLAN] brief (<40 ms p95).

  • Stop (stop): Immediately clears ActiveEdits locks held by the finished conversation.

Development & Verification

npm install          # installs devDependencies only (esbuild + @modelcontextprotocol/ext-apps)
npm run build:ui     # bundles ui/src/* -> self-contained ui/app.html
npm run start:sidecar # optional standalone preview at http://127.0.0.1:8765
npm test             # runs core, MCP/hooks E2E, sidecar, and UI test suites

License

MIT

Available Tools

30 tools
memory_deleteC

Delete a project memory entry by memory_id or key.

Inputs: key, memory_id, project_id.

memory_listC

Search or filter durable project memories (always-injected and confirmed entries ranked first).

Inputs: tag, query, category, file_path, +3 more.

memory_saveC

Save or idempotently update a durable cross-session project memory (architecture, convention, command, constraint, pitfall, context, or fact).

Inputs: title (required), content (required), key, tags, +6 more.

note_listA

Search or filter working notes for a project (pinned and task-scoped notes ranked first).

Inputs: kind, query, task_id, project_id.

note_saveA

Save or update a project-scoped working note (decision, gotcha, spec, or note) persisted across conversations for this project.

Inputs: title (required), body_markdown (required), kind, pinned, +3 more.

open_work_planC

Open the interactive Work Plan task tree, dependency graph, and notes board.

Inputs: project_id.

project_createB

Create a new Work Plan project and optionally seed tasks from a local Markdown plan, folder subdirectories, or GitHub issue URL.

Inputs: seed, title, kp_mode, kp_path, +2 more.

project_getB

Read the project task tree, ready/waiting status, active sibling chats/files, upstream handoff_notes, and pinned notes.

Inputs: task_id, project_id, include_notes.

project_listA

List local Work Plan projects with task progress counts, active chats, and workspace folder.

Inputs: include_archived.

task_planA

Idempotently create, update, or reorganize recursive tasks (task_id?, title, brief, files, target_tests, children) and depends_on edges ([upstream, downstream]).

Inputs: tasks (required), depends_on, project_id, parent_task_id.

task_startA

Start working on a task in this conversation: marks IN_PROGRESS, binds the conversation, and returns brief, upstream handoff_notes, active-file warnings, and optional git worktree command.

Inputs: task_id (required), project_id, branch_name, worktree_path.

task_updateC

Advance task status (TODO, IN_PROGRESS, BLOCKED, IN_REVIEW, DONE, CANCELLED), attach concise handoff_notes for downstream chats, or record optional branch/PR metadata.

Inputs: task_id (required), brief, files, title, +6 more.

ui_archive_projectC

App-only: archive or unarchive a project.

Inputs: project_id (required), archived.

ui_bind_conversationC

App-only: pre-bind a newly launched conversationId to a task.

Inputs: conv_id (required), project_id (required), task_id, workspace_dir.

ui_browse_dirC

App-only: browse local directories and files for the UI path picker.

Inputs: path, query, extensions, include_files, +1 more.

ui_clear_active_editC

App-only: clear a stale active-edit lock row.

Inputs: conv_id (required), repo_id, file_path, project_id, +1 more.

ui_create_projectC

App-only: create a new project from the UI modal.

Inputs: seed, title, source_ref, workspace_dir.

ui_create_taskB

App-only: create a task or sub-task from the UI.

Inputs: title (required), project_id (required), brief, files, +2 more.

ui_delete_memoryC

App-only: delete a project memory entry from the UI.

Inputs: memory_id (required), project_id (required).

ui_delete_noteC

App-only: delete a project note.

Inputs: note_id (required), project_id (required).

ui_delete_projectC

App-only: permanently delete a project.

Inputs: project_id (required).

ui_delete_taskB

App-only: delete a task (and optionally its subtree).

Inputs: task_id (required), project_id (required), cascade.

ui_get_stateC

App-only: fetch full UI snapshot for projects and active project.

Inputs: project_id, include_archived.

ui_move_taskC

App-only: reparent or reorder a task.

Inputs: task_id (required), project_id (required), sort_key, new_parent_id.

ui_save_memoryC

App-only: create or update a project memory entry from the UI.

Inputs: title (required), content (required), project_id (required), key, +7 more.

ui_save_noteC

App-only: create or update a project/task note from the UI.

Inputs: title (required), project_id (required), body_markdown (required), kind, +3 more.

ui_select_projectC

App-only: switch active project in the UI.

Inputs: project_id (required).

ui_set_depC

App-only: add or remove a dependency edge between tasks.

Inputs: project_id (required), upstream_id (required), downstream_id (required), action.

ui_update_projectC

App-only: rename, pin, update project workspace/source, or configure/sync Knowledge Pack (KP).

Inputs: project_id (required), title, pinned, kp_mode, +6 more.

ui_update_taskC

App-only: update task fields, status, manual_status, or handoff_notes.

Inputs: task_id (required), project_id (required), brief, files, +7 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.6/5.0

    Scored across 30 tools

    Disambiguation2/5

    The set is split into a core agent-facing API and a parallel `ui_*` app-facing API that duplicates much of it: `ui_create_task` vs `task_plan`, `ui_update_task` vs `task_update`, `ui_save_note` vs `note_save`, `ui_save_memory` vs `memory_save`, and `ui_delete_memory` vs `memory_delete`. The 'App-only' labels help somewhat, but an agent still faces several near-identical operations and must infer which layer to use.

    Naming Consistency3/5

    All names are snake_case and resource-prefixed, but the convention shifts between noun_verb (`project_list`, `task_start`, `note_save`, `memory_delete`) and `ui_` + verb_noun (`ui_move_task`, `ui_delete_project`). The `ui_` prefix is consistently applied to app-only tools, which keeps it readable despite the mixed verb placement.

    Tool Count2/5

    30 tools is heavy for a project/task planning server, and roughly half are `ui_*` wrappers duplicating core operations. The effective agent-facing surface is around 15 tools, so many entries do not earn independent places in the set.

    Completeness3/5

    Core lifecycle is covered for projects (list/get/create), tasks (plan/start/update), notes (save/list), and memory (save/list/delete), plus an open-UI tool. However, project update/archive/delete, task deletion, and note deletion exist only as App-only tools, and there is no core task get/delete, leaving notable gaps for agent-driven workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Local-first MCP server that gives any AI coding agent per-project memory, workflow intelligence, and always-on, lossless token & context optimization.
      37
      31 npm
      6
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A local-first MCP server that snapshots project working state into a structured context object, enabling agents to share and resume sessions seamlessly without leaving your machine.
      6
      5
      Apache 2.0