Repository navigation
Releases
v1.0.4
Release v1.0.4
Compare changes: v1.0.3...v1.0.4
- Release 1.0.4 (67e6cc0)
- The exit tag now travels as data, not as a live object (30d385c)
- A cold start no longer waits for a daemon that is already up (3185fc8)
- The mark is a prompt, and a second cursor (b1598a3)
- Eight marks, and the favicon is a reduction of its own (58e4a6c)
- The notice carries the copyright lines, and each licence body once (6685cf5)
- The interface has a brand, and a status line that is always there (de3f988)
- The patch stays a maintainer artefact, not a shipped one (98795da)
Installation
Add to your opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-pty"]
}Update Instructions
To get the latest version:
rm -rf ~/.cache/opencode/node_modules/opencode-pty
opencodev1.0.3
Release v1.0.3
Compare changes: v1.0.1...v1.0.3
- Releases are staged, and a human approves them (ca4ebd3)
- Release 1.0.2, for the trusted publisher's validation window (0f864a7)
Installation
Add to your opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-pty"]
}Update Instructions
To get the latest version:
rm -rf ~/.cache/opencode/node_modules/opencode-pty
opencode1.0.1
First published release of the fork, as @lenucksi/agentterm (the npm name
opencode-pty belongs to the upstream project). The plugin id, the daemon socket,
the state directory and the storage keys keep the old name on purpose: renaming
them would strand a running daemon and orphan the archive.
Added
Named keys, quiet waits, and an installer with both edges
pty_sendkeysends a key by name -Enter,Tab,Escape, arrows,
Home/End/PageUp/PageDown,C-a..C-z,F1..F12- withtimesto
repeat.pty_writemakes a model spell bytes, and a wrong byte is not an error,
it is a prompt that does not move. A name the terminal does not have is refused
with the list of names that exist; a command still goes throughpty_write,
where the permission policy sees it.pty_waittakesquietMs: return once the session has printed nothing for that
long, with the process still running. That is how a prompt is awaited without a
pty_readloop. The result says which ending it had (reason="quiet"or
"exit"), and a quiet one has noExit:line, because there is no exit status.agentterm-mcp installprints the two edges this package is reached through:
the OpenCode plugin entry (the one file--writetouches, merging into the
existingpluginarray with a.bakfirst) and the MCP server block for
everything else (mcpServers,claude mcp add, or a printed TOML block for
Codex). Nothing is written without--write.
Third-party notices in the docs dialog
The Docs dialog has a third tab, Licences. It lists every installed package
grouped by licence, with the package count per group and name@version under it,
plus four credits lines for the projects this repository is built on. The package
data is generated at build time from bun pm licenses --json into
dist/licenses.json and served by GET /api/licenses, so the tab cannot fall out
of step with the lockfile. The artifact is sorted and stripped of paths and other
machine metadata, which makes a rebuild on an unchanged lockfile byte-identical.
Rolling the daemon from both surfaces
The daemon is machine state that every OpenCode instance on the machine shares:
one socket, one pid file, one process that owns every PTY. Until now the only
way to roll it was the /pty-daemon-restart command, and only the server half
answered it - so a surface that is not the server could not ask.
There is now one roll, reachable from everywhere:
- the TUI sidebar footer grows a second line,
daemon · restart, with the
pid of the daemon that answered the last roll. Clicking it rolls the daemon;
the line saysdaemon · restarting…while the roll runs and the result
arrives as a toast. - the web interface gets a Restart the daemon button in the settings,
with the answer next to the button. The button is disabled while a roll runs:
two rolls at once are how a machine ends up with two daemons.
Both ask the half that owns the client - the server half, over the plugin's own
RPC and over POST /api/daemon/restart respectively - because the daemon
belongs to the server, not to the surface that asks.
A roll ends every session the daemon owns: the PTY masters belong to that
process. The archive on disk survives.
Every roll is announced to every surface, marked with the id of the action that
started it. The surface that started it recognises its own mark and stays quiet (it
already shows the answer); every other one shows it. So a roll from the browser
reaches the TUI's sidebar, and the other way round.
The sidebar's line now shows the running daemon's pid, refreshed by the panel's
poll rather than only by its own roll, so a roll started anywhere is visible there
within a tick.
Toasts in the web interface
The web interface shows what the server half says: a slash command's result, a roll
started in another surface. The notice arrives over the WebSocket the page already
holds, with the same shape the TUI half turns into a toast.
Failed actions are toasts now too — input the server could not write, a session it
refused to remove, a bulk removal that failed, an undo that did not restore. They
used to be a line in the browser's console, which is to say invisible.
The toolchain is Bun's wherever Bun can do the job
bun check replaced tsc --noEmit for type checking, bun fmt replaced Biome's
formatter (configured through a [fmt] section in bunfig.toml; Biome keeps the
lint), and copyfiles was replaced by scripts/copy-tool-texts.ts. tsc stays
only as the emitter, for the two things Bun does not do: .d.ts and rewriting
.ts import specifiers to .js. The tree is formatted by bun fmt; the web
interface's typecheck no longer needs a build in the tree.
Fixed
-
bun auditwas run to the end, and the gate had been red for longer than
anyone knew. Four transitive advisories are overridden inside their carriers'
declared ranges (body-parser, twoundicimajors,zod);tomlis the one
that leaves a range, because its fix is a major bump and the alternative was a
gate that ignores three high advisories. No--ignoreremains. -
The typecheck needed a build in the tree (TASK-12): the web client imported
its own shared types by package name, which resolves through the export map into
dist/. Those imports are relative now, andbun checkpasses withdist/
deleted. -
A rebuild no longer white-screens a running interface. The static route map is
built once, at start, whileindex.htmlis read per request — so a rebuiltdist/web
handed the browser content-hashed asset names the running server had never seen. The
miss fell through to the redirect, and the browser got HTML for a.jsmodule: a white
page with a MIME-type error. A missing asset is now read from disk, and one that is
really absent answers 404 instead of the shell. -
A path the app does not have lands on
/, not on/index.html.
Security
ip-addressis overridden past a moderate advisory.ip-address@10.7.3
(Address6 matching a zone identifier in quadratic time) reached the lockfile
throughexpress-rate-limit— in the MCP SDK's express stack — and through
socks. Neither is instantiated here: the MCP route is stdio-only. The override
is inside the contract, since both carriers declareip-addressas^10.x.
v0.7.1
[0.7.1] - 2026-10-17
Fixed
The TUI session panel draws the colours the program used
The panel rendered a session's screen as plain text, so a program that paints - the
UEFI boot menu, ls --color, htop - arrived in black and white while the same
session was coloured in the web UI. The colour was never missing on the wire: the
server's screen render already resolved every cell's foreground, background and
attributes. It was dropped twice on the way to the panel - once when the decoder
kept only the rows, and once when the renderer drew one plain string.
The response now carries styledLines: the same runs as spans, but as text, so a
consumer without a terminal of its own can place the characters (a wide character is
one character and two cells, which is why cell coordinates alone were not enough).
The panel draws one <text> per run in a row box. Background padding survives - the
boot menu's blue box is a run of spaces carrying a background - while plain trailing
padding is still trimmed.
v0.7.0
[0.7.0] - 2026-10-17
Added
raw spawn option for PTY sessions
pty_spawn and the session-creation API accept raw: true, which disables the
PTY slave's line discipline (stty raw -echo) before the command runs. Use it for
a serial console (virsh console), a boot menu, or any program that expects a
\r to stay a \r.
Without it, the kernel's cooked discipline applies ICRNL and delivers Enter as
\n. A libvirt serial console showed its boot menu and relayed arrow keys, but
Enter did nothing - the byte was written and the program never saw it. Arrow keys
are escape sequences and are not translated, which is why only Enter was affected.
Raw mode turns ICRNL, ICANON, ISIG and ECHO off, so bytes arrive verbatim. It is
opt-in because a shell would lose line editing and the interrupt key.
pty_list and the <pty_spawned> result now report whether a session is raw.
Fixed
- Enter works on a serial console reached through
pty_spawn: the newrawoption
stops the line discipline from rewriting a carriage return into a line feed.
v0.6.0
[0.6.0] - 2026-10-15
Added
TUI sidebar panel
A PTY section in OpenCode's terminal sidebar, listing this project's sessions and
opening a session's live output in a dialog. Contributed additively through the
V2 TUI plugin API (Plugin.define plus the sidebar.content slot), so it sits
beside the built-in sidebar items rather than replacing them.
-
The server publishes its bound address to a small record under
$XDG_RUNTIME_DIR/opencode-pty/, which is how the panel finds it. A reader
validates every candidate with/health, and the owner removes its own record
on shutdown. -
Sessions now record
exitAt: when the process actually stopped, as opposed to
endedAt, which is written from the exit notification and lost on a restart. It
travels into the archive, which is what lets the dialog show a finished run's
duration. -
The panel polls rather than subscribing: the web UI has a WebSocket for this and
a TUI has no equivalent, soPOLL_MSis the floor for how stale it may look. -
The list is ordered with running sessions first, then finished ones newest first.
It holds every session the server knows, which on a machine with any history is
hundreds of records - and a live process below all of them is one you have to
scroll to find. The header's count stays the true total, so nothing is hidden. -
Once a start has failed repeatedly, the status names the gesture that still works
(toggle the panel again) rather than inviting a click that no longer starts
anything. -
The sidebar lists the running sessions, and the archive is one click away in the
footer. Measured on the author's machine the list held 200 entries in a ~40-column
sidebar, of which three carried news (exit 1,exit 2) and 197 wereexit 0; the
section also displaced the host's own MCP and LSP sections. Ordering could not fix
that, because a status strip cannot be a session manager. Sosidebar.contentdraws
one row per RUNNING session - or one dim line saying nothing is running - and a new
sidebar.footerslot carries the archive's size. Clicking that line expands the
finished runs that FAILED, newest first, capped at 10. Anexit 0is a record, not
an event: on a machine with history there are hundreds of them, and the only place
they are still browsable is the web UI. The header's count stays the true total, and
the footer names the archive rather than the rows on screen - when the cap cuts the
list it says so (10 of 17 failed). The line is absent when nothing failed, because
a click that opens nothing is a control with no answer. -
Opening the archive does not start a server. Expanding the panel is the only trigger
that does, and the sessions the archive shows are already in the panel state, so the
expansion needs no refresh at all. -
The sidebar has a filter, driven by the host's own prompt.
/pty-filterasks for a
query throughui.dialog.promptand stores it beside the collapsed flag, so the plugin
needs no text field and no key handling of its own. Matching is the SHARED rule
(filterGroups/sessionMatches) rather than a second matcher that would drift:
case-insensitive, over the conversation heading and every field a row shows, with a heading
match keeping its whole group. To let the panel use it, those functions are now constrained
on the fields they READ rather than onPTYSessionInfo- the same moveTimeOrderedwas -
because the panel carries a trimmed shape across a process boundary and itsargsis
optional, so the haystack tolerates a session with no command line at all. The header reads
N of 200while a filter is active, the query appears beside it as a clickable chip (the
way to clear it that needs no typing), and an empty body names the query instead of
claiming nothing is running. A dismissed prompt leaves the filter alone; an empty answer
clears it. The numerator counts what the body draws, so0 of 200and "nothing matches"
cannot contradict each other. -
The sidebar groups the running sessions by the conversation that started them. The
list was global: a conversation that had started no PTY still saw the whole machine's
sessions, and without the parent id by heart there was no way to tell whose process a row
was. Each group now carries one collapsible heading, titled through the host's own
data.session.getand falling back toSession <id>- orUngroupedfor a session
started by hand - with the same agent name the web sidebar shows. The fold is the host MCP
sidebar's idiom, copied: ONE mouse handler, on a chevron that appears only once a group is
big enough for folding to save something. A group of one or two is therefore always open,
so the collapse can never take the one live process out of sight. A group holding a
running session is drawn above one that only finished, and the group state is a durable
preference beside the collapsed flag. The grouping applies to the running set - the
archive in the footer stays a single count, because 200 sessions across 20 conversations
would be a wall of headings in a ~40-column sidebar. -
The output dialog uses a plain box rather than a scrollbox. Measured against
opentui 0.5.14: a scrollbox renders nothing when its text contains a line break,
andstickyScrolltogether withstickyStart: 'bottom'blanks it even for a
single line. The box shows exactly as many lines as it has rows, so the newest
output is what lands on screen. The full history stays in the web UI. -
opencode-pty/v2now also resolves/tui. OpenCode builds the TUI specifier from
the configured plugin name, so the documented V2 entry was probed as
opencode-pty/v2/tuiand the panel was never found - while the tools loaded
normally, which is what makes it a silent failure. Found by running OpenCode's own
resolver against the built package. -
opencode-pty/tuiis now a declared export. Theexportswildcards did not reach
it -./*matches one path segment and pointed atdist/src/tui.jsrather than
the directory'sindex.js- so opencode's resolver reported the plugin as having
no TUI feature, which reads as "the panel never appears" rather than as a
packaging mistake. -
@babel/core, pulled in by@opentui/solid's Babel plugin, is overridden past
advisory GHSA-4. Nothing here runs Babel; onlyjsx-runtimeis used. -
The session list is ordered by
exitAt, in the browser as well as the sidebar.
endedAtis lost across a restart - that is the reasonexitAtexists - so a restarted
session had no end time and fell back to its start when the list was ordered. A session
that finished twenty minutes ago therefore sorted ABOVE one that finished a minute ago,
on every surface.sortSessionsByTimenow prefersexitAt, thenendedAt, then
createdAt. -
One duration formatter with two presets.
formatDurationMsis the implementation;
compactgives2h 04mfor the web sidebar andprecisegives1m 05sfor the 40-column
one, both from the same arithmetic. The sidebar's run timer is no longer a second
implementation, and two surfaces can no longer disagree about how long a run was.
One deliberate behaviour change: a duration of zero or less now renders as EMPTY rather
than0s, because0sclaimed a run lasted nothing on a clock that cannot be trusted -
and the callers already render the empty case deliberately. -
The sidebar panel's ordering is now the shared rule plus one step of its own. The
partition (running above finished) stays local, because a live process below a page of
records is one you have to scroll to find. The order inside each half comes from the
shared sort, which also brought its deterministic tie-break: two sessions with the same
timestamp are separated by id rather than by whichever order the server sent them in. -
A
session.panelfor the PTYs of the conversation you are in. A PTY session belongs to
the OpenCode session that spawned it - the web UI groups its list byparentSessionIdfor
the same reason - so the panel claimssession.panel, the host's own place for an extra
view of a session, where Review and Files already live. Open it from the command palette
or/pty-sessions; no keybind is configured, because any guess could collide with the
host's own and the command has an id for the user's keymap config.
It lists this conversation's processes, one on screen, read on the same poll as the
sidebar - the panel's rows are a subset of that list, so a second fetch would be a second
answer to a question already answered. -
The freshness check asks the registry about the version a bump would take.
bun outdated
prints Current, Update and Latest, and the age lookup read only Update. For an exactly-pinned
dependency Update is the CURRENT version - there is nothingbun updatecan install inside
an exact pin - so the lookup returned an age of months and the gate could never wait such a
release out. It demanded a same-day bump instead, which is the outcomeminimumReleaseAge
exists to prevent, and the failure AGENTS.md records as "a gate stricter than the policy it
enforces will fail on every publish". One package gave two answers in the same run: the
@opencode/theme(dev)row looked up 2.0.23 and failed, the(peer)row looked up 2.0.24
and waited it out. The target is now Update when it differs from Current, Latest otherwise.
publishedAtreceives that version instead of the row, so which version is asked about is
assertable rather than something a test has to re-derive by parsing the table itself. -
serovalis overridden past a critical advisory thatsolid-jspins into the lockfile.
seroval@1.5.6carries GHSA-mv8w… (thenable assimilation, critical) plus a high one, and
solid-js@1.9.15pins~1.5.4for bothserovalandseroval-plugins. Only
solid-js/web/dist/server.jsimports it - Solid's SSR bu...
0.5.1 — the 0.5.0 tarball could not be installed
The 0.5.0 tarball could not be installed. This release fixes that and changes nothing else.
What was wrong
package.json declared patchedDependencies pointing at patches/ghostty-web.patch, but files listed only dist. The published package therefore contained a manifest referring to a patch it did not ship, and bun install in the extracted package failed with Couldn't find patch file.
It only shows up when you install the artifact — from a checkout the patch is sitting right there.
A note on the lockfile
Shipping bun.lock was considered and is not the fix. Neither npm pack nor bun pm pack includes it, which is why installing the tarball resolves ranges and lands on @opencode/plugin 2.0.23 rather than the locked 2.0.22. That is ordinary npm behaviour: clone the repository and you get exactly the tested graph, install the tarball and you get the newest matching versions.
Verified from this tarball, not from a checkout
bun install --productionsucceeds, 285 packagespty_spawnreturns<pty_spawned id=... cols=... rows=...>- the id appears in
pty_list pty_screenreturns the rendered text- a file that exists but is not executable is refused before the spawn
See CHANGELOG.md for the 0.5.0 changes.
0.5.0 — pty_screen, terminal geometry, and removal with undo
The web UI reaches parity with the tools, and the tools say what they did.
npm install -g opencode-pty # or drop the tarball into your node_modules
Full detail in the CHANGELOG below.
0.5.0 - 2026-10-04
The release that brings the web UI to parity with the tools, and makes the tools
say what they actually did.
Added
Tools
pty_screenreturns the rendered screen rather than the byte stream, so a TUI
can be read as a TUI instead of as escape sequences.pty_waitblocks until a session exits or produces matching output.- Every session is given a terminal size at spawn, and
pty_resizelets the
agent change it. A program that formats for 80 columns and is given 40 wraps in
the wrong places, and nothing in the output says why. - Sessions are archived to disk and readable after a restart. A restart is
announced, and a session that exists only in the archive is labelled as such
rather than looking like a live one. - The usage guide ships as an embedded skill, so an agent is told how to drive
the tools when it needs to.
Web UI
- Documentation dialog, split for humans and for LLMs. The LLM half is the same
document the plugin hands the agent, so both read one source. - Settings for theme, terminal font size and a debug bar.
- Session search, matching the parent OpenCode session as well as the process.
- PTYs grouped by the OpenCode session that created them.
- Download a transcript as text, with or without control characters.
- Bulk removal with undo. Finished sessions move to the trash and come back;
running sessions are stopped, and the confirmation names both numbers, because
they are not the same kind of action. - Version and Git commit of the build that is actually running.
Terminal
- The terminal renders through ghostty-web: a full palette, adaptive light and
dark themes, bounded colour queries, mouse reporting, and copyable output
without a canvas selection.
Changed
pty_readno longer clamps lines silently. It applies a disclosed budget and
tells you what it cut, with a cursor to continue from, so a truncated read can
no longer be mistaken for the end of the buffer.- Every result tag carries
id="..."as an attribute. Four of the nine tags only
mentioned the id in prose, and a model that learned the convention from the
others looked for an attribute that was not there. - Exit notifications are observable and say so when they cannot be delivered,
instead of failing quietly. - The web UI holds one WebSocket connection and no longer polls.
- Tool descriptions say which tool answers a question, rather than describing
the whole surface.
Fixed
- A command that cannot be executed is refused before the spawn. It used to start,
then abort inside the PTY helper, which surfaced as a plugin crash and left the
session reportingrunningafter the process was gone. pty_screenreports the wrap on the row that continues rather than the row that
ran out.- Terminal size is resolved once at spawn and recorded, instead of being
re-derived at each use and ending up reporting a size it is not running at. - The V2 plugin survives a single failed registration step instead of losing the
whole plugin, and its notifications carry a message id the host accepts. - The web server falls back to a free port when the preferred one is taken, and no
longer hard-caches the HTML shell. - Terminal streaming is gap-free across a snapshot and the delta stream that
follows it, and the grid stays fitted to its pane. - ghostty-web: reset handlers stay live, resolved black backgrounds render, and a
terminal reset no longer loses the selection. - Builds stamp their identity into
dist/rather than the source tree, so a build
no longer leaves the working tree dirty.
Security
- Socket.dev scans every push, not only a local machine, and the local quality gate
fails on a finding. - A high-severity advisory in a transitive dependency of the OpenCode plugin SDK
is resolved. - Exit-notification delivery failures are logged rather than swallowed.