GyShell

The AI-Native Terminal that thinks, executes, and collaborates with you.

English README | 中文 README
Latest release notes: changelogs/v1.4.3.md

If you have any suggestions or questions, please feel free to submit them in GitHub Discussions.

Usage guides: docs/mobile-web-usage.md · docs/tui-usage.md · docs/gybackend-usage.md

Tip

Recommended Models:

• Cost-Performance: Thinking-GLM 5 + Action/Global-Minimax2.5
• Best Performance: Thinking-Gemini 3.1 Pro + Action/Global-Gemini 3 Flash
• Local (Mac Studio): Qwen3.5 / Minimax2.5

Warning

Active Development: GyShell evolves quickly. If a version introduces history compatibility breaks, it will be called out explicitly in release notes.

Note

v1.4.0 upgrade note: the first launch after upgrading from a pre-1.4.0 version may briefly block while GyShell migrates legacy JSON history into SQLite and writes timestamped backup files. v1.4.3 has no additional migration step.

gyshell_demo_10mb.mp4

---

Why GyShell Is Different

Most AI terminal tools either generate one-shot scripts, or run in isolated sandboxes detached from real shell workflows.

GyShell is built for persistent execution in your real terminal runtime:

• Persistent execution loop: observe output -> reason -> continue.
• Human-in-the-loop by design: intervene anytime without breaking flow.
• Multi-tab orchestration: compile, inspect logs, and run fixes in parallel tabs.
• Workspace persistence: terminal tabs and panel layout can survive restarts and restore quickly.
• Detachable multi-window workspace: peel panels into sub-windows and move tabs or whole panels across windows.
• Adaptive panel tab display: keep full tab strips or switch to a compact selector for narrow panel headers.
• Integrated file management: browse, edit, copy, and transfer files across local and SSH sessions without leaving the workspace.
• Live resource visibility: inspect CPU, memory, disks, network, processes, sockets, and GPU from local or SSH sessions.
• OpenClawd-style remote conversation control: keep the runtime core on your own computer and steer it from anywhere through chat.
• Built-in mobile-web delivery: desktop can publish the mobile-web companion directly over your LAN with copyable access links.
• Cross-surface runtime model: desktop, TUI, and mobile-web share one gateway semantics.
• Profile lock safety: busy sessions pin active model profile for consistency.
• Long-horizon context quality: memory.md + compaction summary pipeline keeps long sessions useful.
• Tooling-native workflow: skills, MCP servers, and built-in tools are runtime primitives.

At a Glance

• For shipping work: not just planning, but iterative execution and correction.
• For long-running tasks: preserves session continuity and state across steps.
• For real infrastructure: shell, SSH, forwarding, file management, and multi-tab interactive terminal control.
• For multi-device flow: desktop + TUI + mobile-web with shared gateway semantics.
• For multimodal workflows: text and image inputs can be combined in one execution turn.

v1.4.3 Key Highlights

• Image and PDF preview in the file editor
  • the built-in editor now opens images (png, jpg, gif, webp, bmp, ico, svg, avif) and PDFs inline — page navigation, zoom, and page indicator included
  • the editor panel is now called File Editor rather than Text Editor, since it is no longer text-only
• "Keep Both" when pasting into a folder with name conflicts
  • the paste conflict dialog now offers Keep Both alongside Overwrite — conflicting items are pasted in with auto-numbered suffixes (e.g. report.pdf → report (2).pdf) so existing files stay untouched
  • conflict handling is unified across local and SSH transfers via an end-to-end conflictStrategy (error / overwrite / rename)
• Copy Full Path(s) from the file row right-click menu
  • right-click a file or folder to copy its absolute path (or multiple paths if multi-selected) to the system clipboard, ready to paste into a terminal, chat, or editor
• More reliable SSH SFTP writes
  • the chunked write API now closes the SFTP handle on the final chunk and on empty-file writes, so handles release cleanly instead of being held until session GC
• Seamless tool groups are visibly expandable
  • the chevron is visible at rest (no longer hover-only) and applies to single-step groups too, so it's always clear that a group can be expanded
  • expanding a group reveals the full, untruncated call info for each step — full command, full tool args, full file path. Tool output is still not exposed
  • the N steps count now has correct spacing instead of hugging the title
• Compact horizontal monitor: correct bar heights
  • DISK / LOAD / RX bars used to collapse to a thin sliver in the compact horizontal layout while CPU / MEM / TX rendered correctly — all bars now resolve their percentage heights consistently, and 0% bars are intentionally hidden so "no signal" is visually distinct from "low signal"

---

Key Capabilities

AI-Native Runtime

• Thinking-oriented execution for complex tasks.
• Context-aware responses from terminal state and selected resources.
• Per-profile model routing for Global, Thinking, Action, and Compaction roles.
• Long-session context quality with dedicated compaction models and dynamic compaction summaries.
• SQLite-backed conversation history with automatic one-time migration from legacy JSON storage.
• AI-assisted terminal command drafting from recent tab context, with paste-before-run control.
• Background (nowait) commands automatically notify the agent on completion, so the agent can close the loop without polling.
• Classic or Seamless chat activity display, depending on how much inline tool detail you want.
• Persistent global memory injection via memory.md.
• Multimodal user input pipeline (text + images) for compatible models.
• OpenAI-compatible model endpoint support.

Terminal + SSH + File Management

• Shell support: Zsh, Bash, PowerShell.
• Older Windows PowerShell environments now use more reliable sidecar-based command completion tracking for local and SSH sessions.
• SSH support: password/key auth, proxy chaining, bastion workflows.
• Port forwarding: local, remote, and dynamic SOCKS.
• Agent can coordinate multiple SSH/local terminal tabs in parallel during one task.
• Control-character operations for interactive terminal apps.
• Draft a command for the current terminal tab from recent visible output, then paste it back without auto-running it.
• Search within the active terminal buffer without leaving the panel.
• Terminal tab restoration after backend restart, plus lossless output catch-up for renderer remount/reconnect within the same backend runtime.
• Integrated file browser panel: browse, create, rename, delete, preview, sort, filter, and search files across local and SSH sessions.
• Cross-session file transfer (copy/move) with real-time progress, cancellation, and adaptive SFTP tuning.
• Built-in file editor panel for editing text files, plus inline preview of images (png/jpg/gif/webp/bmp/ico/svg/avif) and PDFs (with page navigation and zoom), all directly in the workspace.
• File row right-click menu with Copy / Cut / Paste / Rename / Delete and Copy Full Path(s) to the system clipboard.
• Paste conflict resolution: choose between Overwrite and Keep Both (auto-numbered names) when pasting into a folder with same-named items.

Workspace + Monitoring

• Detach panels into dedicated sub-windows and move tabs or whole panels across windows.
• Choose Auto, Expanded, or Select panel tab display modes based on how much header space your workspace has.
• Ctrl/Cmd+F opens a panel-local find bar in terminal, current chat, file browser, and file editor.
• Open a resource monitor panel for local and SSH terminals from the workspace rail.
• Monitor panel surfaces CPU, memory, disk, network, process, socket, and GPU telemetry when available.
• Monitor collection is shared across tabs that point at the same local or SSH target, with failover if the original source tab exits.
• Monitor polling can be paused or resumed per local/SSH source, with the preference kept across restarts.
• Compact monitor layouts now give GPU telemetry its own card with clearer VRAM usage details.

Skills + MCP + Tools

• Folder-based skills workflow compatible with agentskills-style structure.
• Dynamic MCP server integration.
• Precision editing tools for safe, targeted file updates.
• Runtime tool toggles and summaries exposed to clients.

Mobile-Web Companion

• Mobile-first remote client for active session tracking and steering.
• Desktop can serve the mobile-web companion directly and expose copyable access links from settings.
• OpenClawd-style conversational control from anywhere while your core runtime stays on your own machine.
• Session list with search and status hints.
• Swipe-to-delete session flow for faster mobile cleanup.
• Detailed turn event inspection from phone browser.
• Tool/skill/terminal/settings access through gateway RPC.
• Gateway exposure can now be limited to localhost, LAN-only, custom CIDR ranges, or all interfaces.

---

Platforms

1. Electron desktop app (apps/electron)
2. Standalone backend runtime (apps/gybackend)
3. TUI runtime (apps/tui wrapper + packages/tui core)
4. Mobile-web runtime (apps/mobile-web wrapper + packages/mobile-web core)

Which Surface Should You Use?

• Desktop app: primary full-featured experience for daily development.
• TUI (gyll): terminal-native flow for keyboard-first sessions and automation, including multi-tab command orchestration.
• Mobile-web: OpenClawd-style remote conversational control from phone/browser.

---

Quick Start

Prerequisites

• Node.js 18+
• npm

Development

git clone https://github.com/MrOrangeJJ/GyShell.git
cd GyShell
npm install
npm run dev

First-run CLI experience

After desktop installation and first launch:

gyll --help
gyll "Plan and execute: run tests, fix failures, and summarize changes"

One-line Mental Model

GyShell = persistent AI runtime + real terminal control + human override at any time.

Mobile-web development

npm run dev:mobile-web

TUI development

npm run dev:tui

---

Desktop Bundled CLI (gyll)

After installing and launching GyShell desktop once, gyll is available from the desktop runtime setup.

If --url is not provided, CLI will try the local desktop backend (127.0.0.1:17888 by default).

gyll --help
gyll --url ip:port
gyll --url ip:port --token <access_token>
gyll --url ip:port "Hello"
gyll --url ip:port --token <access_token> "Hello"
gyll run --url ip:port "Run task"
gyll hook --url ip:port "Send and exit"

Local quick forms:

gyll
gyll "Hello"
gyll run "Run task"
gyll hook "Send and exit"

Modes:

• gyll: interactive TUI.
• gyll "message": create session, send immediately, then enter TUI.
• gyll run "message": create session, stream output in terminal, no TUI entry.
• gyll hook "message": create session, send once, then exit.

Use --token <access_token> when connecting to a non-local websocket gateway.

You can also resume a target session:

gyll --sessionid "your-session-id"

Hook mode is useful for callback-style self-wakeup in long workflows.

Typical gyll patterns

• Interactive pairing: gyll
• Single prompt then continue in TUI: gyll "message"
• Automation-like terminal streaming: gyll run "message"
• Callback signal / wake-up message: gyll hook "message"

---

Architecture Notes

GyShell follows strict layering:

• packages/*: implementation logic.
• apps/*: composition/bootstrap/build wrappers.
• Frontend logic does not belong in packages/backend.

Core runtime chain (simplified):

1. startElectronMain (desktop composition root)
2. GatewayService (session runtime + transport-agnostic orchestration)
3. WebSocketGatewayControlService (policy-based ws gateway control)
4. WebSocketGatewayAdapter / ElectronWindowTransport (transport implementations)
5. Client controllers in TUI and mobile-web

See:

• docs/monorepo-architecture.md
• docs/build-commands.md

Privacy and Update Policy

• Version checks query only this repository's GitHub version.json.
• No third-party auto-update endpoint is used.
• Version check is the only automatic background network request.

Read More

• Release notes: changelogs/v1.4.3.md
• Build matrix and packaging: docs/build-commands.md
• Monorepo boundaries and runtime flow: docs/monorepo-architecture.md

---

Build and Packaging

• npm run build
• npm run build:backend
• npm run build:tui
• npm run build:mobile-web
• npm run dist
• npm run dist:mac
• npm run dist:win
• npm run dist:linux
• npm run dist:linux-arm64
• ./build.sh --help

For the full command matrix and packaging notes, see docs/build-commands.md.

---

License

This project is licensed under CC BY-NC 4.0.

Special acknowledgment: inspirations and references from Tabby (MIT).

---

GyShell - The shell that thinks with you.