mayfly

Mayfly

English | 中文

Mayfly is an interactive terminal UI for DeepSeek Harness (dsh) — an out-of-tree Cordis bundle over dsh-base, built against Harness 0.2.0-rc.2. Mayfly 0.1.3-rc.2 deliberately uses the same plugin model as dsh Web: plugins are ordinary Cordis siblings and consume native dsh services directly.

• Terminal-native rendering: Markdown tables, closed Mermaid fences in assistant messages, and renderer-neutral line, point, bar, sparkline, and heatmap nodes — with width-safe source or text fallbacks.
• One activity row for live status: the spinner, current step, turn elapsed time, estimated token count, and output rate live above the editor; the transcript records only what has happened.
• Side conversations: /btw and the /agents subagent tree share the transcript pane; F7 returns to the previous conversation and F8 closes the displayed one.
• An ordinary plugin model: consume ctx.commands, ctx.sessionProjections, ctx.tools, and other documented dsh services directly; UI contributions go through mayflyPanes, mayflyStatus, mayflyOverlays, and mayflyEditorExtensions.

The activity row above the editor is the one place for live status: the spinner, the current step (Thinking, Running commands), the turn's elapsed time, and the estimated token count and output rate. The transcript records only what has happened, so streaming reasoning shows as a captionless ✻ tail that settles to one ✻ Thought for 6s row, and file changes stay visible as diff cards next to the final answer. Rates use four characters per token, exclude first-chunk latency, and disappear after two seconds without output. Narrow terminals omit tips and rates first.

Plugin model

A plugin declares the services it needs with inject, then uses them from its Cordis context:

• ctx.commands, ctx.sessionProjections, ctx.tools, and the rest of the documented dsh services are used directly.
• ctx.mayflyPanes, ctx.mayflyStatus, ctx.mayflyOverlays, and ctx.mayflyEditorExtensions are the only Mayfly-specific UI contribution services.
• ctx.mayflyCurrentAgent.current() returns the exact Agent selected by this Mayfly frontend when an Agent-scoped native service needs it.
• Every registration belongs to the caller's Cordis Fiber. Unloading the plugin removes its commands and UI contributions.

There is no Mayfly plugin manifest, capability negotiation, adapter facade, private plugin realm, or separate plugin-author CLI. Mayfly's own features and external plugins register through the same services.

Plugins always return ordinary renderer-neutral nodes. Mayfly automatically windows large list nodes and delays hidden responsive branches, so plugins do not manage viewport ranges, overscan, renderer caches, or scroll controllers. Plugins still own database and network fetching.

Interactive panes and overlays declare onEvent: { observe, action }. Mayfly's frontend owner retains form drafts, selections, tabs, document anchors, confirmation, operation state, and feedback across renderer reloads. Plugins perform native reads and writes in action, then return a structured settlement such as accepted, invalid, conflict, or failed; external data refreshes use set(node, { reason: 'data', source }).

import type { Context } from '@deepseek-ai/cordis'
import type {} from '@deepseek-ai/dsh-commands'
import type {} from '@ephemeral-ai/mayfly-ui'
import { ui } from '@ephemeral-ai/mayfly-ui'

export const name = '@acme/build-health'
export const inject = ['commands', 'mayflyPanes']

export function apply(ctx: Context): void {
  ctx.commands.register({
    name: 'health',
    description: 'Show build health',
    handler: () => ({ kind: 'success', text: 'healthy' }),
  })
  ctx.mayflyPanes.register({
    id: 'acme.build-health',
    placement: 'right',
    narrow: 'bottom',
  }, ui.text('healthy'))
}

Publish-shaped plugin packages live in examples/; the developer manual covers the full contribution lifecycle.

Install

Prerequisites are Node ^22.19 || >=24 and pnpm 11.

npm i -g @deepseek-ai/dsh
dsh plugin --profile mayfly add @ephemeral-ai/mayfly
dsh --profile mayfly

Or install the standalone launcher, which includes the tested dsh runtime:

npm -g install @ephemeral-ai/mayfly-cli
mayfly

Set DEEPSEEK_API_KEY before first run.

Usage

/help lists the active commands and key bindings. /agents browses the current session's subagent tree; Enter opens a child and /agents stop <id> stops a live continuable leaf child; a parent with live descendants is refused so teardown cannot silently remove a whole subtree. /btw <question> opens a temporary side Agent. Side conversations (BTW and subagents, several at once) render in the same transcript pane with the complete Mayfly layout and editor: press F7 to return to the previous conversation and F8 to close the displayed one. Interrupting the selected conversation also interrupts every running continuable descendant without closing those Agents.

Architecture

The public npm surface is deliberately limited to three packages:

• @ephemeral-ai/mayfly-ui: renderer-neutral contracts, builders, and the four UI services/provider.
• @ephemeral-ai/mayfly: all runtime areas, public runtime subpaths, composition, and presets.
• @ephemeral-ai/mayfly-cli: the dependency-free global launcher.

Frontend, conversation, app, core, transcript, and interaction remain internal ownership areas and Cordis rows inside @ephemeral-ai/mayfly; they are not independently published packages.

flowchart TB
    ROOT["one dsh process · one Cordis service graph"]
    DSH["native dsh services<br/>commands · sessionProjections · tools · agents"]
    PLUGIN["ordinary Cordis plugins<br/>official Mayfly rows and external siblings"]
    AGENT["mayflyConversations · mayflyCurrentAgent<br/>primary + side conversations<br/>exact displayed Agent"]
    UI["direct Mayfly UI services<br/>mayflyPanes · mayflyStatus<br/>mayflyOverlays · mayflyEditorExtensions"]
    CORE["@ephemeral-ai/mayfly core area<br/>only pi-tui and raw-terminal owner"]
    TERM["terminal"]

    ROOT --> DSH
    ROOT --> PLUGIN
    DSH --> PLUGIN
    AGENT --> PLUGIN
    PLUGIN --> UI
    UI --> CORE
    CORE --> TERM

Only packages/mayfly/src/core/ imports pi-tui or owns raw terminal behavior. @ephemeral-ai/mayfly-ui defines renderer-neutral nodes and direct registries. The app area selects the current Agent and coordinates startup, while the transcript and interaction areas consume native dsh services and publish UI contributions.

See the architecture, the service seams, and the developer manual.

Community

Questions, feedback, or feature ideas? Join the official Mayfly group on Feishu (primarily Chinese). Invite links expire every 7 days — grab the current one from the latest comment of the pinned group issue. Bug reports still belong in issues.

License

MIT.