VibeShell
-
Your terminal. Your agent. The same workspace.
-
A local-first SSH/SFTP workspace for people and coding agents — with visible operations, shared sessions, integrated files, and discoverable plugins.
+
Keep your servers, files, and AI work in the same place.
+
An SSH terminal you can work in yourself, share with an agent, and make your own.
[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
@@ -10,67 +10,94 @@
[](https://github.com/veithly/vibeshell/releases)
[](LICENSE)
- [Download](https://github.com/veithly/vibeshell/releases) · [What's new in 1.1](CHANGELOG.md) · [Agent guide](skills/vibeshell/SKILL.md) · [Contribute to dev](CONTRIBUTING.md)
+ [Download](https://github.com/veithly/vibeshell/releases) · [Agent / CLI guide](skills/vibeshell/SKILL.md) · [Changelog](CHANGELOG.md) · [Contribute](CONTRIBUTING.md)
-
+
-## Why a workspace, not another SSH command?
+*Real VibeShell components, synthetic Northstar demo data. The gallery uses an isolated browser fixture: no live servers, credentials, model calls, or service restarts. Agent transcripts and command results are examples, not recordings of an actual agent run. [Reproduce the screenshots](scripts/readme-demo/README.md).*
-SSH already provides secure transport, authentication, forwarding, and remote command execution. VibeShell does not replace that protocol or claim a faster network. It brings the work around SSH into one place: **the session you are using, the files you are editing, and the actions your agent is taking**.
+## Less passing context between tools
-| In a command-line-only workflow | In VibeShell |
-| --- | --- |
-| A person and an agent may work through unrelated terminals. | Desktop, native CLI and MCP share saved targets and discoverable sessions. |
-| You need to ask what the agent just ran. | Commands and operation states appear in an activity strip and durable history. |
-| A new agent connection is invisible to the desktop. | New sessions become separate tabs without stealing your active tab. |
-| Files, tunnels and commands require switching tools. | Local/remote file tabs, SFTP, forwarding and plugin views live alongside terminals. |
-| Each automation needs handwritten command knowledge. | Plugins expose action schemas and current usage references to agents. |
-| A sync tool can mistake equal file sizes for equal content. | Directory sync compares content and protects excluded paths during deletion. |
+A routine server task rarely stays in one terminal. You check a log, find a configuration file, open an editor, ask an agent for help, then work out which machine and session each tool is using.
+
+VibeShell keeps that work together. SSH and local terminals, coding agents, remote files, Git changes, and operations dashboards share a tabbed workspace. Use it as a normal terminal; bring AI into the parts where it helps. You do not need a model account for ordinary terminal and file work.
+
+The difference is the workflow, not a new SSH protocol. OpenSSH, tmux, editors and scripts can cover many of the same jobs. VibeShell reduces the setup, copying and window switching needed to make them work together.
+
+## Let an agent help without losing the thread
+
+### See what it ran, and where
+
+Desktop, native CLI and MCP can use the same saved servers and discover existing sessions. When an agent runs a command, the activity strip and history show the command, session, time and operation state. Repeated attempts remain separate records; multiline commands are not reduced to a one-line label.
+
+There are two ways to collaborate. Send input into a shared interactive shell when you want to work in that prompt together. Use independent execution when the agent should inspect something without typing over your work. Both have visible activity; “input sent” is kept distinct from “command completed.”
+
+An agent-created session appears as another tab without switching away from the tab you selected. Two connections to the same server remain two sessions, not one ambiguous server-name tab. History can be paged through and recovered after reopening the UI.
+
+### Approve the actual operation, not a vague request
+
+The approval dialog puts the proposed command and the reasons for review in front of you. You can allow that operation or reject it instead of discovering a service restart in the transcript afterward. CLI and MCP plugin actions also retain their permission and confirmation checks.
+
+
-You can assemble similar workflows from OpenSSH, tmux, editors and scripts. VibeShell makes their coordination a product feature, rather than a setup task.
+*Demo request only. The service restart in this image was never executed. Command classification and approval are useful controls, not a sandbox or a guarantee that every risky command will be recognized.*
-## The 1.1 experience
+## Bring your coding agent, not another chat window
-### Work with an agent without losing visibility
+Launch separately installed tools such as **Claude Code, Codex, OpenCode and Pi** in real local terminals. Pick a project directory, add an initial brief, and choose the start modes the selected tool supports: a new session, continuing the latest one, or choosing a previous session. Access modes are explicit rather than hidden in a command copied from a tutorial.
-Agent and CLI operations show the command, target session, time and lifecycle state. Repeated commands remain separate records; long, multiline commands are retained, with pagination and recovery after reopening the UI. The activity history is encrypted locally and is not part of cloud sync.
+
-Use the shared interactive terminal when you need to collaborate in the same shell. Use independent exec for inspection without typing into the person's prompt; it remains visible in activity history. A successful input operation means **bytes were delivered**, not that the remote command completed successfully.
+The agent's terminal stays beside the rest of your work. Open **Workspace changes** to see the branch, changed files and line-by-line diff. You can read the proposed edit instead of relying on the agent's summary of it. Local development and remote operations can live in neighboring tabs, but they are not silently treated as the same execution environment.
-When an agent opens another session, its tab appears without changing the person's selection. Session identity, not server name, distinguishes parallel work. Closing an owner process ends its connections: daemon-owned sessions can outlive the GUI, while GUI-owned sessions cannot survive quitting that GUI process.
+
-### Less window management, more context
+*Agent tools need their own installation, sign-in and subscriptions. VibeShell provides the workspace and launch integration; it does not bundle a model subscription or claim the sample transcript is live output.*
-A searchable connection launcher brings SSH servers, local shells and coding-agent entry points together. Switch between list and card views; use keyboard focus management, light/dark themes and reduced-motion support. Card animations use browser-native APIs rather than a separate animation runtime.
+## A terminal that helps with the small things
-Split terminals and file views, detach work into another window, and keep unsaved file edits when reorganizing the workspace. Command history, snippets, contextual actions and explicit error messages reduce repetitive copying and ambiguous “success” notifications.
+You should not need AI just to remember a flag. Built-in completion suggests commands, subcommands and options, with descriptions and command-history matches. Inline suggestions and a keyboard-driven completion list keep the answer near the cursor. Frequently used commands can become snippets, while **Quick Cmd** runs a short inspection and shows its output without taking over your interactive shell.
-
+For an extra nudge, enable **AI command prediction** with your own OpenAI-compatible or Claude endpoint and model. It proposes a suffix to what you are typing; it does not run the suggestion for you. This is separate from launching a coding agent.
-### Files are part of the session
+**Prediction is off by default.** When enabled, the current input, recent command history and local completion candidates are sent to the provider you configure. Leave it disabled for work that must not leave the machine; ordinary local completion remains available.
-Browse SFTP in columns or icon views, select multiple files, copy paths, and follow transfer progress. Open local and remote files in workspace tabs; supported viewers include text/code, images, PDF, media and archives.
+Terminal rendering uses xterm.js, a WebGL renderer where available, and batched input/output paths to reduce UI overhead. These are responsiveness choices, not a claim that VibeShell makes the SSH network faster.
-The transport is designed around integrity: transfers use bounded chunks; a download waits for local writes before reporting completion; sync detects same-size edits; excluded paths and nested `.gitignore` rules are protected when deleting extras. Local directory transfers reject overlapping source and destination roots. Content comparison can add remote reads — this is an integrity choice, not a bandwidth-saving claim.
+## Find a connection without remembering an address
-
+The connection launcher brings **SSH, local shells and coding agents** into one place. Search your saved servers, switch between compact lists and cards, and organize targets with groups and tags. Existing-session indicators and a separate new-session action help distinguish “return to my work” from “open another connection.”
-### Edit saved credentials safely
+
-Change a saved password, replace a private key, or update/clear a key passphrase without recreating the server. Untouched fields preserve their previous values; existing secrets are not fetched into the edit form. Metadata, renames and credential changes commit together or roll back together.
+Bring existing profiles from OpenSSH, PuTTY or Tabby, preview an import before applying it, and configure a jump host for private targets. Stored passwords from those other applications are deliberately not copied; PuTTY `.ppk` keys need conversion to OpenSSH format.
-This edits **VibeShell's saved login information**, not the remote operating-system account's password. Unknown or changed host keys still require the appropriate trust decision; a correct login key does not replace host identity verification.
+Changing a saved password, private key or passphrase does not require deleting the server. Untouched fields keep their values, existing secrets are not loaded into the edit form, and profile/credential changes save together or roll back together. This changes **VibeShell's saved login information**, not the remote account's password.
-### Native automation, not a second server inventory
+## Files belong next to the command that uses them
-The Rust `vibeshell` executable can operate without Node.js or a desktop window. It starts a native daemon when required and reuses saved profiles and sessions. When a daemon already owns SSH sessions, the GUI attaches without replacing its live socket; terminal, SFTP, tunnel, recording and database-probe operations route to the owning process.
+Open a remote configuration through SFTP, or use **⌘/Ctrl+O** for local files without opening an SSH connection at all. Documents get their own tabs, so closing the last terminal does not close your local notes.
-Local coding-agent launchers support tools such as Claude Code, Codex, OpenCode and Pi through real PTYs, alongside repository status/diff views. Those agents are separately installed products: VibeShell does not include model subscriptions or their credentials.
+The file workspace offers editable text/code, syntax highlighting, and Markdown source, preview, or both side by side. SFTP includes column/icon browsing, multiple selection, path copying, upload/download progress, and viewers for supported images, PDFs, media and archives. Read a runbook, inspect a log and edit a config without maintaining a separate mental map of windows.
-### Plugins an agent can actually discover
+Move file and terminal panes around, split the workspace, or detach a document into another window. Unsaved text stays with its editing buffer during layout changes. Local text saves detect changes made by another program and refuse to silently overwrite them; truncated reads are not offered as a full-file save.
-Every supported built-in or imported declarative plugin exposes installation state, permissions, action inputs and a current reference. **The main Skill is an index, not an encyclopedia**; detailed instructions live in per-plugin reference documents.
+Folder transfer is also about correctness: bounded chunks, downloads that wait for local writes, content comparison for same-size edits, and protection for excluded paths and nested `.gitignore` rules when deleting extras. Content comparison can add remote reads; it is not a promise of lower bandwidth.
+
+[Local files, Markdown behavior and editing limits](docs/local-files-and-css-themes.md)
+
+## Go from a command to a useful view
+
+Sometimes a terminal is the right view; sometimes a container list or a CPU graph is faster to understand. Open a plugin for the session you are already using instead of configuring the same server in another dashboard.
+
+| What you are working on | Built-in views and tools |
+| --- | --- |
+| A slow or unhealthy host | Server Performance, Process Explorer, System Logs, Network Inspector, Disk Usage |
+| Services and infrastructure | Docker Containers, Kubernetes Pods, Cron Scheduler, Systemd Services |
+| Data and code | Database Inspector, Redis Inspector, Git Workspace |
+
+These **12 built-ins** are more than UI buttons. Agents can discover what is installed, read an action's inputs, fetch its current instructions and use it through the native CLI or MCP:
```bash
vibeshell plugins list --installed --json
@@ -79,75 +106,60 @@ vibeshell plugins docs server-performance
vibeshell plugins run server-performance status --session SESSION_ID --inputs '{}'
```
-Replace `SESSION_ID` with an existing session, and check the plugin is installed and enabled first. `describe` returns machine-readable schemas; `docs` reflects the current validated manifest, including imported plugins.
+Use an existing session ID and check the plugin is installed and enabled first. The main Skill contains an index; detailed usage lives in `references/