HJewkes/active-work

active-work

Durable per-initiative workspace state for engineering work — a CLI, an MCP server, an HTTP daemon, a read-only dashboard, and a Claude skill, all in one npm package, so Claude Code sessions can pick up cleanly across days, machines, and contexts.

Overview

Engineering work spans days or weeks; Claude Code sessions don't. A typical week has handoffs between sessions, between machines, between agents — and every handoff loses context unless something durable holds it. active-work is that something. It keeps a small set of plain files per initiative (a brief, a handoff note, tasks, session summaries, tracked artifacts) under $XDGDATAHOME/active-work/<slug/, and exposes those files through a CLI (active-work), an MCP server, an HTTP daemon, and a Claude skill so that any of those surfaces can read or write the same source of truth.

The headline feature is aw <slug — a one-shot launcher that assembles the bootstrap prompt (brief excerpt, full handoff, last session summary, top open tasks, open artifacts, time since last session) and execs claude with the initiative's worktree as cwd. Everything Claude needs to resume work, in one command. The underlying prompt is also available via active-work open <slug for callers that want to handle the spawn themselves. The skill pre-loads the rules and trigger phrases that tell Claude when to engage; the daemon serves the same primitives over MCP so Claude can mutate state (add tasks, mark them done, record session summaries) through tool calls instead of file edits.

State lives as plain markdown + YAML, so anything the tool can write the operator can read in cat or edit in $EDITOR. Concurrency is handled by atomic writes (tmp + fsync + rename) and per-initiative POSIX advisory locks. Schemas are validated on every write, so the on-disk tree is always coherent.

The package ships everything in one tarball: CLI binary, MCP server, daemon, bundled single-file dashboard, and skill content. One npm install -g plus one active-work setup and the whole stack is live.

Install

npm install -g @titan-design/active-work
active-work setup

active-work setup is an interactive wizard that walks through eight steps:

• Verify Node version — Node 22+ required.
• Create the active root — $XDGDATAHOME/active-work/.
• Write the schema version — .schema-version file at version 1.
• Write a config stub — $XDGCONFIGHOME/active-work/config.json with sensible discovery defaults.
• Install the skill — copy skill/ into ~/.claude/skills/active-work/ (the npm postinstall already does this if ~/.claude/ exists; this step is idempotent).
• Register the MCP server — adds an entry to your Claude Code MCP config so Claude can call active-work tools.

• Start the daemon — launches active-work mcp serve --detach and (on macOS) optionally installs a launchd plist so the daemon restarts at login.
• Optional ingestion walkthrough — spawns a Claude session at the active root with a discovery prompt, helpful when adopting active-work for an existing pile of in-flight work.

For non-interactive environments (CI, dotfile bootstrap scripts) use active-work setup --yes. To re-run after an upgrade and pick up new defaults, use active-work setup --update.

Quickstart

Create an initiative, add a couple of tasks, then bootstrap a Claude session:

active-work new my-feature --title "My Feature" --ship-target 2026-Q4
active-work task add my-feature --title "Wire up auth" --priority 1 --severity high
active-work task add my-feature --title "Write tests" --priority 2
aw my-feature            # launches `claude` with the bootstrap prompt

active-work new scaffolds the directory: brief.md (frontmatter + body), handoff.md, an empty tasks/ folder, and an artifacts.yml. active-work task add writes a YAML task file with a sequential ID derived from the initiative's taskprefix (e.g. MF-1, MF-2). aw <slug is the launcher: it calls active-work open <slug under the hood to assemble the bootstrap prompt — brief excerpt, open loops with the age of each hang, last session, top open tasks, open artifacts, time since last session — then execs claude with that prompt in the initiative's worktree. Run aw with no slug and it resolves the initiative from your current directory — if the cwd sits inside an initiative's registered worktree, it opens that one straight away; otherwise (or with aw --pick) it drops to the interactive picker. Use active-work open <slug directly when you want the prompt without launching Claude. To re-seed context inside an already-running session, active-work prompt [slug] prints the same bootstrap prompt (cwd-resolved, no side effects); the bundled /aw-prompt Claude Code slash command runs it and injects the output. Add --adhoc to any of these (aw <slug --adhoc) to reframe the prompt for ad-hoc work on the workstream — the context becomes background rather than a directive to continue the handoff, and the session waits for you to describe the task.

When you wrap up a session, capture it: