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:
- browse projects, campaigns, findings, reports and attack paths without leaving the console;
- read-only;
- zero model calls while browsing, so that reading costs nothing and sends nothing to a model provider;
- 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
| Option | Description | Verdict |
|---|---|---|
| A | Official OpenCode TUI plugin API | chosen, after resyncing the fork |
| B | Patch the fork's TUI directly | fallback only |
| C | Separate dm-explore binary | rejected: fails « without leaving the console » |
| D | Custom slash commands | rejected: 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.registerfor one route,darkmoon.explorer;api.keymap.registerLayerfor the command, reachable as/explore, from the palette, or with<leader>d;api.ui.dialog,api.ui.toast,api.theme.mode(), andapi.kvfor 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
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
| Measure | Value | Status |
|---|---|---|
| Model calls while browsing | 0 (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 baseline | VERIFIED (report) |
| Image size | 353 MB, unchanged by the plugin | VERIFIED (report) |
| Community executive / plan / frameworks fetch | ~1.5–1.8 s each, after a 250 ms settle | VERIFIED (report) |
| Network | one request per screen, 60 s cache | VERIFIED (code + report) |
| Plugin tests (bun) | 15 → 23 → 28 → 40 → 43 → 48 across iterations | VERIFIED (reports) |
| Community Python adapter tests | 29 → 32 | VERIFIED (reports) |
| Large fixture | 1,200 findings → 24 pages of 50, only the visible window rendered | VERIFIED (report), SIMULATED data |
| Render time | none recorded | not measured |


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).

Scientific and technical sources (verified)
- OpenCode. https://github.com/anomalyco/opencode (formerly
sst/opencode) - OpenTUI. https://github.com/anomalyco/opentui (formerly
sst/opentui) - Ecma International. ECMA-48: Control Functions for Coded Character Sets. https://ecma-international.org/publications-and-standards/standards/ecma-48/
- B. Shneiderman. « The eyes have it ». IEEE Symposium on Visual Languages, 1996. doi:10.1109/VL.1996.545307
URLs fetched and DOI checked on 2026-11-20.
Research, source code & reproducibility
- Main research repository: ASCIT31/darkmoon-visualization-research, sections tui/architecture, tui/iterations and UXDR-17 to UXDR-20 in decisions. Engine-side record: ADR-F01 and EXP-058 in darkmoon-attack-paths-research.
- Source code: ASCIT31/Dark-Moon →
conf/plugins/darkmoon-explorer(index.tsx,core.ts,core.test.ts,darkmoon_explore.py).index.tsx,core.tsandcore.test.tshave identical blob hashes in both editions; only the Python adapter and its tests differ (VERIFIED). - Documentation: https://docs.dark-moon.org
- References: references/README.md (terminal-interface section).
- Reproducible experiments: install DarkMoon Community, run a campaign against a lab you are authorised to test, open
/explore, and compare the OpenCode message count before and after browsing. The unit tests live next to the plugin (core.test.ts) and can be run with bun.
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.
See the proof, not just the write-up: the Pro remediation benchmark (fixes retested against the exploit) · how Darkmoon compares to other AI pentest tools.
← All articles