FAQ

Why not a plain npm install @ephemeral-ai/mayfly?

Mayfly is a plugin bundle installed into a dsh profile, not a standalone app — a bare install only drops the package into node_modules, with no host and no profile assembly, so there is nothing to run. The supported paths are the mayfly shell or dsh plugin --profile mayfly add; see Quickstart. The current preview is v0.1.4-rc.1, published under npm's rc tag; latest stays on the previous release line. Reproducible environments should pin Mayfly 0.1.4-rc.1 and Harness 0.2.1-rc.2. The contributor development install lives in Contributing to Mayfly.

The default install does not resolve the newest release?

pnpm 11 enables a minimumReleaseAge cooldown by default: dist-tag resolution silently skips versions published inside the window and falls back to an older one. If dsh plugin --profile mayfly add @ephemeral-ai/mayfly installs a stale version, either:

• install the current latest exactly — query it with npm view @ephemeral-ai/mayfly dist-tags.latest, then run dsh plugin --profile mayfly add @ephemeral-ai/mayfly@<published-version>;
• or re-run the same unversioned command once the cooldown window has passed (upgrading = re-running the same plugin add).

Upgrading through /update avoids the trap entirely: it resolves the target from registry metadata, always pins the exact version, and inside the cooldown window it answers with the retry time (an ETA) instead of installing a stale build.

How do I upgrade Mayfly?

Two paths:

• Shell users: re-run npm -g install @ephemeral-ai/mayfly-cli — reinstalling is the upgrade (the shell calibrates the profile's Mayfly to its own version and pins the host line with it); start with mayfly as usual afterwards.
• Direct-dsh users:
  • In-app (recommended): type /update in the session — it runs the safety pre-flight first (profile health, whether the active dsh runtime meets the target release's harness line, the cooldown window), then after you select Yes in the Yes / No confirmation it snapshots the current install, installs the exact version in one transaction, verifies the whole package set, and boot-smokes the result (a module import sweep plus a real boot); any failure rolls back automatically to the previous version, with a progress panel and a log path throughout. /update <version> pins an explicit target; a bare /update doubles as a read-only check. After a successful update the current session keeps running the old version — a restart applies it.
  • Manually: re-run the same dsh plugin --profile mayfly add @ephemeral-ai/mayfly (or the exact-version form in the previous question).

Mayfly also checks for a newer release in the background at startup (at most once per 24h, silent on failure, reads registry metadata only, sends nothing); when one exists it appends a two-line notice to the scroll area (below the banner at boot). To turn the startup check off, write this into ~/.dsh/settings.yaml:

mayfly:
  updateCheck: false

Pasting an image does nothing?

Ctrl-V paste depends on two things:

1. Terminal environment: the platform's own clipboard path is probed — wl-paste then xclip on Linux (3s timeout), one PowerShell call on Windows (10s), osascript on macOS (5s);
2. Model capability: pasted images enter the message as image content blocks. If the current model route has no image input, messages containing image blocks are rejected — that is the upstream harness capability negotiation; switch to a vision-capable model.

Images land in the attachment store (default ~/.dsh/attachments; relocate via DSH_MAYFLY_ATTACHMENT_DIR or DSH_HOME), capped at 10MB per image, 8 images / 30MB / 16M pixels per message.

You can copy image content from an application or copy one or more local PNG/JPEG/WebP/GIF files in your file manager (Ubuntu Files, Windows Explorer, macOS Finder — all paste as one ordered batch). The file-manager path only accepts local regular files; remote URIs, directories, symlinks, and special files are refused with a reason.

Why doesn't the injected AGENTS.md context show up in the transcript?

The harness injects workspace instructions (AGENTS.md and friends) and runtime-context snapshots into the session as synthetic user messages. Mayfly sorts by message source: human input renders as usual (» message blocks); synthetic messages render as nothing — no item, no placeholder — keeping the transcript clean. The content is still sent to the model in full; it is just not rendered.

Can I customize key bindings?

Not yet. Keys register through mayflyKeymap (duplicate bindings are rejected), but user-facing customization is deferred to a later phase (same for alt-screen surfaces). See Key bindings for everything available today.

/quit does nothing?

In the brief window before the agent attaches, /quit shows no active session instead of exiting — command dispatch checks for a current agent. Retry a moment later. Double Ctrl-C within 1 second also exits interactive mode.

When does the status-bar git badge refresh?

The git badge probes lazily through a TTL cache (branch 5s, status 15s), refreshed on whatever redraw comes next (typing and streaming both trigger one) — switching branches in the same directory shows up within seconds. The cache is built per working directory: a session switch (/new, /resume, or a restart) that lands on a new cwd rebuilds the cache for it.

What happens when the status bar runs out of room?

The footer is one row (an entry has no row of its own: the only second line is the heavy ━ under the item whose view is entered). When the row is crowded it first gives up detail in a set order (an item's time, the provider, the thinking level, git, the directory's depth, the cache bar, the context bar, and last the model). Entries then admit in priority, then id, order across the whole row regardless of band: an entry that fits keeps its full width, an over-wide entry truncates to the remaining budget (entries declaring overflow: hide hide entirely rather than truncate), and once the row is full, later entries stop appearing. Admitted entries then lay out in their declared left/center/right band. The session name no longer competes for footer space — it sits at the right end of the editor's top border.

Does bash-mode output enter the session history?

No. Commands in ! bash mode run through Mayfly's own executor and echo into the scroll area as shell cards — deliberately outside the session transcript, invisible to the model. Paste results back into the prompt, or let the model run a tool, when it needs to know.