DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

kolezka /

kolezka/worklog-persist

Topic repository only

This plugin has no description yet.

★ 0 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: master@ba76c3da

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 adds Preview: <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 the outline: block. A key left out keeps its built-in default.
  • A repo declared under worlds[].projects[] gets its world, project name and optional kb_folder from 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 stays UNRESOLVED and the agent runs onboarding. A repo under ignore, 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>, where kb_path is kb_folder or <root_collection>/<World>/<project>. Ticket slugs (AD-163-uat-checklist) are accepted.
  • Bootstrap is the plugin's own rule: a world folder gets INDEX only, a project folder gets INDEX, Specs, Plans, Tasks. It is idempotent.
  • When the MCP server is down, /load says 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.

—/ 5

No ratings yet

Manifest verification required

Commit ba76c3da5772

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout