Work Graph

Work Graph is a marketplace-free, agent-readable workflow for preserving goals, return paths, dependencies, and investigation evidence across coding sessions. GitHub issues remain authoritative; the included wg command only reads or writes that state and renders disposable orientation views.

Give it to an agent

Point the agent at this repository's SKILL.md and say:

Fetch and follow https://raw.githubusercontent.com/technologylab-ai/work-graph/main/SKILL.md.
Bootstrap this repository into the work-graph model. Inventory and propose the
migration before changing files or GitHub.

For normal work:

Fetch and follow https://raw.githubusercontent.com/technologylab-ai/work-graph/main/SKILL.md,
then orient me to the current work.

Install the optional CLI

Prerequisites

• Git.
• GitHub CLI 2.97 or newer, authenticated with gh auth login.
• uv (recommended). uv downloads and manages a compatible Python version automatically.

Install wg with:

uv tool install git+https://github.com/technologylab-ai/work-graph.git

Alternatively, use pipx with an existing Python 3.9 or newer installation:

pipx install git+https://github.com/technologylab-ai/work-graph.git

The CLI has no third-party runtime dependencies. The wg executable must be on the agent's PATH. Codex project hooks require both a trusted repository and explicit review of each exact command-hook definition.

Then, inside an opted-in repository:

wg init
wg focus ISSUE
wg doctor
wg orient

For Codex, start the CLI, open /hooks, review and trust the three Work Graph hooks, and submit one prompt so SessionStart runs. Rerun wg doctor: static hook wiring and observed runtime activation are reported separately. Changed hook definitions require review again. Claude Code uses its own project-hook approval flow; approve the project hooks when prompted.

wg init creates .work-graph.toml, installs one canonical repo skill at .agents/skills/work-graph, adds a thin Claude adapter at .claude/skills/work-graph, and merges project-scoped hook wiring for both hosts. There are no symlinks. Hook reconciliation removes only Work Graph's exact command handlers and preserves other handlers, even when they share a matcher group. wg doctor detects modified skills and structurally drifted hooks; wg init --refresh-skill refreshes managed skill files from the installed CLI version.

wg focus ISSUE stores only the current branch-to-issue pointer in local Git configuration. It is not committed and does not mirror issue status. The hooks use it when a branch name or pull request does not identify one issue reliably. A live focus switch cannot silently certify new work against the old issue: if the previous lane has uncovered state, checkpoint it before the hook rebinds.

wg init does not create issues or migrate existing trackers; the agent performs that semantic migration after presenting it for approval. Use --hooks or --skills with codex, claude, or none to narrow the default installation.

By default, SessionStart injects the complete root and current issue bodies, return path, blockers, latest valid checkpoint, Git state, and a random session lane. For material Git changes, Stop can continue the agent once with the exact lane-scoped checkpoint command; it then warns and ends rather than looping if the checkpoint was not created. Investigation-only work gets one non-blocking reminder per outstanding checkpoint.

Manual PreCompact blocks while a checkpoint is pending and shows the exact recovery command. Automatic PreCompact warns but proceeds because blocking hard-limit recovery can fail the host request and neither Codex nor Claude Code turns a blocked PreCompact result into an agent continuation. The pending baseline survives post-compaction SessionStart. Set enforcement = "warn" or "off", or set checkpoint_investigations = false, in .work-graph.toml to relax that behavior. Subagents never own the canonical checkpoint.

Hook-satisfying comments contain managed metadata for a stable comment identity, one agent lane, a rotating challenge, and the exact content-sensitive Git fingerprint being certified. Checkpoints from other sessions, unrelated comments, or earlier file contents cannot release the lane. Session caches are separated by repository worktree and are disposable; GitHub remains the only durable work database.

To update an existing installation and its checked-in workflow files:

uv tool install --force git+https://github.com/technologylab-ai/work-graph.git
wg init --refresh-skill
wg doctor

After an update that changes Codex hook definitions, review them again in /hooks.

Core commands

wg orient [ISSUE]              Render root, return path, blockers, children, and checkpoint
wg focus [ISSUE]               Show or set the branch-local current issue
wg focus --clear               Remove the branch-local current issue
wg checkpoint [ISSUE] --lane L --file F
                                  Validate and post a lane-scoped checkpoint
wg checkpoint [ISSUE] --unscoped --file F
                                  Post evidence without satisfying a hook lane
wg doctor                      Check prerequisites, skill drift, hooks, and issue detection
wg init                        Install both project skills and hooks

No marketplace, server, or separate work database is involved.