AGENTS.md 现在与其他 sibling 仓库逐字节一致,只保留提交纪律; 项目背景、测试与验证、实现约定、发布与文档维护移入新增的 CONTRIBUTING.md。 Co-Authored-By: opencode v2.3.2
opencode-command-window
The GitHub repository https://github.com/duzhaokun123/opencode-command-window is a mirror. The canonical repository is https://git.o0kam1.dev/HumanlessCode/opencode-command-window; code changes and pull requests belong there. GitHub issues are welcome for questions and discussion.
An unofficial OpenCode V2 server plugin that gives the built-in shell tool explicit output windows: tail, head, lines, and max_bytes.
The default shell tool keeps only the end of large output and saves the rest to a file. Piping a command through head or tail hides the total line count and the saved path. This plugin lets the model ask for the range it actually needs, after the command has run, without rerunning it, and by default tells the model to use those parameters instead of piping.
Requirements
- OpenCode v2.3.0 or newer.
- Node.js and pnpm only when you install from source.
Install
Install the package with the OpenCode CLI:
opencode plugin add @o0kam1/opencode-command-window
Or add it to plugins in opencode.json(c):
{
"plugins": ["@o0kam1/opencode-command-window"]
}
Reload OpenCode (/reload) or restart it. The plugin id is command.window, which differs from the package name: use the id when you disable or configure the plugin.
To run unreleased code, clone the repository into the global plugin directory and install its dependencies:
git clone https://git.o0kam1.dev/HumanlessCode/opencode-command-window.git \
~/.config/opencode/plugins/command-window
cd ~/.config/opencode/plugins/command-window
pnpm install --prod
OpenCode loads directories under a config location's plugins/ folder. If you keep the clone somewhere else, add its absolute path to plugins in opencode.json(c):
{
"plugins": [{ "package": "/absolute/path/to/command-window" }]
}
Configuration
The plugin works without configuration: it adds the tail, head, lines, and max_bytes parameters to shell, applies them to each result, and injects both system prompt paragraphs for primary requests. To change that behavior, declare the plugin in opencode.json(c) with an options object. Every key is optional.
{
"plugins": [
{
"package": "@o0kam1/opencode-command-window",
"options": {
// Opt-in: rewrite a trailing `| head` / `| tail` into window parameters.
"pipeWindow": true,
// Opt-in: warn when a finished command still piped through head or tail.
"pipeWarning": true,
"pipeWarningText": "Use the shell window parameters instead of piping through head or tail.",
// Both prompt paragraphs are on by default.
"windowHint": true,
"windowHintText": "Limit output with the shell window parameters instead of piping through head or tail.",
"readBack": true,
"readBackText": "Saved shell output is in the reported file; read it instead of rerunning the command."
}
}
]
}
Options are read once when the plugin loads. After editing them, run /reload or restart OpenCode.
Command options
| Option | Type | Default | Meaning |
|---|---|---|---|
pipeWindow |
boolean | false |
Rewrite a trailing | head/| tail pipe in the command into the head/tail window parameters before the command runs. |
pipeWarning |
boolean | false |
Prepend a [window warning: ...] note to a completed shell result when the command still piped through head or tail. |
pipeWarningText |
non-empty string | built-in text | Replace the warning text. Used only when pipeWarning is true. |
Prompt options
| Option | Type | Default | Meaning |
|---|---|---|---|
windowHint |
boolean | true |
Inject the output-window paragraph into primary requests that expose the shell tool. |
windowHintText |
non-empty string | built-in text | Replace the output-window paragraph. Used only when windowHint is true. |
readBack |
boolean | true |
Inject the read-back paragraph into primary requests that expose the read tool. |
readBackText |
non-empty string | built-in text | Replace the read-back paragraph. Used only when readBack is true. |
Notes:
- Options only come from a
pluginsentry. A plugin discovered under a config location'splugins/folder receives empty options; declaring the same package or absolute directory inpluginssupplies options and replaces the discovered entry. - Both prompt paragraphs are injected only into
contexthook requests (primary agent requests);compactionandgenerateonly refresh theshelltool description. The window paragraph requires the request to exposeshell; the read-back paragraph requiresread. pipeWindowis off by default because it changes the command before it runs. When enabled, a command ending in\| head/\| tailwith an explicit line count (-n N,-NN,--lines=N,--lines N) is rewritten to run at full width, with the count moved into thehead/tailparameter, so the marker reports the total line count and the saved-output path. Only one trailing segment is rewritten; head-then-tail chains, a barehead/tailwithout a count, byte mode (-c), other flags, extra arguments, quoting or substitution, and calls that already carry window parameters are left untouched. So are commands that join another command (&&,||,;,&, or a newline), because the pipe only sees the last pipeline while the window would cover the whole output.pipeWarningis off by default. When enabled, a completed shell call whose command pipes output throughheadortailgets the note prepended to the result, so the model reads the warning first. Detection looks at every|at shell quoting depth 0, so it also catches joined commands (cd /tmp && … | tail) and forms the rewriter refuses (| head -c 100, a bare| head, extra arguments); quoted pipes and||/|&do not count. Running and killed results are left alone. A trailing pipe already rewritten bypipeWindowis gone before the command runs, so it triggers no warning.- The window parameters, the appended
shelldescription, and theexecute.afterwindow application are always active; no option turns them off. - Invalid values fall back to their defaults and log one
[command.window]warning per key. Booleans must be actual booleans; text options must contain non-whitespace characters after trimming, so a whitespace-only string is rejected. Unknown keys are ignored, and option errors never prevent the plugin from loading. - The window paragraph tells the model to pass
tail,head,lines, ormax_bytesinstead of appending| heador| tailto the command, because piping hides the total line count and the saved path and can stop the command early. Content filters such asgrepstill belong in the command. - The read-back paragraph tells the model to continue reading a saved output file with
read(offset/limit, at most 2000 lines per call) instead of rerunning the command. Reading a file outside the workspace can ask for directory approval. - Each paragraph adds a fixed amount of input tokens to every primary request.
Usage
Call shell as usual and add one window parameter:
{ "command": "pytest -q", "tail": 40 }
{ "command": "npm test", "head": 20, "tail": 20 }
{ "command": "cat huge.log", "lines": { "start": 120000, "end": 120050 } }
{ "command": "tar -tf archive.tar", "lines": { "start": 5000 } }
{ "command": "cargo build", "tail": 200, "max_bytes": 1048576 }
| Field | Type | Meaning |
|---|---|---|
tail |
integer ≥ 0 | Return the last N lines. |
head |
integer ≥ 0 | Return the first N lines. |
lines |
{ start, end? } |
Return the 1-based inclusive range. Omit end to read to the end. |
max_bytes |
integer 1–5242880 | Hard cap on the UTF-8 bytes of the window body. Defaults to 204800. |
To limit how much output comes back, pass these parameters instead of appending | head or | tail to the command: piping hides the total line count and the saved path, and can stop the command early. Filtering by content (for example grep) still belongs in the command. With pipeWindow enabled, a trailing \| head/\| tail pipe with an explicit line count is rewritten into these parameters before the command runs.
Rules:
tailandheadmay be combined to return both ends. The body then contains a[... N lines omitted ...]placeholder.linescannot be combined withtailorhead.tail: 0andhead: 0mean "not set".max_bytesalone does not open a window.- Without any window parameter the result is left exactly as OpenCode produced it.
What comes back
The body is followed by one marker paragraph:
[showing lines 199998-200000 of 200000 (tail 3); full output saved to /home/me/.local/share/opencode/shell/0123456789abcdef/sh_abc.out]
[showing lines 1-5 and 119996-120000 of 120000 (head 5, tail 5); full output saved to /home/me/.local/share/opencode/shell/0123456789abcdef/sh_abc.out]
[showing lines 120000-120050 of 120051 (lines 120000-120050); full output saved to /home/me/.local/share/opencode/shell/0123456789abcdef/sh_abc.out]
[showing lines 1-2 of 3 (head 2); full output was not saved because the result was not truncated]
The total line count is always reported. When OpenCode saved the complete output, the marker contains the file path, so a later read can return another range without rerunning the command: use the read tool on that path with offset and limit, or call shell again with lines when the command is cheap. When the output was complete inline, no file exists and the marker says so instead of inventing a path.
Marker notes:
capped at N bytes: the byte cap stopped the window before it was complete.scan stopped after 5000 ms: the five-second scan budget ran out; the total is reported asat least N.max_bytes clamped to 5242880: the requested cap was above the maximum.no lines in the requested range; total N: the range starts past the end.(no output): the command produced no output.
Behavior details
- OpenCode's saved output file is the preferred source. Complete inline output is scanned directly.
- If only a truncated preview is available because the saved file is gone, the plugin leaves the preview untouched and prepends
[window not applied: ...]. - Binary output is replaced with a byte-count description instead of being decoded.
- Background results that are still running, and killed results, are never windowed.
- Exit-code and timeout notices are content parts, not the body; they are preserved.
- Memory use is bounded by
max_bytes; the scan never buffers the whole output. The scan budget is five seconds. - The command is never rerun, rewritten, or filtered through another process.
- Windowed results set
metadata.truncatedand addmetadata.windowwithmode,shownLines,totalLines,maxBytes, andclamped.
Limitations
- No
grep, regex, or context filters. Filter with the command itself when you need matching lines. - Ranges are line-based.
max_bytesonly caps the result; it cannot address a byte range. - The plugin does not clean up OpenCode's saved output files.
- A window cannot recover output that OpenCode already discarded before saving a file.
- The truncation parameters are not shown in the interface. The plugin has no TUI or GUI part because OpenCode v2.3.0 provides no renderer for a tool call row, so no client can label a call with the parameters the model chose. They appear only in the marker at the end of the returned text, and in
metadata.windowon the tool result; when the output is collapsed, the user must expand it to read them.
Uninstall
opencode plugin remove @o0kam1/opencode-command-window
For a source clone, remove its directory (or its plugins entry) instead, then reload OpenCode.
Development
pnpm install
pnpm check # tsc --noEmit && vitest run
| Path | Purpose |
|---|---|
src/index.ts |
Plugin wiring: options, schema and description transforms, system prompt injection, execute.before and execute.after hooks. |
src/options.ts |
Plugin option validation and defaults. |
src/prompt.ts |
Window-parameter and read-back paragraphs, plus idempotent system part injection. |
src/schema.ts |
Replacement shell input schema and the appended description. |
src/pipe.ts |
Trailing | head/| tail pipe parsing, in-place rewrite of one shell call, and detection for the warning. |
src/warn.ts |
Prepends the advisory note when a completed shell call piped through head/tail. |
src/window.ts |
Parameter parsing and marker rendering. |
src/scan.ts |
Streaming file and text scans with byte caps. |
src/apply.ts |
Applies a window to one completed tool result. |
Manual verification
- Install the plugin and reload OpenCode.
- Run
seq 1 200000with{"tail": 3}. The marker must report lines 199998–200000 of 200000 and the saved path. - Run the same command with
{"head": 3, "tail": 3}. The body must contain one omitted-lines placeholder. - Run it with
{"lines": {"start": 100000, "end": 100003}}. Exactly four lines must come back. - Run
seq 1 5with{"tail": 2}. The marker must say the result was not truncated. - Combine
lineswithtail. The result must start with[window error: ...]and keep the default preview. - Start
sleep 5with{"background": true, "tail": 1}. The running result must be untouched. - Run
seq 1 200000with{"tail": 3}and then ask the model to show another range. It must read the reported file with thereadtool instead of rerunning the command. - Ask the model to inspect a command that produces large output. It must pass
tail,head, orlinesinstead of piping the command throughheadortail. Then setwindowHinttofalse, reload, and confirm the paragraph is no longer injected. - Set
pipeWindowtotrue, reload, and runseq 1 100 | tail -n 3. The command must execute at full width and the marker must report lines 98–100 of 100 with the saved-output path when the result is truncated. Then disablepipeWindowagain and confirm the same call keeps the pipe. - Set
pipeWarningtotrue, reload, and runseq 1 100 | tail -n 3. The result must begin with[window warning: ...]and still contain only the last lines as the default preview. Then disable it and confirm the same call comes back without the note. - Check
~/.local/share/opencode/log/opencode.logfor[command.window]warnings.