Introduction

The philosophy of DeepSeek Harness (DSH) is that “everything is a plugin,” and workflows can be extended through plugins. Wayfinder is a task management concept in which tasks may be scattered across dex, Jira, GitHub Issues, or Markdown files. If these tasks are handled with independent DSH sessions, manually managing dependencies and state synchronization can become difficult. This plugin aims to generate a top-level DSH session for each ready task and visualize the dependency graph in the chat GUI.

Plugin Overview

  • Name: dsh-wayfinder-ui
  • Owner: andrepontesmelo
  • Category: Workflow
  • License: MIT
  • Core Features: Generates a live session for each ready Wayfinder task and draws the dependency graph in the chat GUI.

Installation and Enablement

This plugin requires Node.js >= 22 and the DSH Web profile. Installation requires manual cloning and linking, followed by restarting the GUI.

  1. Clone the Code Repository
    Clone the repository in any location:
git clone https://github.com/andrepontesmelo/dsh-wayfinder-ui.git
  1. Link to the Web Profile
    Link the cloned directory to the DSH Web profile:
ln -s /path/to/dsh-wayfinder-ui ~/.dsh/profiles/web/node_modules/dsh-wayfinder-ui
  1. Register the Plugin
    Open ~/.dsh/profiles/web/cordis.patch.yml and add the following lines at the end of the file to register the plugin:
- insert:
    - id: wayfinder
      name: 'dsh-wayfinder-ui'
  1. Restart the GUI
    After saving the configuration, you must restart the DeepSeek Harness GUI to load the plugin tools and the map panel.

Core Features

The plugin provides a set of tools that the model can invoke to manage the lifecycle of Wayfinder tasks:

  • wayfinder_snippet: Prints the protocol, proposes ready Wayfinder tasks, requests user approval, and then invokes wayfinder_spawn_session. It also documents the seed message format and routing inheritance rules.
  • wayfinder_spawn_session: Generates a top-level DSH session in parallel for each ready task. The seed message includes a task locator so that workers can find their actual tickets (for example, Jira, GitHub). Each generated session inherits the caller’s workspace routing, but this can be overridden via parameters.
  • wayfinder_map_create: Validates and persists a new map to <root>/.wayfinder-runner/state.json in the registry, and sets it as the selected opened map.
  • wayfinder_task_resolve: Marks a task as completed (via the path reported by the worker) and links the reporting session ID to the task row.
  • wayfinder_task_set_status: Manually overrides the task status (todo | done | running | waiting | blocked). It is recommended to prefer using wayfinder_task_resolve for worker completion reports.
  • wayfinder_map_sync: Creates or replaces a map by name, including the full task list. It is also registered as a recovery tool /wayfinder-map-sync.
  • wayfinder_grilling_start: Reports that a session for a “grilling” task has started grilling batch processing and is waiting for the user. It marks grillingSince on the task row and displays a flame icon in the panel.

How It Works

The workflow consists of four main stages:

  1. Chart: Invokes wayfinder_map_create to validate the task list and persist the map.
  2. Spawn: Invokes wayfinder_spawn_session to generate a top-level session for each approved task. The seed message starts with /wayfinder so that Harness can inject skill content.
  3. Report: Workers report completion by invoking wayfinder_task_resolve.
  4. Derive & Restart: State (done, blocked, running, waiting) is derived from reports and dependencies. Restarting the GUI reloads the state file and reassociates sessions with their task rows.

Considerations

  • Profile Limitation: The plugin only applies to the Web profile. The map cards, right sidebar, and sidebar badges are located in the DSH GUI.
  • Session Target: Generated sessions target the selected opened map in the registry (selectedMapId), falling back to the most recently opened map if no map is selected.
  • System Requirements: Node.js >= 22 and the DSH Web profile are required.
  • Restart Requirement: The GUI must be restarted to load the tools and map panel.

Summary

This plugin provides a structured way to manage Wayfinder tasks in DSH workflows. By mapping tasks to independent sessions and visualizing progress in the GUI, it simplifies task management across multiple tracking sources.