worklog-persist
A focused Claude Code plugin that gives your sessions a durable work-state layer backed by the Outline MCP server. It preserves the state of active engineering work between agent sessions: what task is in progress, what was verified, what changed, which decisions were made, what is blocked, and what the next action is.
It is a persistence layer only. Graph synchronization, reflection promotion and curriculum clustering are deliberately not part of this plugin.
The plugin is named worklog-persist, not outline-persist: the outline name
belongs to the Outline MCP server and the separate outline
KB skill, and a plugin with the same name shadows them. Only the plugin identity
changed. The MCP server entry, OUTLINE_API_TOKEN and the Outline document
routing are untouched.
What it does
- Reads current work context from Outline before non-trivial work.
- Records task start, verified checkpoints, handoff and completion.
- Keeps one record per work item (idempotency key = resolved project + task slug), so repeated checkpoints update rather than duplicate.
- Redacts secret-shaped values before anything is written.
- Never claims a write succeeded unless Outline confirms it; states plainly when Outline is unavailable and continues.
Install
Requires the claude CLI and an outline MCP server reachable via the standard
HTTP transport, Cloudflare Access + Bearer token, all from environment
variables — no credentials, and no one operator's Outline URL, are stored in
this repo. Set before first use:
export OUTLINE_MCP_URL="https://outline.example.com/mcp" # your Outline instance's MCP endpoint
export OUTLINE_API_TOKEN="..." # Outline API token
export CF_ACCESS_CLIENT_ID="..." # only if behind Cloudflare Access
export CF_ACCESS_CLIENT_SECRET="..."
Claude Code expands ${VAR} placeholders in a plugin's .mcp.json for http
server url and headers fields at session start; see the
MCP docs.
make # every target, with a one-line description each
./install.sh # dry-run by default: prints the plan, touches nothing
./install.sh --apply # execute, confirming each step
./install.sh --apply --yes # non-interactive
./install.sh --check # validate plugin structure only (no claude needed)
make plan # == ./install.sh
make install # == ./install.sh --apply, and REFUSES from a worktree
--apply refuses to run from a linked git worktree. marketplace add records the
checkout path, and a worktree path is deleted with its branch.
Re-running ./install.sh --apply is safe: it skips the marketplace add and plugin install
if they are already present, and never edits your settings.json or a shared
mcp.json — the claude CLI manages its own registry, so unrelated marketplaces,
plugins, MCP servers and hooks are left untouched.
DeepSeek Harness
dsh/ is a DeepSeek Harness (DSH) adapter for the same plugin tree. The Claude Code
install above does not use it and does not change. The adapter imports its runtime
from the published npm package claude-plugin-dsh, pinned to an exact version in
dsh/package.json and locked in dsh/bun.lock. There is no vendored copy.
Install the adapter's dependencies first, from a persistent checkout, with Bun and Node 20 or newer. Then add the adapter to a DSH profile:
cd /abs/path/to/worklog-persist/dsh && bun install --frozen-lockfile
dsh plugin --profile <profile> add file:/abs/path/to/worklog-persist/dsh
Do not rely on dsh plugin add to install claude-plugin-dsh for you; that has
not been checked. To check what the adapter registers without a DSH profile:
bun x claude-plugin-dsh@0.2.1 inspect /abs/path/to/worklog-persist
inspect imports the adapter's JavaScript, so run it only on a trusted checkout.
Do not run the package's sync or scaffold commands on this adapter: as of 0.2.1
they write a vendored claude-compat.js, which this adapter no longer uses. To move
to a newer runtime, change the exact version in dsh/package.json, run
bun install in dsh/ to refresh dsh/bun.lock, then run make test.
The adapter registers the skill, the lifecycle commands as /wl-<name>, and the
SessionStart and Stop hooks. The native worklog panel and /show are Claude
Code only. The runtime does not read .mcp.json. dsh/cordis.patch.yml carries an
outline row for @deepseek-ai/dsh-mcp-client that ships disabled: enable
claude-compat-worklog-persist-outline only when the profile has no outline
server yet, and set OUTLINE_MCP_URL, OUTLINE_API_TOKEN and, if needed, the two
CF_ACCESS_CLIENT_* variables above. The MCP client package must be available to
the profile.
Renamed from outline-persist
| Old | New |
|---|---|
plugin and skill outline-persist |
worklog-persist |
marketplace outline-persist-marketplace |
worklog-persist-marketplace |
env OUTLINE_HOOK_OFF |
WORKLOG_HOOK_OFF |
env OUTLINE_PERSIST_LIVE |
WORKLOG_PERSIST_LIVE |
state dir ~/.local/state/outline-persist |
~/.local/state/worklog-persist |
Uninstall the old plugin before installing this one:
claude plugin uninstall outline-persist@<marketplace>. The off-state file does not
migrate. If automatic persistence was disabled, run
bash scripts/persistence-state.sh off once after the reinstall.
Enable / disable
The plugin can be disabled without uninstalling it:
/off # inside a session (slash command)
bash scripts/persistence-state.sh off # or from a shell
bash scripts/persistence-state.sh on # re-enable
WORKLOG_HOOK_OFF=1 # env override forces off
./install.sh --apply --disable # disable the whole plugin
./install.sh --apply --enable
./install.sh --apply --uninstall
When disabled, the SessionStart hook stops injecting the durable-memory rule, the Stop hook stops blocking unpersisted turns, and no automatic writes happen. The manual commands still work.
The Stop hook blocks a stop only after work was shipped since the last Outline
write: a git commit or git push, gh pr create or gh pr merge, a release,
publish or deploy command. Edits and long read-only runs never trigger it. It
blocks at most once per piece of work, never in a non-interactive run or for an
ignored repo, and stays quiet for 90 minutes after a block or an Outline write.
Set WORKLOG_STOP_COOLDOWN_MIN to change that window (0 turns it off).
Search by date
Use /search --on 2026-11-09, /search --from 2026-11-01 --to 2026-11-09,
or /search --last-days 7 --timezone Europe/Warsaw, with optional search text.
The search is read-only and covers the current project's Outline task records,
checkpoint history and conversation history exposed by the host.
Calendar ranges include both dates. Last 7 days is an elapsed 168-hour window.
Pass an IANA timezone for calendar dates. The agent asks when the user's zone is
unknown; the standalone helper defaults to UTC. Results distinguish checkpoint
dates, document updates and message times. Unavailable sources and incomplete
results are reported, not hidden as empty matches. Conversation date-only browsing
depends on the host's history interface. A DSH build with bounded empty-query
support accepts query: "" with time bounds; older builds require search text.
Commands
Eight slash commands map to the persistence lifecycle:
| Command | Purpose |
|---|---|
/load |
Load current work-state before substantive work (read-only). |
/start |
Create or update the task record with objective + acceptance criteria. |
/checkpoint |
Update the same record after a verified milestone. |
/handoff |
Write a compact handoff state when a session ends or is blocked. |
/complete |
Record the real completion result with verification outcomes. |
/dry-run |
Show the intended read/write (with redaction visible), change nothing. |
/off |
Disable automatic persistence without removing the plugin. |
/setup |
Route this repo to an Outline world, or mark it as not persisted. |
The full operational contract lives in skills/worklog-persist/SKILL.md, which
also auto-activates by description — the robust driver even where the SessionStart
hook's context injection is affected by known Claude Code bugs
(#16538,
#88086).
Native worklog panel
In a Claude Code build with Mods, /worklog-persist:show (or the prompt
show worklog panel) opens a pane beside the chat for the current project only:
its task records, the status and next action of the task you pick, that task's
checkpoints and handoffs, and a title filter over the project's documents.
- Pick a task in Tasks to make it active. The pane lists task records, not individual chat sessions; it does not guess which task the conversation belongs to.
- A pinned status line below the prompt shows
Task: <task>. An open document addsPreview: <document>, without changing the active task. The line clears while the project scope is unresolved and follows task or document selection. - Previewing a document shows it in the pane only. Load into session adds it to the conversation as untrusted reference data, with its Outline id.
- The action buttons run this plugin's own commands (
load,start,checkpoint,handoff,complete,dry-run,setup,off). A dispatched command is not a confirmed write; the pane refreshes from Outline when the turn ends. - The pane only reads Outline. It never creates a folder or a record, and it shows a read failure as a failure, not as an empty project.
The panel is a hooks module (hooks/register.tsx). It needs a Claude Code build
with Mods and the module loaded. A development copy in a session's mods folder
loads only after the person running that session agrees to it. What installing or
updating the plugin does to the module has not been checked. The lifecycle
commands and the classic hooks are unchanged by the panel, but loading this
plugin in a build without Mods has not been tested. Details:
docs/session-hook/.
Persisted record schema
Structured state, not a transcript. The task record holds current state only,
kept under about 4,000 characters: repository identity, branch and worktree,
Last updated: YYYY-MM-DD, then sections for objective (with acceptance
criteria), status (active / blocked / handoff / complete), decisions,
verified facts, blockers, next action, the latest checkpoint links, and related
documents. Checkpoints update it in place with editMode: "patch" of the changed
sections.
History never goes into the record. Each checkpoint, handoff or completion
creates a short child document, Tasks/<slug>/<YYYY-MM-DD> <short title>, with
changed files, commands and outcomes, and a link back to the record. This keeps
each write small: Outline's update_document returns the whole body, so a record
that grows with every checkpoint costs more context on every write.
KB structure and routing
The plugin reads its own config file: $WORKLOG_CONFIG, else
~/.config/worklog-persist/config.yaml. It is YAML and needs PyYAML
(python3 -m pip install pyyaml, or your system package). Without PyYAML, or
with a missing or broken file, the resolver never crashes. It reports
config_error and falls back to $WORKLOG_WORLD.
outline:
root_collection: My KB
global_collection: Notebook
archive_collection: Archive
worlds:
- name: Alpha
projects:
- {name: my-project, repo: ~/code/my-project}
- {name: other-project, repo: ~/code/other, kb_folder: My KB/Alpha/custom-folder}
ignore:
- ~/scratch
- Collections (
root_collection,global_collection,archive_collection) come from theoutline:block. A key left out keeps its built-in default. - A repo declared under
worlds[].projects[]gets its world, project name and optionalkb_folderfrom the config. A linked git worktree resolves to its main checkout first, so it maps to the same project. - An undeclared repo uses
$WORKLOG_WORLD, then path root: the config world whose own declared repos are the deepest ancestor-or-equal of this one (a tie between two different worlds is left unresolved, never guessed). Otherwise the world staysUNRESOLVEDand the agent runs onboarding. A repo underignore, or below an ignored dir, gets no world and no folder, from any of these. - Outside any git repo the project is
workspace, never the directory name. - Records live at
<kb_path>/Tasks/<task-slug>, wherekb_pathiskb_folderor<root_collection>/<World>/<project>. Ticket slugs (AD-163-uat-checklist) are accepted. - Bootstrap is the plugin's own rule: a world folder gets
INDEXonly, a project folder getsINDEX,Specs,Plans,Tasks. It is idempotent. - When the MCP server is down,
/loadsays persistence is unavailable. There is no local fallback.
Upgrading from 0.2: the old shared manifest and its world env var are no longer
read. The schema is the same, so you can copy the entries you need into the file
above, or run /setup once per repo.
Onboarding a repo
You do not have to write the config yourself. When a session starts in a repo
that is not declared (or there is no config yet) and WORKLOG_WORLD is unset,
the SessionStart hook tells the agent to run onboarding first. /setup runs the
same flow on demand. The agent lists the worlds that already exist as top-level
documents in root_collection, asks you once (pick a world, name a new one, or
do not persist this repo), and records the answer with:
bash scripts/config-add.sh project --world Alpha --name my-project --repo ~/code/my-project
bash scripts/config-add.sh ignore --repo ~/scratch
config-add.sh creates the file if needed, keeps existing entries, does nothing
on a repeat, refuses to move a repo to another world, and never rewrites a file
it cannot parse. It rewrites the file in full, so YAML comments in it are lost.
Check what a repo resolves to:
bash scripts/resolve-context.sh my-task-slug
Tests
make check # everything offline: pytest suite, shell suites, structure check
make lint # shellcheck at warning severity
make live # opt-in reachability check against the Outline server in .mcp.json
make test-native # native panel: claude plugin validate + claude plugin test (needs claude)
Offline tests use local fixtures and mocks; the live test is opt-in and needs no credentials in CI.
Documentation
docs/ describes the plugin by building block: each block has README,
CONTRACTS, INVARIANTS, GAPS and OPERATIONS pages. Start at
docs/README.md. Rules for writing there are in
docs/CONVENTIONS.md, and tests/test_docs_layout.py
enforces them.
Scope boundary
This plugin covers Outline persistence only: the skill, its SessionStart rule,
the slash commands, the native worklog panel and the outline MCP entry. It has no reflection, no graph
sync and no curriculum. It reads no config but its own.
No comments yet. Be the first to write one.