{"id":29257438,"url":"https://github.com/yiwenlu66/piloty","last_synced_at":"2025-07-05T05:01:29.181Z","repository":{"id":301770177,"uuid":"1010070146","full_name":"yiwenlu66/PiloTY","owner":"yiwenlu66","description":"PiloTY: AI pilot for PTY operations via MCP - enables AI agents to control interactive terminals like a human","archived":false,"fork":false,"pushed_at":"2025-06-28T17:46:03.000Z","size":45,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-28T18:39:34.469Z","etag":null,"topics":["ai-agent","automation","cli","interactive","mcp","pty","python","shell","ssh","terminal"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yiwenlu66.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-28T09:24:45.000Z","updated_at":"2025-06-28T17:46:06.000Z","dependencies_parsed_at":"2025-06-28T18:50:50.968Z","dependency_job_id":null,"html_url":"https://github.com/yiwenlu66/PiloTY","commit_stats":null,"previous_names":["yiwenlu66/piloty"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yiwenlu66/PiloTY","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiwenlu66%2FPiloTY","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiwenlu66%2FPiloTY/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiwenlu66%2FPiloTY/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiwenlu66%2FPiloTY/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yiwenlu66","download_url":"https://codeload.github.com/yiwenlu66/PiloTY/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiwenlu66%2FPiloTY/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263443098,"owners_count":23467246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","automation","cli","interactive","mcp","pty","python","shell","ssh","terminal"],"created_at":"2025-07-04T04:05:04.773Z","updated_at":"2025-07-05T05:01:29.175Z","avatar_url":"https://github.com/yiwenlu66.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PiloTY\n\n**AI Pilot for PTY Operations** - An MCP server that enables AI agents to control interactive terminals like a human.\n\n\u003e **⚠️ Work in Progress**: This project is under active development and not ready for production use yet.\n\n\u003e **🔴 Security Warning**: PiloTY provides unrestricted terminal access that can \"jailbreak\" permission controls. For example, while Claude Code requires approval for each bash command, PiloTY's `run` tool can execute ANY command without additional checks. Only use with trusted AI systems and understand the security implications.\n\nPiloTY (Pilot + PTY) bridges AI agents and terminal interfaces through the Model Context Protocol, providing stateful terminal sessions with support for interactive applications, SSH connections, and background processes.\n\n📖 **[Read the technical design document](TECHNICAL.md)** for detailed architecture and use cases.\n\n## What You Can Do\n\n**Transform natural language into powerful terminal workflows.** With PiloTY, AI agents can control terminals just like experienced developers - maintaining state, managing SSH sessions, and handling complex multi-step operations through simple conversation.\n\n### Stateful Development Workflows\n\n\u003e \"Change to my project directory, activate the virtual environment, and run the tests\"\n\n\u003e \"Install the dependencies, build the project, and run the linter\"\n\n### Remote Server Management  \n\n\u003e \"SSH into my production server, check the logs in /var/log/, and restart the nginx service\"\n\n\u003e \"Connect to my database server and show me the current connections\"\n\n### Background Process Monitoring\n\n\u003e \"Start a long-running data processing script in the background and check on its progress every few minutes\"\n\n\u003e \"Download a large file using wget in the background and let me know when it's done\"\n\n### Interactive Debugging\n\n\u003e \"Run my Python script with ipdb and set a breakpoint at line 42\"\n\n\u003e \"Start a tmux session on my remote server and attach to an existing session\"\n\n## Installation\n\n### Option 1: Install with uv (Recommended)\n\nThe fastest and most reliable way to install PiloTY:\n\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install PiloTY globally\nuv tool install git+https://github.com/yiwenlu66/PiloTY.git\n\n# Update shell PATH if needed\nuv tool update-shell\n```\n\n### Option 2: Install with pipx\n\nAlternative installation using pipx:\n\n```bash\n# Install pipx if you haven't already\npython -m pip install --user pipx\npipx ensurepath\n\n# Install PiloTY\npipx install git+https://github.com/yiwenlu66/PiloTY.git\n```\n\n### Option 3: Install from source\n\nFor development or testing:\n\n```bash\ngit clone https://github.com/yiwenlu66/PiloTY.git\ncd PiloTY\n\n# Using uv (recommended)\nuv tool install .\n\n# Or using pip in development mode\npip install -e .\n```\n\nAfter installation, verify the `piloty` command is available:\n\n```bash\nwhich piloty  # Should show the installed location\n```\n\n## Setup with AI Agents\n\n### Claude Code\n\nAdd PiloTY to your Claude Code configuration in `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"piloty\": {\n      \"command\": \"piloty\"\n    }\n  }\n}\n```\n\n**Important**: Restart Claude Code completely after adding the configuration.\n\n### Claude Desktop\n\nAdd the following to your Claude Desktop configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"piloty\": {\n      \"command\": \"piloty\"\n    }\n  }\n}\n```\n\n## Features\n\n- **Stateful Terminal Sessions**: Maintains context across commands\n- **Interactive Program Support**: SSH, vim, less, and more coming soon\n- **Background Process Management**: Run and monitor long-running processes\n- **Handler Architecture**: Extensible system for adding new interactive programs\n- **PTY Control**: True terminal emulation for authentic interactions\n\n## Roadmap\n\n### ✅ Currently Supported\n- **Stateful shell sessions** - Commands maintain context and working directory\n- **SSH with public key authentication** - Seamless remote server access\n- **Background process management** - Start, monitor, and control long-running tasks\n- **Interactive program handling** - Basic support for SSH and shell interactions\n\n### 🚧 Coming Soon\n- **Password authentication** - Support for SSH and other tools requiring password input\n- **REPL support** - Interactive data analysis with Python, R, and other interpreters\n- **Advanced interactive tools** - Enhanced vim, tmux, and debugger integration\n- **Multi-session management** - Coordinate multiple terminal sessions simultaneously\n\n## Session Logging\n\nPiloTY automatically logs all terminal sessions to `~/.piloty/` for debugging and inspection:\n\n- **Active sessions**: `~/.piloty/active/` (symlinks to active sessions)\n- **Session history**: `~/.piloty/sessions/` (persistent logs for all sessions)\n- **Command history**: Timestamped commands and outputs\n- **Session state**: Working directory, background jobs, active handlers\n\nUse the [session viewer tool](tools/README.md) to inspect session logs, or browse the files directly with standard UNIX tools like `tail`, `grep`, and `cat`.\n\n## Testing Integration\n\nAfter configuration, test PiloTY in Claude Code by asking it to perform terminal tasks:\n\n\u003e \"Please run 'echo Hello from PiloTY' in a terminal session\"\n\n\u003e \"Change to the /tmp directory and show me the current working directory\"\n\n\u003e \"SSH into my server and check the disk usage with df -h\"\n\n\u003e \"Start a background process to download a file and monitor its progress\"\n\n\u003e \"Check what background jobs are running in my session\"\n\nThe AI will automatically use PiloTY's MCP tools to execute these requests while maintaining session state across commands.\n\n## Developer Resources\n\n- **[Development Guide](DEVELOPMENT.md)**: Architecture details and how to extend PiloTY\n- **[Developer Tools](tools/README.md)**: Interactive PTY playground for testing\n- **[Technical Design](TECHNICAL.md)**: Detailed architecture and philosophy\n\n## Testing and Development\n\n### Manual Testing\n\nFor hands-on testing and development:\n\n```bash\npython tools/pty_playground.py\n```\n\n### Integration Testing\n\nUse PiloTY through AI agents (Claude Code, Claude Desktop, etc.) by asking them to perform terminal tasks in natural language.\n\n### Automated Tests\n\nRun the test suite:\n\n```bash\npython tests/test_background_processes.py\npython tests/test_poll_output.py\npython tests/test_ssh.py\n```\n\n## Acknowledgments\n\nPiloTY is built upon the foundational work of [pty-mcp](https://github.com/qodo-ai/pty-mcp) by [Qodo](https://github.com/qodo-ai). We extend our gratitude to the original authors for creating the initial MCP terminal server implementation that made this project possible.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyiwenlu66%2Fpiloty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyiwenlu66%2Fpiloty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyiwenlu66%2Fpiloty/lists"}