wk — files-first project management

wk is project management that lives in a folder you own. Projects, open questions, loose ends and work history are plain markdown files in a git repo on your machine — the "work repo". The extension puts a sidebar over those files; it never locks them away. Everything stays readable, editable, greppable and diffable with any tool, forever, whether or not the extension is installed.

If you use Claude Code, wk also connects the two: sessions show up live in the sidebar attached to the project they're working on, buttons hand work to Claude with the right context, and Claude reads and writes the same markdown files under rules it understands. Without Claude, the sidebar is a fast read-only view over your notes with light management commands — everything else still works.

The sidebar

• Now — live Claude Code sessions, grouped under the project each is working on, with the project's open questions, pending migrations and backlog directly underneath.
• Next — planned projects in priority order (priority, then size, then age), the answer to "what should I pick up next?".
• All Projects — every book, every project, current and archived.
• Questions — open questions from every current project's QUESTIONS.md, in one place.
• Remember — the things that otherwise get lost: loose ends (deliberate temporary hacks that must be undone), pending live migrations, and questions waiting on someone else.

Getting started (60 seconds)

1. Install the extension.
2. Open the wk sidebar. With no work repo yet, every view offers Start tracking work — it creates a work repo (default ~/work, or anywhere you choose), writes a starter repos.yml and a getting-started project, and runs git init for you. No git knowledge needed, no remote needed.
3. That's it. Add projects with the + button (or ask Claude to start one).

Already keeping notes in a folder? Use Use an existing folder instead, or set the work.repoPath setting.

The work repo

The work repo is an ordinary git repo of markdown files. At its top level, one directory per book — a broad area of work, usually mapping to a codebase — declared in repos.yml:

version: 1          # optional
repos:
  shop:             # book name = its directory name in the work repo
    title: Web Shop           # optional display name
    paths:                    # optional - where that codebase is checked out
      - /home/me/src/shop
  infra: {}         # no paths: a "virtual" book - registers and notes, no code checkout

That is the whole schema: repos: maps book name → { title?, paths? }. A missing or empty paths means a virtual book. Unknown top-level keys are ignored.

Within a book, a project is a directory in one of three lifecycle stages — current/ (being worked), planned/ (agreed someday-work) or archive/<year>/ (done) — holding:

• project.yml — name, title, status, icon, priority/size/tags for the Next view
• README.md — what the project is, where it stands, what's next (kept current, not appended to)
• HISTORY.md — dated prose: what changed and why
• QUESTIONS.md and OUTSTANDING.md — numbered registers of open questions and loose ends, where an entry's status lives in a small stamped meta line (Raised, Waiting on:, Answered, …)
• optionally BACKLOG.md, research/, migrations/pending|applied/

By convention (Claude follows it, and you can too) a book can also hold an inbox/ for raw braindumps awaiting triage and a reference/ for durable how-tos — plain folders, created when first needed. The sidebar reads everything directly off disk — there is no database and no index to corrupt.

Claude Code integration

Run wk: Set Up Claude Integration (also offered once, unobtrusively, when Claude Code and a work repo are both present). It does four concrete things:

1. Copies the bundled hook script and its library to ~/.claude/wk/ (a stable home that survives extension updates), plus a config.json listing your work repos.
2. Backs up ~/.claude/settings.json to settings.json.wk-backup (once, only if no backup exists), then merges four hook entries into it — SessionStart, PostToolUse (file edits), Stop, SessionEnd — each running ~/.claude/wk/hooks.js. Your other hooks are left untouched.
3. Installs the work skill to ~/.claude/skills/work/SKILL.md, which teaches Claude the file formats and the bookkeeping rules (register the session against a project, record history, add Project: trailers to commits, keep the README current).
4. On later extension updates, quietly refreshes those copies when the bundled version is newer.

What the hooks record: a small JSON row per session under <work repo>/.state/sessions/ (which project it's attached to, when it was last seen, which files it touched), an append-only activity log, and — on session end — an auto-commit of anything left uncommitted in the work repo, plus a sync with its remote if it has one. The hooks fast-exit for sessions outside your registered work repos and codebases, and are written to never break a session: any failure degrades to doing nothing.

wk: Check Setup opens a report of the whole chain — repo, git state, hooks, settings entries, skill, Claude extension — with what's wrong and how to fix it.

No Claude? Skip all of the above. The sidebar, projects, registers and planning views work the same; only the session tracking and the hand-to-Claude buttons need Claude Code.

Syncing between machines

The work repo is plain git, so syncing is a remote: create an empty private repo anywhere (GitHub, GitLab, a bare repo on a server you own) and run wk: Connect Work Repo to a Remote…. After that the session-end hook pushes as part of its auto-commit, and other machines pick changes up with a normal pull (the session-start hook pulls when an upstream is configured). No remote is required — a purely local work repo is fully supported.

Settings

• work.repoPath — path of the work repo (set for you by Start tracking work). Empty tries work/ then .work/ inside each workspace folder, then any repo already registered in ~/.claude/wk/config.json.
• work.activeBook — which book this window is for (drives the Next view's ordering); empty infers it from the workspace folders.
• work.handoff — whether Work on this in Claude opens the chat panel (instructions arrive invisibly via the hooks at session start; the prompt is only pre-filled as a fallback when the hooks aren't set up) or a terminal running the CLI.
• work.liveWindowMinutes — how recently a session must have been seen to count as live.

Notes

• Windows is not supported. The extension and hooks assume a POSIX environment (Linux, macOS, WSL, dev containers, remote SSH); on native Windows they will stay quiet rather than misbehave, but nothing will work.
• Not affiliated with Anthropic. Claude is a trademark of Anthropic, PBC.
• MIT licensed.