* refactor: unify directory download with upload transfer system Directory downloads previously used a completely separate implementation with custom queue management, progress tracking, and concurrency control (~390 lines in useSftpViewFileOps.ts). This caused the download UI to show only a single aggregate task without child file details, unlike uploads which showed parent + child tasks. Replace the custom download implementation with a new downloadToLocal() method in useSftpTransfers that reuses the existing transferDirectory/ transferFile infrastructure. Downloads now: - Show parent task with child file tasks (same as uploads) - Use the configurable transfer concurrency setting - Support cancellation through the same mechanism - Share progress tracking and conflict detection code Net reduction of ~260 lines. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: remove dead code from directory download refactor Remove listSftp, mkdirLocal, and RemoteFile imports that were only used by the old custom directory download implementation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: handle symlink directories in transfers and remove dead code - Use isNavigableDirectory() instead of type === "directory" in transferDirectory so symlinks pointing to directories are recursed into correctly (fixes both upload and download paths) - Remove unused deleteLocalFile prop from useSftpViewFileOps Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: use connection ID for download tasks and cancel child streams - Use pane connection ID (not SFTP session ID) as sourceConnectionId so download tasks are properly associated with the host and visible in filtered transfer views - Cancel all active child transfer streams at the backend when parent is cancelled, not just the parent ID — stops data transfer immediately Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: add symlink cycle detection and propagate child failures - Add visitedPaths Set to transferDirectory to detect and skip symlink directory cycles that would cause infinite recursion - Check for failed child tasks after transferDirectory completes and mark parent as failed instead of falsely reporting success Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: use depth limit for symlink loops and handle EEXIST on mkdir - Replace visited-paths cycle detection with a depth limit (64), which reliably catches symlink loops that generate new path strings each hop (e.g. /dir/link/link/link...) - Handle EEXIST errors in mkdirLocal gracefully so re-downloading to an existing directory doesn't abort the entire transfer Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: throw on depth limit exceeded and mark downloads non-retryable - Depth limit now throws instead of silently returning, so exceeding it surfaces as a failed transfer rather than an incomplete success - Set retryable: false on downloadToLocal tasks since retryTransfer cannot resolve the synthetic "local" connection ID Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: track symlink depth only and verify EEXIST target is directory - Change depth guard to only count symlink directory hops, not total directory depth, so legitimate deep trees are not rejected - After catching EEXIST on mkdirLocal, stat the path to verify it is actually a directory — throw if a regular file exists at that path Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: remove dead props from callbacks and surface download failures - Remove mkdirLocal and deleteLocalFile from useSftpViewPaneCallbacks interface and passthrough (fixes TS2353 build error) - Show error toast when downloadToLocal returns "failed" status, not just when it throws Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: track child transfer IDs outside React state for reliable cancel Child transfer IDs were only discoverable via transfersRef.current, which lags behind setTransfers due to React batching. This caused two race conditions: 1. Cancellation: child streams started between setTransfers and render were not cancelled at the backend, continuing to write data. 2. Failure detection: hasFailedChildren checked transfersRef which might not reflect recently-failed children, marking partial downloads as successful. Fix: track active child IDs in activeChildIdsRef (a mutable Map outside React state) for immediate visibility during cancellation. Check child failure status inside setTransfers functional updater where the latest state is guaranteed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: preserve actual progress on partial failure and count symlink dirs - Don't force transferredBytes to totalBytes when some children failed, so the progress bar accurately reflects the partial completion - Use isNavigableDirectory in countDirectoryFiles and estimateDirectoryBytes so symlink directories are included in size/count estimates Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: symlink count, progress on fast downloads, and child cancellation 1. countDirectoryFiles: use isNavigableDirectory so symlink dirs are recursed into, keeping totals consistent with transferDirectory 2. Final status: compute actual completedCount from children instead of relying on totalBytes which may be 0 if the background scan hasn't finished yet 3. Catch block: detect cancellation from error message (not just cancelledTasksRef) so child-initiated cancels don't show as errors Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: add symlink depth guard to countDirectoryFiles and estimateDirectoryBytes Both helper functions now track symlink depth and stop recursing when MAX_SYMLINK_DEPTH is exceeded, consistent with transferDirectory. Prevents infinite recursion on symlink directory cycles during the background file count/size scan. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: reliable final status and non-retryable child tasks 1. transferDirectory now returns the count of failed child transfers, tracked outside React state. downloadToLocal uses this count directly instead of reading from setTransfers updater (which may be deferred by React batching), ensuring the correct status is returned to the caller for toast messages. 2. Child tasks explicitly inherit retryable from the parent task. For downloadToLocal (retryable: false), this prevents showing retry actions on failed children whose "local" targetConnectionId cannot be resolved by retryTransfer. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: add ancestor path cycle detection for symlink directories The depth-only guard allowed up to 32 pointless traversals before stopping a symlink cycle (e.g. dir/link -> .). Add an ancestorPaths Set that tracks the current recursion stack — if a directory's source path is already in the set, it's an immediate cycle and is skipped with zero wasted traversals. The depth limit remains as a hard backstop. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: don't recurse into symlink directories during transfers Revert to only recursing into real directories (type === "directory") in transferDirectory, countDirectoryFiles, and estimateDirectoryBytes. Symlink directories are now transferred as regular entries instead of being followed, eliminating all symlink cycle risks without needing complex cycle detection that can't reliably work with unresolved remote paths. Also clean up activeChildIdsRef in processTransfer (both success and error paths) to prevent memory leaks from pane-to-pane directory transfers. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: filter "." entries and recurse into symlink dirs with depth guard 1. Filter both "." and ".." in all recursive functions — some SFTP servers include "." in readdir, causing infinite self-recursion. 2. Restore symlink directory recursion in transferDirectory with a symlinkDepth counter (max 32). Symlink dirs that exceed the limit are excluded from the dirs list (treated as files). This is needed because startStreamTransfer cannot transfer a directory as a file, so skipping symlink dirs caused child transfer failures. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: add symlink depth guard to count/estimate helpers countDirectoryFiles and estimateDirectoryBytes now track symlinkDepth consistently with transferDirectory, preventing infinite recursion on symlink cycles in the background file count/size estimation. Also fixes: - Remove fragile string-based cancellation detection in downloadToLocal - Clean up cancelledTasksRef in downloadToLocal catch block - Move MAX_SYMLINK_DEPTH before its first use Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: use path reconstruction instead of string replace for duplicate conflicts resolveConflict's "duplicate" action used String.replace to swap the filename in the target path, but this replaces the first occurrence which can corrupt the path if the filename also appears in a parent directory name. Use joinPath(getParentPath(...), newName) instead. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: skip over-depth symlink directories instead of treating as files When symlinkDepth exceeds MAX_SYMLINK_DEPTH, symlink directories were falling through to regularFiles and being passed to transferFile, which cannot transfer directories and would produce confusing errors. Now they are skipped entirely with a warning log. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: count skipped symlinks as errors and process subdirs concurrently 1. Symlink directories skipped at MAX_SYMLINK_DEPTH now increment totalErrors so the parent task is marked failed instead of silently reporting success with incomplete content. 2. Sibling subdirectories are now processed with Promise.all instead of sequential await, restoring cross-directory concurrency that the old download implementation had. Files within each directory still use the configurable worker pool concurrency. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: sequential subdirs to prevent SFTP overload and check dir errors in processTransfer 1. Revert subdirectory processing to sequential (for...of await) to prevent unbounded concurrent SFTP requests from nested Promise.all + worker pools across the directory tree. File-level concurrency within each directory is still governed by getTransferConcurrency(). 2. processTransfer now captures transferDirectory's error count return value and marks the parent task as "failed" when child transfers fail, instead of unconditionally marking "completed". Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * refactor: remove redundant completed state update for directory transfers Directory success path no longer writes "completed" in both the directory-specific block and the generic block. The directory-specific block now only handles the failure case with early return; success falls through to the generic completed block. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: route partial directory failures through shared completion path The early return for directory transfer failures skipped cache invalidation, target pane refresh, and onTransferComplete callbacks (needed by cut/paste to clear clipboard). Now partial failures flow through the same cleanup path as successes — cache is cleared, target is refreshed, and completionHandler is called with the correct "failed" status. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: restrict symlink directory recursion to downloadToLocal only Add followSymlinks parameter (default false) to transferDirectory, countDirectoryFiles, and estimateDirectoryBytes. Only downloadToLocal passes true — uploads and pane-to-pane copies retain their original behavior of treating symlink directories as regular entries. This prevents existing upload/copy flows from expanding symlinked directory trees (which could duplicate content or trigger cycles), while still allowing local downloads to recursively copy through symlink directories with depth protection. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: disable retry for partial dir failures and fix symlink file count 1. Mark partially failed directory transfers as retryable: false to prevent retry from replaying the entire directory without conflict checks, which would silently overwrite already-copied files. 2. In countDirectoryFiles and estimateDirectoryBytes, skip over-depth symlink directories entirely instead of counting them as files. This makes the totals consistent with transferDirectory which also skips these entries, preventing impossible progress like "10/11". Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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.
🔥 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.
🔥 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
- 🔥 Catty Agent — AI Partner
- What is Netcatty
- Why Netcatty
- Features
- Demos
- Screenshots
- Supported Distros
- Getting Started
- Build & Package
- Tech Stack
- Contributing
- Contributors
- Star History
- License
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.
Vault Views
Organize and navigate your hosts using the view that best fits the moment: grid for overview, list for scanning, tree for structure.
Split Terminals
Split panes help you monitor multiple servers/services at the same time (deploy + logs + metrics) without juggling windows.
Supported Distros
Netcatty automatically detects and displays OS icons for connected hosts:
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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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
Made with ❤️ by binaricat







