4574f1e2b2 fix: stabilize scoped AI draft/session transitions (#724)
* fix: correct terminal AI history resume behavior

The previous implementation plan mistakenly treated reopening an old terminal AI session in a fresh or reconnected SSH tab as a scope-retargeting feature.

The intended rule is draft-first:
- a fresh or reconnected terminal opens on a blank draft
- older chats remain available in history for manual access
- selecting history does not imply automatic scope transfer into the new tab

This change is a rule correction, not a conflict between product rules.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: harden ai draft transitions

* fix ai session continuation from history

* fix: clear stale activeSessionIdMap entry when view resolves to draft

Addresses the Codex P2 review on aiPanelViewState.ts:38. When a terminal
scope mounts with a persisted activeSessionIdMap entry but no explicit
panelView and no draft, resolveDisplayedPanelView now returns the
default draft view (terminal fresh-start behavior). The sync effect
that writes into activeSessionIdMap is guarded by `if (!activeSession)
return`, so the old entry stays put. That stale entry then leaks into
activeTerminalTargetIds in every other scope, and
getSessionScopeMatchRank uses it to suppress host-matched history that
is actually resumable — so valid sessions vanish from the history
drawer until another action rewrites the map.

Add a dedicated effect that clears the scope's activeSessionIdMap
entry whenever the resolved panel view is draft but a persisted
session id is still present. This keeps the map an accurate record of
"which session each scope is currently showing" instead of a lagging
snapshot.

Also extend sessionScopeMatch.test.ts to cover the rank=2 exact-match
branch and the scope-type mismatch short-circuit, which were missing
from the original suite.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: track cross-terminal session ownership by session id, not targetId

Addresses the Codex follow-up review on commit 345244b2. When a user
resumes a session from history into a different terminal, the session's
`scope.targetId` still points at the original terminal. The previous
ownership tracking — which checked whether `session.scope.targetId`
appeared in `activeTerminalTargetIds` (derived from the keys of
`activeSessionIdMap`) — therefore:

- could not prevent the same session from being resumed in multiple
  terminals simultaneously, because the resumed session's targetId
  never matches the current scope's targetId; and
- let `pruneInactiveScopedSessions` treat a session as orphaned and
  clear its `externalSessionId` the moment the original terminal
  closed, even though another terminal was actively using it.

Switch ownership to be keyed on session id:

- `getSessionScopeMatchRank` now takes `activeTerminalSessionIds`
  (a Set of session ids currently displayed by other terminal scopes)
  and returns rank 0 when `session.id` is in that set.
- `AIChatSidePanel` derives `activeTerminalSessionIds` from the
  *values* of `activeSessionIdMap`, excluding the current scope's key.
- `pruneInactiveScopedSessions` gains an `activeSessionIds` parameter;
  sessions whose id is in this set are never reported as orphaned and
  never have their `externalSessionId` cleared, regardless of their
  stored `scope.targetId`.
- `cleanupOrphanedAISessions` computes the in-use set from the
  pre-cleanup `activeSessionIdMap`, filtered to live scopes, and
  passes it through. The map is read once and reused.

Tests cover the new id-based ownership, the rank-2 exact-match path,
the scope-type-mismatch short-circuit, and the
"resumed-elsewhere session must not be cleaned" invariant.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: bincxz <16399091+binaricat@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 17:16:10 +08:00
2025-12-07 03:25:07 +08:00
2026-03-19 22:01:00 +08:00

Netcatty

Netcatty

🔥 AI-Powered SSH Client, SFTP Browser & Terminal Manager 🚀
netcatty.app

A beautiful, feature-rich SSH workspace built with Electron, React, and xterm.js.
🔥 Built-in AI Agent · Split terminals · Vault views · SFTP workflows · Custom themes — all in one.

GitHub Release   Platform   License

Download Latest Release

Support on Ko-fi

English · 简体中文 · 日本語


Netcatty Main Interface


🔥 Catty Agent — Your IT Ops AI Partner

🚀 Boost your IT ops daily work with AI power. Catty Agent is the built-in AI assistant that understands your servers, executes commands, and handles complex multi-host operations — all through natural conversation.

Catty Agent Interface

🔥 What can Catty Agent do?

  • 🚀 Natural language server management — just tell it what you need, no more memorizing commands
  • 🔥 Real-time server diagnostics — check status, inspect logs, monitor resources through conversation
  • 🚀 Multi-host orchestration — coordinate tasks across multiple servers simultaneously
  • 🔥 Intelligent context awareness — understands your server environment and provides tailored responses
  • 🚀 One-click complex operations — set up clusters, deploy services, and more with simple instructions

🎬 AI in Action

🔥 Single Host — Intelligent Server Diagnostics

Ask Catty Agent to check a server's health, and it runs the right commands, analyzes the output, and gives you a clear summary — all in seconds.

https://github.com/user-attachments/assets/eecf08f1-80bd-49db-886d-b36e93388865

🚀 Multi-Host — Docker Swarm Cluster Setup

Watch Catty Agent orchestrate a Docker Swarm cluster across two servers in one conversation. It handles the init, token exchange, and node joining — you just tell it what you want.

https://github.com/user-attachments/assets/282027aa-5c9e-4bb1-b2c3-5eea9df2b203


Contents


What is Netcatty

Netcatty is a modern SSH client and terminal manager for macOS, Windows, and Linux, designed for developers, sysadmins, and DevOps engineers who need to manage multiple remote servers efficiently.

  • Netcatty is an alternative to PuTTY, Termius, SecureCRT, and macOS Terminal.app for SSH connections
  • Netcatty is a powerful SFTP client with dual-pane file browser
  • Netcatty is a terminal workspace with split panes, tabs, and session management
  • Netcatty supports SSH, local terminal, Telnet, Mosh, and Serial connections (when available)
  • Netcatty is not a shell replacement — it connects to shells via SSH/Telnet/Mosh or local/serial sessions

Why Netcatty

If you regularly work with a fleet of servers, Netcatty is built for speed and flow:

  • Workspace-first — split panes + tabs + session restore for “always-on” workflows
  • Vault organization — grid/list/tree views with fast search and drag-friendly workflows
  • Serious SFTP — built-in editor + drag & drop + smooth file operations

Features

🗂️ Vault

  • Multiple views — grid / list / tree
  • Fast search — locate hosts and groups quickly

🖥️ Terminal Workspaces

  • Split panes — horizontal and vertical splits for multi-tasking
  • Session management — run multiple connections side-by-side

📁 SFTP + Built-in Editor

  • File workflows — drag & drop uploads/downloads
  • Edit in place — built-in editor for quick changes

🎨 Personalization

  • Custom themes — tune the app appearance to your taste
  • Keyword highlighting — customize highlight rules for terminal output

Demos

Video previews (stored in screenshots/gifs/), rendered inline on GitHub:

Vault views: grid / list / tree

Switch between different Vault views to match your workflow: overview in grid, dense scanning in list, and hierarchical navigation in tree.

https://github.com/user-attachments/assets/e2742987-3131-404d-bd4b-06423e5bfd99

Split terminals + session management

Work in multiple sessions at once with split panes. Keep related tasks side-by-side and reduce context switching.

https://github.com/user-attachments/assets/377d0c46-cc5a-4382-aa31-5acfd412ce62

SFTP: drag & drop + built-in editor

Move files with drag & drop, then edit quickly using the built-in editor without leaving the app.

https://github.com/user-attachments/assets/c6e06af4-b0d5-461c-b0c7-9d6f655af6c7

Drag file upload

Drop files into the app to kick off uploads without hunting through dialogs.

https://github.com/user-attachments/assets/c8e0c4ff-f020-4e18-9b09-681ec97b003f

Custom themes

Make Netcatty yours: customize themes and UI appearance.

https://github.com/user-attachments/assets/77e2a693-4ef2-4823-8ca1-9bcbf14ed98b

Keyword highlighting

Highlight important terminal output so errors, warnings, and key events stand out at a glance.

https://github.com/user-attachments/assets/e6516993-ad66-4594-8c28-57426082339b


Screenshots

Main Window

The main window is designed for long-running SSH workflows: quick access to sessions, navigation, and core tools in one place.

Main Window (Dark)

Main Window (Light)

Vault Views

Organize and navigate your hosts using the view that best fits the moment: grid for overview, list for scanning, tree for structure.

Vault Grid View

Vault List View

Vault Tree View (Dark)

Vault Tree View (Light)

Split Terminals

Split panes help you monitor multiple servers/services at the same time (deploy + logs + metrics) without juggling windows.

Split Windows


Supported Distros

Netcatty automatically detects and displays OS icons for connected hosts:

Ubuntu Debian CentOS Fedora Arch Linux Alpine Amazon Linux Red Hat Rocky Linux openSUSE Oracle Linux Kali Linux AlmaLinux

Getting Started

Download

Download the latest release for your platform from GitHub Releases.

OS Support
macOS Universal (x64 / arm64)
Windows x64 / arm64
Linux x64 / arm64

Or browse all releases at GitHub Releases.

macOS Users: Current releases are expected to be code-signed and notarized. If Gatekeeper still warns, make sure you downloaded the latest official build from GitHub Releases.

Prerequisites

  • Node.js 18+ and npm
  • macOS, Windows 10+, or Linux

Development

# Clone the repository
git clone https://github.com/binaricat/Netcatty.git
cd Netcatty

# Install dependencies
npm install

# Start development mode (Vite + Electron)
npm run dev

Project Structure

├── App.tsx                 # Main React application
├── components/             # React components
│   ├── Terminal.tsx        # Terminal component
│   ├── SftpView.tsx        # SFTP browser
│   ├── VaultView.tsx       # Host management
│   ├── KeyManager.tsx      # SSH key management
│   └── ...
├── application/            # State management & i18n
├── domain/                 # Domain models & logic
├── infrastructure/         # Services & adapters
├── electron/               # Electron main process
│   ├── main.cjs            # Main entry
│   └── bridges/            # IPC bridges
└── public/                 # Static assets & icons

Build & Package

# Build for production
npm run build

# Package for current platform
npm run pack

# Package for specific platforms
npm run pack:mac     # macOS (DMG + ZIP)
npm run pack:win     # Windows (NSIS installer)
npm run pack:linux   # Linux (AppImage + DEB + RPM)

Tech Stack

Category Technology
Framework Electron 40
Frontend React 19, TypeScript
Build Tool Vite 7
Terminal xterm.js 5
Styling Tailwind CSS 4
SSH/SFTP ssh2, ssh2-sftp-client
PTY node-pty
Icons Lucide React

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

See agents.md for architecture overview and coding conventions.


Contributors

Thanks to all the people who contribute!


License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.


Star History

Star History Chart

Made with ❤️ by binaricat

Languages
TypeScript 64.1%
JavaScript 35.4%
CSS 0.2%
Shell 0.1%