Skip to content

Repl ssh terminal support #133

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 15 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 14 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,11 @@ This document provides answers to the most commonly asked questions about Claude

- [Features & Capabilities](#features--capabilities)
- [What can I do with Claude Desktop Commander?](#what-can-i-do-with-claude-desktop-commander)
- [Can Claude analyze my CSV/Excel files directly?](#can-claude-analyze-my-csvexcel-files-directly)
- [Can Claude connect to remote servers?](#can-claude-connect-to-remote-servers)
- [Does Claude save temporary files when running code?](#does-claude-save-temporary-files-when-running-code)
- [What programming languages can Claude run interactively?](#what-programming-languages-can-claude-run-interactively)
- [Can Claude handle multi-step operations?](#can-claude-handle-multi-step-operations)
- [How does it handle file editing?](#how-does-it-handle-file-editing)
- [Can it help me understand complex codebases?](#can-it-help-me-understand-complex-codebases)
- [How does it handle long-running commands?](#how-does-it-handle-long-running-commands)
Expand Down Expand Up @@ -189,6 +194,26 @@ The tool enables a wide range of tasks:
- Analyze and summarize codebases
- Produce reports on code quality or structure

### Can Claude analyze my CSV/Excel files directly?

Yes! Just ask Claude to analyze any data file. It will write and execute Python/Node code in memory to process your data and show results instantly.

### Can Claude connect to remote servers?

Yes! Claude can start SSH connections, databases, or other programs and continue interacting with them throughout your conversation.

### Does Claude save temporary files when running code?

If you ask. Code can run in memory. When you ask for data analysis, Claude executes Python/R code directly without creating files on your disk. Or creating if you ask.

### What programming languages can Claude run interactively?

Python, Node.js, R, Julia, and shell commands. Any interactive terminal REPL environments. Perfect for data analysis, web development, statistics, and system administration.

### Can Claude handle multi-step operations?

Yes! Claude can start a program (like SSH or database connection) and send multiple commands to it, maintaining context throughout the session.

### How does it handle file editing and URL content?

Claude Desktop Commander provides two main approaches to file editing and supports URL content:
Expand Down Expand Up @@ -464,4 +489,4 @@ Jupyter notebooks and Claude Desktop Commander serve different purposes:
- Visual output for data visualization
- More structured for educational purposes

For data science or analysis projects, you might use both: Claude Desktop Commander for system tasks and code management, and Jupyter for interactive exploration and visualization.
For data science or analysis projects, you might use both: Claude Desktop Commander for system tasks and code management, and Jupyter for interactive exploration and visualization.
28 changes: 25 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ Execute long-running terminal commands on your computer and manage processes thr

## Features

- **Enhanced terminal commands with interactive process control**
- **Execute code in memory (Python, Node.js, R) without saving files**
- **Instant data analysis - just ask to analyze CSV/JSON files**
- **Interact with running processes (SSH, databases, development servers)**
- Execute terminal commands with output streaming
- Command timeout and background execution support
- Process management (list and kill processes)
Expand Down Expand Up @@ -181,8 +185,9 @@ The server provides a comprehensive set of tools organized into several categori
|----------|------|-------------|
| **Configuration** | `get_config` | Get the complete server configuration as JSON (includes blockedCommands, defaultShell, allowedDirectories, fileReadLineLimit, fileWriteLineLimit, telemetryEnabled) |
| | `set_config_value` | Set a specific configuration value by key. Available settings: <br>• `blockedCommands`: Array of shell commands that cannot be executed<br>• `defaultShell`: Shell to use for commands (e.g., bash, zsh, powershell)<br>• `allowedDirectories`: Array of filesystem paths the server can access for file operations (⚠️ terminal commands can still access files outside these directories)<br>• `fileReadLineLimit`: Maximum lines to read at once (default: 1000)<br>• `fileWriteLineLimit`: Maximum lines to write at once (default: 50)<br>• `telemetryEnabled`: Enable/disable telemetry (boolean) |
| **Terminal** | `execute_command` | Execute a terminal command with configurable timeout and shell selection |
| | `read_output` | Read new output from a running terminal session |
| **Terminal** | `start_process` | Start programs with smart detection of when they're ready for input |
| | `interact_with_process` | Send commands to running programs and get responses |
| | `read_process_output` | Read output from running processes |
| | `force_terminate` | Force terminate a running terminal session |
| | `list_sessions` | List all active terminal sessions |
| | `list_processes` | List all running processes with detailed information |
Expand All @@ -198,6 +203,23 @@ The server provides a comprehensive set of tools organized into several categori
| | `get_file_info` | Retrieve detailed metadata about a file or directory |
| **Text Editing** | `edit_block` | Apply targeted text replacements with enhanced prompting for smaller edits (includes character-level diff feedback) |

### Quick Examples

**Data Analysis:**
```
"Analyze sales.csv and show top customers" → Claude runs Python code in memory
```

**Remote Access:**
```
"SSH to my server and check disk space" → Claude maintains SSH session
```

**Development:**
```
"Start Node.js and test this API" → Claude runs interactive Node session
```

### Tool Usage Examples

Search/Replace Block Format:
Expand Down Expand Up @@ -614,4 +636,4 @@ For complete details about data collection, please see our [Privacy Policy](PRIV

## License

MIT
MIT
26 changes: 23 additions & 3 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -1015,8 +1015,8 @@ <h3>Smart file system integration</h3>
<div class="benefit-icon">
<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="2" width="20" height="8" rx="2" ry="2"></rect><rect x="2" y="14" width="20" height="8" rx="2" ry="2"></rect><line x1="6" y1="6" x2="6.01" y2="6"></line><line x1="6" y1="18" x2="6.01" y2="18"></line></svg>
</div>
<h3>Full terminal access</h3>
<p>Execute any command line operation directly through Claude's interface for seamless development, testing, and deployment workflows.</p>
<h3>Interactive code execution</h3>
<p>Execute Python, Node.js, R code in memory for instant data analysis. Connect to SSH, databases, and maintain persistent sessions for complex workflows.</p>
</div>

<div class="benefit-card">
Expand Down Expand Up @@ -1085,6 +1085,25 @@ <h3>AI DevOps</h3>
<!-- <a href="segments/user-segments.html#devops-professionals" class="segment-link">Learn More</a> -->
</div>

<!-- Data Analyst Segment -->
<div class="segment-card" id="cases-data">
<div class="segment-icon">
<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 3v18h18"></path><path d="M18.7 8l-5.1 5.2-2.8-2.7L7 14.3"></path></svg>
</div>
<h3>AI Data Analyst</h3>
<p>Analyze CSV files, databases, and datasets instantly with Python and R.</p>
<div class="segment-jobs">
<ul>
<li>Instant CSV/Excel analysis</li>
<li>Database queries with persistent connections</li>
<li>Statistical analysis with R</li>
<li>Data visualization</li>
<li>Report generation</li>
</ul>
</div>
<!-- <a href="segments/user-segments.html#data-professionals" class="segment-link">Learn More</a> -->
</div>

<!-- Tech Writer Segment -->
<div class="segment-card" id="cases-writer">
<div class="segment-icon">
Expand Down Expand Up @@ -1990,6 +2009,7 @@ <h3>Use Cases</h3>
<ul>
<li><a href="#cases-software">AI Software Engineer</a></li>
<li><a href="#cases-devops">AI DevOps</a></li>
<li><a href="#cases-data">AI Data Analyst</a></li>
<li><a href="#cases-writer">AI Technical Writer</a></li>
<li><a href="#cases-uxui">AI UX/UI Designer</a></li>
</ul>
Expand Down Expand Up @@ -2143,4 +2163,4 @@ <h3>Resources</h3>
});
</script>
</body>
</html>
</html>
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
"testemonials"
],
"scripts": {
"open-chat": "open -n /Applications/Claude.app",
"sync-version": "node scripts/sync-version.js",
"bump": "node scripts/sync-version.js --bump",
"bump:minor": "node scripts/sync-version.js --bump --minor",
Expand Down
6 changes: 2 additions & 4 deletions src/handlers/filesystem-handlers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -167,11 +167,9 @@ export async function handleWriteFile(args: unknown): Promise<ServerResult> {
const lineCount = lines.length;
let errorMessage = "";
if (lineCount > MAX_LINES) {
errorMessage = `File was written with warning: Line count limit exceeded: ${lineCount} lines (maximum: ${MAX_LINES}).
errorMessage = `File written successfully! (${lineCount} lines)

SOLUTION: Split your content into smaller chunks:
1. First chunk: write_file(path, firstChunk, {mode: 'rewrite'})
2. Additional chunks: write_file(path, nextChunk, {mode: 'append'})`;
💡 Performance tip: For optimal speed, consider chunking files into ≤30 line pieces in future operations.`;
}

// Pass the mode parameter to writeFile
Expand Down
37 changes: 23 additions & 14 deletions src/handlers/terminal-handlers.ts
Original file line number Diff line number Diff line change
@@ -1,33 +1,42 @@
import {
executeCommand,
readOutput,
startProcess,
readProcessOutput,
interactWithProcess,
forceTerminate,
listSessions
} from '../tools/execute.js';
} from '../tools/improved-process-tools.js';

import {
ExecuteCommandArgsSchema,
ReadOutputArgsSchema,
StartProcessArgsSchema,
ReadProcessOutputArgsSchema,
InteractWithProcessArgsSchema,
ForceTerminateArgsSchema,
ListSessionsArgsSchema
} from '../tools/schemas.js';

import { ServerResult } from '../types.js';

/**
* Handle execute_command command
* Handle start_process command (improved execute_command)
*/
export async function handleExecuteCommand(args: unknown): Promise<ServerResult> {
const parsed = ExecuteCommandArgsSchema.parse(args);
return executeCommand(parsed);
export async function handleStartProcess(args: unknown): Promise<ServerResult> {
const parsed = StartProcessArgsSchema.parse(args);
return startProcess(parsed);
}

/**
* Handle read_output command
* Handle read_process_output command (improved read_output)
*/
export async function handleReadOutput(args: unknown): Promise<ServerResult> {
const parsed = ReadOutputArgsSchema.parse(args);
return readOutput(parsed);
export async function handleReadProcessOutput(args: unknown): Promise<ServerResult> {
const parsed = ReadProcessOutputArgsSchema.parse(args);
return readProcessOutput(parsed);
}
Comment on lines +22 to +33
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix inconsistent error handling between handlers and underlying functions.

The handlers use .parse() which throws on validation errors, but the underlying functions (startProcess, readProcessOutput) use .safeParse() and handle validation errors gracefully. This creates redundant validation and potential unhandled exceptions.

Either use .safeParse() in the handlers or remove the validation from the underlying functions. Here's the recommended fix to maintain consistency:

-export async function handleStartProcess(args: unknown): Promise<ServerResult> {
-    const parsed = StartProcessArgsSchema.parse(args);
-    return startProcess(parsed);
-}
+export async function handleStartProcess(args: unknown): Promise<ServerResult> {
+    return startProcess(args);
+}

-export async function handleReadProcessOutput(args: unknown): Promise<ServerResult> {
-    const parsed = ReadProcessOutputArgsSchema.parse(args);
-    return readProcessOutput(parsed);
-}
+export async function handleReadProcessOutput(args: unknown): Promise<ServerResult> {
+    return readProcessOutput(args);
+}
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
export async function handleStartProcess(args: unknown): Promise<ServerResult> {
const parsed = StartProcessArgsSchema.parse(args);
return startProcess(parsed);
}
/**
* Handle read_output command
* Handle read_process_output command (improved read_output)
*/
export async function handleReadOutput(args: unknown): Promise<ServerResult> {
const parsed = ReadOutputArgsSchema.parse(args);
return readOutput(parsed);
export async function handleReadProcessOutput(args: unknown): Promise<ServerResult> {
const parsed = ReadProcessOutputArgsSchema.parse(args);
return readProcessOutput(parsed);
}
export async function handleStartProcess(args: unknown): Promise<ServerResult> {
return startProcess(args);
}
/**
* Handle read_process_output command (improved read_output)
*/
export async function handleReadProcessOutput(args: unknown): Promise<ServerResult> {
return readProcessOutput(args);
}
🤖 Prompt for AI Agents
In src/handlers/terminal-handlers.ts around lines 22 to 33, the handlers use
.parse() which throws on validation errors, while the underlying functions use
.safeParse() and handle errors gracefully, causing redundant validation and
possible unhandled exceptions. To fix this, replace .parse() with .safeParse()
in the handlers, check the validation result, and handle errors consistently
before calling the underlying functions, ensuring validation is done only once
and errors are managed properly.


/**
* Handle interact_with_process command (improved send_input)
*/
export async function handleInteractWithProcess(args: unknown): Promise<ServerResult> {
return interactWithProcess(args);
}

/**
Expand All @@ -43,4 +52,4 @@ export async function handleForceTerminate(args: unknown): Promise<ServerResult>
*/
export async function handleListSessions(): Promise<ServerResult> {
return listSessions();
}
}
Loading