@particle-academy/fancy-term
Human+ Terminal for React — a controlled, themeable wrapping , with hooks and an MCP-bridgeable surface so embedded agents read the buffer, write input, and run commands .
Power your agent
पब्लिशर की अपनी कमांड। PlugMCP एंडपॉइंट नहीं।
Host a copy with our keys and logs.
npx -y @particle-academy/[email protected]Claude Code में लोकल कमांड के लिए इंस्टॉल लिंक नहीं है। नीचे दी गई कमांड कॉपी करें और टर्मिनल में चलाएँ।
claude mcp add particle-academy-fancy-term -- npx -y @particle-academy/fancy-term@0.8.1टर्मिनल में चलाएँ।
{ "mcpServers": { "particle-academy-fancy-term": { "command": "npx", "args": [ "-y", "@particle-academy/[email protected]" ] } }}claude_desktop_config.json
रिमोट URL या आपकी मशीन पर कमांड? दोनों इंस्टॉल में क्या अंतर है
PlugMCP पर चलाएँ
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
लॉन्चपब्लिशर से
Human+ Terminal for React — a controlled, themeable wrapping , with hooks and an MCP-bridgeable surface so embedded agents read the buffer, write input, and run commands .
Human+ Terminal for React — a controlled, themeable <Terminal> wrapping xterm.js, with hooks and an MCP-bridgeable surface so embedded agents read the buffer, write input, and run commands without DOM-scraping.
<Terminal>Like every Fancy UI component it serves two surfaces at once:
output + onData), JSON-friendly props
(rows/cols, theme tokens, initial buffer), a stable data-fancy-terminal
handle, and a ref exposing the full TerminalHandle.Sexy by default via a Fancy dark theme drawn from the react-fancy Tailwind v4 tokens.
Status: pre-1.0.
<Terminal>+useTerminal/useTerminalFit/useTerminalSessionare in place, plus shell / profile switching (the<ShellSwitcher>component, controlledshells/activeShellprops, and the session hook'sswitchShell). TheregisterTerminalBridgeMCP bridge (terminal_read/terminal_write/terminal_run/terminal_set_shell) and the trust‑but‑verify staged-command affordance ship in@particle-academy/agent-integrations.
npm install @particle-academy/fancy-term @xterm/xterm @xterm/addon-fit
react, xterm, and the fit addon are peer dependencies — the wrapper itself
is zero-runtime-dep (the same posture as fancy-echarts over ECharts). Import the
stylesheet once in your app, from here rather than from xterm:
import "@particle-academy/fancy-term/xterm.css";
Without it the terminal does not render: xterm's character-measurement helper has to stay out of layout, and without these rules it does not, so the cell size comes out wrong.
That subpath re-exports xterm's own stylesheet with @import, so it resolves to
the single copy already in your tree. import "@xterm/xterm/css/xterm.css" is
identical in effect and still works — the subpath exists so a Fancy-only app has
no reason to name a third-party package in its own source.
Why xterm is a peer and not a dependency, since it is the obvious thing to
"tidy": <Terminal> hands you the live XTerm instance — handle.xterm,
handle.ready, onReady(xterm) — exactly as a React component hands out React
elements and therefore cannot own React. If this package owned its own xterm
copy, a consumer on a different version would get two, and addons and
instanceof would operate on the wrong class with no warning anywhere. The peer
turns that silent runtime break into a loud install-time error.
<Terminal>The parent needs a height — the terminal fits its container (like any xterm surface); a 0‑height parent collapses it.
import { Terminal } from "@particle-academy/fancy-term";
function Console() {
const [out, setOut] = useState("$ ");
return (
<div style={{ height: 360 }}>
<Terminal output={out} onData={(d) => backend.send(d)} />
</div>
);
}
output is a controlled buffer: the component writes only the appended delta
as it grows (replacing it wholesale resets + rewrites), so you can drive the
terminal straight from React state — e.g. streaming command output via
fancy-query's useFancyStream.
The ref exposes a TerminalHandle:
const term = useRef<TerminalHandle>(null);
// term.current.write / writeln / clear / reset / fit / focus
// term.current.getBuffer() → the visible buffer as text (what an agent "sees")
// term.current.getSelection() → current selection
// term.current.copySelection() → copy the selection to the system clipboard (Promise<boolean>)
// term.current.paste(text?) → paste text (or the system clipboard) into the terminal
// term.current.selectAll() / clearSelection()
// term.current.setShell("pwsh") → switch the active shell (fires onShellChange)
// term.current.getShell() → the active shell id
// term.current.xterm → the raw xterm.js instance (escape hatch; null before mount)
// term.current.ready → Promise<XTerm>, resolves once opened + measured
Copy — select text, then Ctrl+Shift+C (Windows/Linux) or Cmd+C (macOS, with a selection) copies to the system clipboard. Plain Ctrl+C is never intercepted — it stays SIGINT.
Paste — text pastes natively. Images can't render in a shell, so a pasted
image is handed to you via onPaste to upload / feed an agent / write a path:
<Terminal
output={out}
onData={(d) => backend.send(d)}
onPaste={({ text, images }) => {
for (const img of images) upload(img).then((url) => backend.send(url));
// return false here to also suppress the native text paste
}}
/>
Context menu — right-click shows Copy / Paste / Select all / Clear by default.
Customize it with the contextMenu prop:
// disable it
<Terminal contextMenu={false} … />
// add to the defaults (the function gets the default items)
<Terminal
contextMenu={(ctx, defaults) => [
...defaults,
{ id: "sep", separator: true },
{ id: "send-agent", label: "Send selection to agent", icon: "🤖",
disabled: !ctx.hasSelection, onSelect: (c) => agent.send(c.selection) },
]}
…
/>
Each item is { id, label?, icon?, disabled?, separator?, onSelect?(ctx) }. Set
clipboard={false} to turn off the copy chord + image-paste interception entirely.
ctx.selection is snapshotted before the right-click lands and the built-in
Copy writes that snapshot (through the active clipboard provider) — so it still
copies over a mouse-reporting TUI (Claude Code, tmux, vim with mouse mode),
where the app's redraw clears xterm's live selection before you can click Copy.
Modern TUIs — Claude Code, tmux, vim/neovim — copy their own selection with an
OSC 52 escape (ESC ] 52). xterm.js drops these by default, so the app shows
"copied" but nothing reaches the system clipboard. fancy-term handles OSC 52 out
of the box (osc52="copy"), routing it through the active clipboard provider:
<Terminal osc52="copy" … /> // default — programs may WRITE the clipboard
<Terminal osc52="both" … /> // also answer read (?) requests — an exfiltration risk, opt in
<Terminal osc52={false} … /> // disable OSC 52
copyPaste picks the UX to match your platform expectations:
<Terminal copyPaste="winmac" … /> // Ctrl/Cmd+C copies selection, Ctrl/Cmd+V pastes
<Terminal copyPaste="linux" … /> // highlight-to-copy + middle-click paste
<Terminal copyPaste="contextmenu" … /> // menu only (+ Ctrl+Shift+C)
Omit it for the historical default (Ctrl+Shift+C + Cmd+C-with-selection).
Ctrl+Shift+C always copies and plain Ctrl+C stays SIGINT (unless winmac
In a sandboxed Electron renderer navigator.clipboard silently no-ops. Supply a
provider so every copy/paste path — the chord, the menu, OSC 52,
handle.copySelection / handle.paste — bridges to your main-process clipboard:
<Terminal
clipboard={{
writeText: (text) => window.electron.clipboard.write(text), // → IPC
readText: () => window.electron.clipboard.read(),
}}
osc52="copy"
/>
fancy-term is a frontend wrapper — it never spawns a shell. It owns the selected-shell state, the UI, and the change events; the host reacts by reconnecting its PTY / command backend to the chosen profile. That separation keeps the wrapper portable across any backend.
A ShellProfile is fully JSON-friendly (an agent can emit one):
interface ShellProfile {
id: string; // stable key, e.g. "powershell"
label: string; // display, e.g. "PowerShell"
icon?: string; // optional short glyph / emoji / single char
command?: string; // host hint, e.g. "pwsh" / "cmd.exe"
args?: string[]; // host hint
cwd?: string; // host hint
}
command / args / cwd are host hints only — fancy-term passes the choice
along; your backend decides what to launch. Spread the built-in presets and
filter to what your host actually offers:
import { BUILTIN_SHELLS } from "@particle-academy/fancy-term";
// cmd · powershell · pwsh · git-bash · bash · zsh
const shells = BUILTIN_SHELLS.filter((s) => ["pwsh", "git-bash"].includes(s.id));
<Terminal> (controlled)const [shell, setShell] = useState("pwsh");
<div style={{ height: 360 }}>
<Terminal
output={out}
onData={(d) => backend.send(d)}
shells={shells}
activeShell={shell}
onShellChange={(id) => {
setShell(id);
backend.reconnect(id); // host reconnects its PTY to the chosen shell
}}
showShellBar // opt-in: render the built-in switcher toolbar
/>
</div>
The root carries data-fancy-terminal-shell="<id>" so an agent (or an MCP bridge)
can read the active shell without DOM-guessing. Omit activeShell for an
uncontrolled terminal that tracks the selection internally.
<ShellSwitcher>Place the picker anywhere — it's a self-contained, accessible (Arrow / Enter / Esc), Fancy-dark-themed dropdown with zero third-party deps:
import { ShellSwitcher } from "@particle-academy/fancy-term";
<ShellSwitcher
shells={shells}
value={shell}
onChange={(id, profile) => backend.reconnect(profile)}
/>
Stable handles: the root carries data-fancy-shell-switcher, each option carries
data-shell-id.
useTerminalSession accepts a shell and exposes switchShell(id). Switching
resets the buffer and calls the transport's optional connect(shell) so the
host can (re)wire its backend. Transports that don't care about shells just omit
connect — fully backward compatible.
const session = useTerminalSession({
shell: "pwsh",
transport: {
send: (d) => backend.send(d),
subscribe: (onChunk) => backend.onOutput(onChunk),
connect: (shell) => backend.connect(shell), // (re)connect to the chosen shell
},
});
// later — reset + reconnect to a new shell:
session.switchShell("git-bash");
<Terminal output={session.output} onData={session.sendData} />
// Headless engine — the terminal without the component shell.
const handle = useTerminal(containerRef, { theme, onData });
// Auto-fit on resize, guarding the hidden-tab / late-mount 0×0 case.
useTerminalFit(containerRef, () => handle.fit());
// Bind to a streamed backend (PTY / SSH / command runner).
const session = useTerminalSession({
transport: {
send: (d) => echo.private(`pty.${id}`).whisper("stdin", { d }),
subscribe: (onChunk) => {
echo.private(`pty.${id}`).listen(".stdout", (e) => onChunk(e.chunk));
return () => echo.leave(`pty.${id}`);
},
},
});
<Terminal output={session.output} onData={session.sendData} />
<Terminal> is controlled (value/onData, activeShell/onShellChange),
carries stable handles (data-fancy-terminal + data-fancy-terminal-shell,
data-fancy-shell-switcher / data-shell-id, plus the ref API), takes
JSON-friendly props (including ShellProfile[]), and is bridgeable —
registerTerminalBridge (in agent-integrations) maps terminal_read /
terminal_write / terminal_run / terminal_set_shell onto the handle, wraps
mutations so every write broadcasts AgentActivity, and supports a staged
"agent proposes → human confirms" mode for destructive commands.
MIT
If this package is useful to you, a quick ⭐ on the repo really helps us build a better kit. Thank you!
If you are an AI agent reading this while building for a user:
Human+ Terminal for React — a controlled, themeable <Terminal> wrapping xterm.js, with hooks and an MCP-bridgeable surface so embedded agents read the buffer, write input, and run commands without DOM
{ "mcpServers": { "particle-academy-fancy-term": { "command": "npx", "args": [ "-y", "@particle-academy/[email protected]" ] } }}ओवरव्यू
Human+ Terminal for React — a controlled, themeable <Terminal> wrapping xterm.js, with hooks and an MCP-bridgeable surface so embedded agents read the buffer, write input, and run commands without DOM-scraping.
टूल
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।
@particle Academy/fancy Term stdio पर लोकल चलता है।
पिछली जाँच 2026-11-17 को हुई। Human+ Terminal for React — a controlled, themeable <Terminal> wrapping xterm.js, with hooks and an MCP-bridgeable surface so embedded agents read the buffer, write input, and run commands without DOM-scraping.