Blog··7 min read

Bringing DarkMoon to the Terminal: Building an OpenCode Explorer

How DarkMoon added a read-only Terminal Explorer to the OpenCode console: options compared, fork resync, data adapters, zero model calls, measured costs.

DarkMoon research series·C. OpenCode & TUI·Article 14 of 23·All 23 articles

Introduction

DarkMoon runs its agents inside a fork of OpenCode, an open-source agent console for the terminal. Until November 2026, reading the results of a campaign meant leaving that console: opening report files, or, in the Pro edition, a web dashboard. The Terminal Explorer is a plugin that keeps the operator in the console. It is published in DarkMoon Community at conf/plugins/darkmoon-explorer and ships in both editions.

The research behind it is documented in darkmoon-visualization-research and summarised as an engineering decision in ADR-F01 of the attack-paths research repository.

Problem

The requirement, as stated by the product owner on 18 November 2026 (OBSERVED), had four parts:

  1. browse projects, campaigns, findings, reports and attack paths without leaving the console;
  2. read-only;
  3. zero model calls while browsing, so that reading costs nothing and sends nothing to a model provider;
  4. available in Community, not only in Pro.

Point 3 rules out the obvious shortcut. In an agent console, the easiest way to « show findings » is to ask the agent, and each question is a billed model turn.

Methodology

Four options compared

OptionDescriptionVerdict
AOfficial OpenCode TUI plugin APIchosen, after resyncing the fork
BPatch the fork's TUI directlyfallback only
CSeparate dm-explore binaryrejected: fails « without leaving the console »
DCustom slash commandsrejected: each step costs an LLM turn

(VERIFIED, internal report IR-63.)

The fork had to move first

The DarkMoon fork was at OpenCode 1.3.0, which had no TUI plugin API: the plugin package exported only . and ./tool, and routes were a closed union. The first ./tui export appeared in 1.4.0. The fork was fast-forwarded to v1.19.6, with OPENCODE_DISABLE_AUTOUPDATE=1 so that upstream updates cannot replace the DarkMoon binary. A rule was added: no deprecated calls, so that a future 2.x is « a rebuild, not a rewrite » (VERIFIED, reports IR-63, IR-64).

What the plugin actually uses

  • api.route.register for one route, darkmoon.explorer;
  • api.keymap.registerLayer for the command, reachable as /explore, from the palette, or with <leader>d;
  • api.ui.dialog, api.ui.toast, api.theme.mode(), and api.kv for the username only;
  • OpenTUI 0.4.5 as a host peer (@opentui/solid, @opentui/keymap/solid, @opentui/core) with Solid.

The plugin has no package.json and adds no dependency (VERIFIED, code). Sizes at the documented commit: index.tsx 2,698 lines, core.ts 1,151 lines, core.test.ts 557 lines (VERIFIED).

Two data adapters, one read model

Diagram. Figure 1. The two adapters behind the same views.
Figure 1. The two adapters behind the same views.

In Pro, the plugin logs in to the existing REST API, keeps the token in memory only, and calls existing GET routes; no endpoint was added. In Community, it runs a standard-library Python adapter in isolated mode over the local JSON store. The adapter vendors the evidence-redaction module and fails closed: if redaction cannot load, evidence becomes {"withheld": true} and the report shows « Report withheld ». Paths are confined to the data root, identifiers are checked against a regex, and symlinks that leave the root are refused (VERIFIED, code).

Terminal-specific security

Findings contain attacker-controlled strings (HTTP responses, banners, file contents). Printed raw, they can carry terminal escape sequences that clear the screen, change the window title or write to the clipboard. The clean() function strips 7-bit OSC/CSI, 8-bit OSC/DCS/SOS/PM/APC, C0/C1 controls and bidirectional overrides; it was tested live with ESC[2J, ESC]0; and ESC]52; (VERIFIED, code and test results). The control functions involved are those defined in ECMA-48.

Real results

MeasureValueStatus
Model calls while browsing0 (OpenCode DB: 148 messages / 7 sessions / 641 parts before and after the journeys; 0 sessions with all providers disabled)VERIFIED (reports)
Memory+44 MB RSS on a ~700 MB baselineVERIFIED (report)
Image size353 MB, unchanged by the pluginVERIFIED (report)
Community executive / plan / frameworks fetch~1.5–1.8 s each, after a 250 ms settleVERIFIED (report)
Networkone request per screen, 60 s cacheVERIFIED (code + report)
Plugin tests (bun)15 → 23 → 28 → 40 → 43 → 48 across iterationsVERIFIED (reports)
Community Python adapter tests29 → 32VERIFIED (reports)
Large fixture1,200 findings → 24 pages of 50, only the visible window renderedVERIFIED (report), SIMULATED data
Render timenone recordednot measured
Terminal Explorer Prioritized Treatment Plan in Community: a list of 14 actions with statuses on the left, and on the right the detail of action 1, an SQL-injection action marked In progress, with a note that this edition does not run retests.
Terminal Explorer Prioritized Treatment Plan in Community: a list of 14 actions with statuses on the left, and on the right the detail of action 1, an SQL-injection action marked In progress, with a note that this edition does not run retests.Original capture: ASCIT31/Dark-Moon
Terminal Explorer attack-paths tab in Community: 0 evidence-backed and 17 possible paths, and a 3-step Possible Attack Path whose links are labelled 'possible · not observed'.
Terminal Explorer attack-paths tab in Community: 0 evidence-backed and 17 possible paths, and a 3-step Possible Attack Path whose links are labelled 'possible · not observed'.Original capture: ASCIT31/Dark-Moon

The incident that changed the escape key

During capture scripts, esc at the explorer root closed it, and the following scripted keystrokes reached the Pro chat: « 6 » (no answer, $0) and « 5 » (one model answer, $0.09) (VERIFIED, report IR-65). The fix: esc at the root now stays in the explorer and shows « Press q to return to the console. »; q is the only exit. It was verified by sending esc three times, a digit and enter, and observing 0 new messages (VERIFIED). The lesson recorded is general: a harness that drives a real agent console must assert the active route before every keystroke.

Iterations

The plugin went from a 16-screen prototype on real DVGA data (Pro, 18 November) to the Community port in PR #59 (merged 19 November, 18 PNG and 18 ANSI captures), then to executive views and finally 80-column tabs on 20 November (VERIFIED, reports and PRs).

Limits

  • No images. The plugin API exposes no graphics protocol; the brand mark is the text DARKMOON.
  • Markdown tables and block quotes are drawn by the host component and cannot be restyled from a plugin beyond colours.
  • Branching attack paths are listed path by path, not merged.
  • No per-project ACL in the Pro API: the explorer shows what the account can read (OBSERVED, residual risk).
  • Truecolor is needed for exact colours; with --network none, OpenCode stays on a blank screen (VERIFIED).
  • API churn at OpenCode 2.x remains a risk.
  • No render-time measurement exists (not measured).

Figures

  • Figure 1 (Mermaid): data adapters.
  • Captures: docs/pics/terminal-explorer/ in DarkMoon Community (ANSI dumps of the real TUI rendered to PNG, synthetic demo data).
DarkMoon Terminal Explorer Frameworks view: a technical assessment, explicitly not an audit, listing ISO/IEC 27001:2022 Annex A, GDPR, NIS2 and the EU AI Act with counts of controls per state (weakness observed, none observed, not tested, not technically assessable), and on the right the Annex A controls with a weakness observed and the findings and actions behind each.
Figure 2. The Frameworks view of the explorer: a technical assessment, explicitly not an audit, with controls counted per state and the findings and actions behind each Annex A control. Lab data from intentionally vulnerable training apps.Captured 20 November 2026 from the Terminal Explorer (current interface).

Scientific and technical sources (verified)

URLs fetched and DOI checked on 2026-11-20.

Research, source code & reproducibility

Related reading: From Angular to TUI: Designing Two Interfaces Around the Same Security Data · Designing a Premium Terminal Interface with OpenTUI · Visualizing Attack Paths in ASCII and Unicode · Declared vs Proven Attack Paths: A Practical Evidence Model


Bug reports on the explorer, especially on escape-sequence handling, are welcome on ASCIT31/Dark-Moon.

Next
Run it against your own lab

Darkmoon is open source (AGPL-3.0) and self hosted. Clone it, point it at a target you own, and read every line.