mayfly

Mayfly

English | [中文](README.zh.md)

Mayfly is an independent terminal frontend for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). The product runs as two processes: a native dsh Host and an independent TUI connected through the official HTTP/WebSocket Client. The Host owns Agents, models, tools, and Sessions; the TUI owns input, themes, panels, and terminal rendering. Closing the TUI detaches it while Host work continues.

This development branch targets official Harness 0.2.2-rc.1. The published Mayfly 0.1.4-rc.2 is the immutable reference for appearance, keys, and workflows. Shared presentation is being carried into the split runtime; complete visual parity still requires the acceptance described in [split validation](docs/split-parity-validation.md).

Unified command

The new CLI starts a background Host automatically and connects the independent TUI. From a built checkout:

pnpm install --frozen-lockfile
pnpm run build
node packages/cli/lib/bin.js --profile mayfly-dev
node packages/cli/lib/bin.js server status --profile mayfly-dev
node packages/cli/lib/bin.js server stop --profile mayfly-dev

After a matching release is published, install @ephemeral-ai/mayfly-cli globally and use mayfly and mayfly server start|stop|restart|status|logs|enable|disable|upgrade. Linux uses systemd user services, macOS LaunchAgents, and Windows a hidden Mayfly supervisor. Login startup is opt-in. Data defaults to ~/.mayfly, with MAYFLY_HOME overriding it; credentials are exchanged through private local discovery. See the [CLI manual](packages/cli/README.md) for instances, logs, remote connections and lifecycle limits.

Upgrade the external CLI after stopping the old Host and backing up MAYFLY_HOME, then run mayfly server upgrade on the original profile to retain its Sessions. CLI-managed linked profiles use this explicit installer path; /update cannot upgrade them. See [upgrades and existing data](website/en/guide/upgrade.md) for the exact commands, rollback, and the old ~/.dsh boundary.

Native development startup

Use Node >=24.9.0, pinned pnpm 11.7.0, and an isolated official dsh 0.2.2-rc.1 executable. These split packages are development artifacts; install from this checkout or verified release tarballs. The installer checks the dsh version and keeps the global installation unchanged.

pnpm install --frozen-lockfile
DSH_BIN=/path/to/dsh PROFILE=mayfly-split-accept script/install-dev.sh

The installer builds the workspace, creates a dedicated profile from the native Web template, and adds @ephemeral-ai/mayfly-host. It reuses an existing profile and rejects the shared mayfly and default profiles. Launch both processes:

# Terminal 1: Host
/path/to/dsh --profile mayfly-split-accept

# Terminal 2: TUI; copy the authenticated URL printed by the Host
MAYFLY_DSH_STARTUP_URL='' script/mayfly-tui.sh

Model credentials, provider settings, permission presets, and session files belong to the Host. The Host emits one mayfly host: readiness line. Supply that authenticated URL through MAYFLY_DSH_STARTUP_URL; the TUI rejects credentials in command-line arguments. --host accepts a non-secret HTTP(S) URL while obtaining its token from the environment.

The TUI supports an initial task, an existing Session, and a Host working directory:

# Set the authenticated URL once in this terminal
export MAYFLY_DSH_STARTUP_URL=''
script/mayfly-tui.sh 'Explain this repository'
script/mayfly-tui.sh --resume 
script/mayfly-tui.sh --cwd /path/on/host 'Run the relevant checks'

MAYFLY_SESSION_ID, MAYFLY_CWD, and MAYFLY_TASK provide defaults when corresponding arguments are absent. A launch without a task or resume id stays sessionless until the first prompt. /new and /clear return to that start view without creating an empty Session or stopping existing work. Rebuild with pnpm run build after source edits; rerun the installer when the dependency graph changes. The unified CLI uses this same TUI entry after starting and discovering its local background Host.

Use the TUI

The shared layout contains the conversation, activity and notification rows, editor, and status/views lane. It renders Markdown tables, closed Mermaid fences, tool cards, file diffs, approvals, and questions. Theme changes preserve the native editor's draft, cursor, undo, history, paste, and completion state. /theme custom [] reads a palette on the TUI machine; /theme changes live presentation without saving the Host's default. Use /settings or onboarding to change persisted preferences.

/help and slash completion reflect the selected Host's actual command catalog and the mounted local features. A writable Session adds native Host commands; readonly views do not advertise writable commands. Canonical command names remain singular: /model, /provider, /preset, and /plugin.

| Workflow | Commands and behavior |

| --- | --- |

| Session navigation | /sessions (/resume) opens the workspace/session browser; an id resumes directly. /rename renames the selected Session. /fork creates and selects a branch at the current native fork boundary; extra arguments are ignored. /rewind opens the reference earlier-turn picker with prompt/response previews and creates a selected branch while preserving the original Session. |

| Models and configuration | /model [name], /effort [level] (/thinking), /provider, /preset [name], /permissions, and /settings use native Host catalogs and writes. Before a Session exists, model and preset choices set Host defaults. |

| Plan mode | /plan enters plan mode, /plan off leaves it, and /mode or Shift+Tab toggles it. /plan sends a native plan prompt in an existing Session; without a Session it asks you to send an ordinary message first. A sessionless mode choice is admitted before the first ordinary prompt; a failed admission sends no prompt. Alt+M c