{"id":46706018,"url":"https://github.com/pppp606/claude-term","last_synced_at":"2026-03-09T08:11:35.193Z","repository":{"id":309467476,"uuid":"1036387829","full_name":"pppp606/claude-term","owner":"pppp606","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-19T09:45:10.000Z","size":431,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-19T11:40:52.914Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pppp606.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-12T02:20:55.000Z","updated_at":"2025-08-19T09:45:13.000Z","dependencies_parsed_at":"2025-08-12T04:26:59.040Z","dependency_job_id":"98940f61-7ad8-467a-91c9-4c95b0c5d494","html_url":"https://github.com/pppp606/claude-term","commit_stats":null,"previous_names":["pppp606/claude-term"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pppp606/claude-term","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pppp606%2Fclaude-term","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pppp606%2Fclaude-term/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pppp606%2Fclaude-term/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pppp606%2Fclaude-term/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pppp606","download_url":"https://codeload.github.com/pppp606/claude-term/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pppp606%2Fclaude-term/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30287502,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-03-09T08:11:33.924Z","updated_at":"2026-03-09T08:11:35.187Z","avatar_url":"https://github.com/pppp606.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-term\n\n`claude-term` is a lightweight IDE server and MCP server for Claude Code that enables AI-assisted coding entirely from the terminal. It provides full Claude Code functionality with custom tools without requiring heavy GUI IDEs.\n\n\n## What is claude-term?\n\nInstead of using Claude Code through IDEs like VSCode or Cursor, `claude-term` provides both an IDE server and MCP server that Claude Code can connect to. This allows you to:\n\n- **Terminal-native AI coding**: Use Claude Code features in any terminal environment\n- **Custom MCP tools**: Specialized git workflow tools via Model Context Protocol\n- **Zero GUI dependencies**: No need for VSCode, Cursor, or other heavy IDEs\n- **Remote/headless friendly**: Perfect for SSH sessions and server environments  \n- **Your terminal, your rules**: Full control with native CLI tools integration\n\n## Architecture\n\n```\n┌─────────────┐    WebSocket         ┌──────────────┐\n│   Claude    │ ◄─────────────────── │ claude-term  │\n│   Code      │   selection_changed  │ IDE Server   │\n│             │   file sharing       │              │\n│             │                      └──────────────┘\n│             │    stdio MCP               │\n│             │ ◄─────────────────── ┌──────────────┐\n│             │   review_push        │ claude-term  │\n│             │   git_status         │ MCP Server   │\n└─────────────┘                      └──────────────┘\n                                           │\n                                           ▼\n                                    ┌──────────────┐\n                                    │ Your Project │\n                                    │ (fzf, delta, │\n                                    │  bat, rg)    │\n                                    └──────────────┘\n```\n\n**Key Features:**\n- **Interactive Line Selection**: Select specific lines with fzf and send directly to Claude\n- **File Sharing**: Send complete files via `at_mentioned` events  \n- **MCP Tools**: Custom git workflow tools via Model Context Protocol\n- **CLI Tool Integration**: Native fzf, bat, delta, and ripgrep integration\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone and setup\ngit clone https://github.com/pppp606/claude-term.git\ncd claude-term\nnpm install\nnpm run build\n```\n\n### Usage\n\n1. **Start claude-term servers** (both IDE and MCP, in your project directory):\n```bash\ncd /your/project\nnode dist/cli.js start\n```\n\nOutput:\n```\n🚀 Starting claude-term servers...\n📁 Workspace: /your/project\n📦 IDE Name: claude-term-myproject\n\n✅ Both servers started successfully!\n🔌 IDE Server: Port 54321\n🔌 MCP Server: stdio transport\n\n📋 Next steps:\n1. In Claude, run: /ide\n2. Select: claude-term-myproject\n3. Add MCP server: claude mcp add claude-term-myproject-tools node dist/mcp-server.js\n4. Start coding!\n\nWaiting for connections...\n```\n\n2. **Connect from Claude Code**:\n```bash\nclaude\n```\n\nThen in Claude:\n```\n/ide\n```\n\nSelect your `claude-term-myproject` from the list.\n\n3. **Add MCP tools** (one-time setup):\n```bash\nclaude mcp add claude-term-myproject-tools node dist/mcp-server.js\n```\n\nNow you have both IDE features and custom MCP tools available!\n\n4. **Interactive Commands** (once connected):\n\n**IDE Server Commands:**\n```bash\n# 📁 File Operations\n/browse    # Interactive file picker with fzf\n/cat src/app.js    # Interactive line selector - select and send specific lines!\n/send src/app.js    # Send complete files to Claude\n\n# 🔍 Search \u0026 Discovery\n/search \"function.*authenticate\"    # ripgrep-powered code search\n/active    # Show files Claude can access\n\n# 🚀 Git Workflow (IDE server)\n/review-push (/rp)    # Review unpushed commits and approve/reject for push\n\n# ℹ️ Help \u0026 Control\n/help      # Show all available commands\n/quit      # Exit the session\n```\n\n**MCP Tools** (available directly in Claude Code):\n```bash\n# 🚀 Git Workflow (MCP tools)  \nreview_push    # Review and push commits via MCP (displays interactive review with user approval)\ngit_status     # Get current git status and unpushed commits\n```\n\n## Key Features\n\n### Dual Server Architecture\n\n`claude-term` provides both IDE server capabilities and MCP (Model Context Protocol) tools:\n\n- **IDE Server**: File operations, line selection, search, and interactive terminal commands\n- **MCP Server**: Custom tools for git workflows that integrate directly with Claude Code\n- **Single Command Setup**: Both servers start simultaneously with `node dist/cli.js start`\n\n### Interactive Line Selection\n\nThe standout feature of `claude-term` is **interactive line selection** with fzf:\n\n### MCP Tools Integration\n\n`claude-term` provides specialized MCP tools that integrate directly with Claude Code using a **dual-server architecture**:\n\n**Architecture:**\n- **IDE Server**: WebSocket server for `/ide` functionality + internal MCP server (port 12345)\n- **Standalone MCP Server**: stdio transport MCP server that forwards tool calls to IDE server\n- **Tool Forwarding**: MCP tool calls are forwarded via HTTP to execute in the IDE terminal\n\n**Available MCP Tools:**\n- **`review_push`**: Review unpushed commits and push after approval\n- **`git_status`**: Get current git status and unpushed commit count\n\n**Setup:**\n```bash\n# 1. Start both servers\nnode dist/cli.js start\n\n# 2. Add MCP server to Claude Code\nclaude mcp add claude-term-claude-term-tools node dist/mcp-server.js\n\n# 3. Use in Claude Code conversations\n```\n\n**How it works:**\n1. Claude Code spawns standalone MCP server process (stdio transport)\n2. Standalone MCP server forwards tool calls to running IDE server via HTTP\n3. Tools execute in the terminal where `claude-term start` is running\n4. Interactive prompts appear in your original terminal\n5. Results are forwarded back to Claude Code seamlessly\n\n**Example Usage:**\n```\n# In Claude Code, you can use:\nCan you check the current git status and then review and push any commits?\n```\nClaude Code will automatically use the `git_status` and `review_push` tools, but execution happens in your terminal.\n\n### Git Review \u0026 Push Workflow\n\n`claude-term` includes a comprehensive Git workflow (available both as IDE commands and MCP tools):\n\n```bash\n# IDE Server command\n/review-push    # or /rp for short\n\n# MCP tool (used automatically by Claude Code)\nreview_push     # Called directly by Claude\n```\n\n**What happens:**\n1. 📊 **Commit Analysis** - Automatically detects all unpushed commits\n2. 📄 **Less Pager** - Opens scrollable diff view with Delta syntax highlighting  \n3. 📋 **Commit List** - Shows all commits to be pushed with hash and message\n4. 📁 **File-by-File Diffs** - Beautiful, color-coded diffs for each changed file\n5. ✅ **Single Approval** - Simple y/n choice after review (no duplicate prompts)\n6. 🚀 **Safe Push** - Pushes to remote if approved\n7. 🔄 **Smart Reject** - If rejected, undoes all commits while preserving changes\n8. 🧹 **Clean Display** - No temp file paths shown in less status line\n\n**Perfect for:**\n- Reviewing code before pushing to shared branches\n- Ensuring no debug code or secrets are committed\n- Double-checking complex changes\n- Safe collaboration workflows\n- Clean editing sessions without scattered diff outputs\n- AI-assisted code review (via MCP tools)\n\n**Enhanced Workflow:**\n- Claude Code edits files → Simple \"📝 File modified\" notifications\n- Use `/review-push` or let Claude use `review_push` MCP tool → Comprehensive diff review\n- Single y/n approval → Clean push or smart rollback\n\n### Interactive Line Selection (continued)\n\n```bash\n# Open any file with the interactive selector\n/cat src/components/Header.js\n```\n\n**What happens:**\n1. 📄 **File opens in fzf** with numbered lines\n2. 🎯 **Navigate** with ↑↓ arrows or j/k\n3. ⭐ **Select lines** with Tab (multi-select supported)\n4. 📤 **Send to Claude** with Enter - selected lines sent via `selection_changed` event\n\n**Perfect for:**\n- Asking Claude to explain specific code sections\n- Getting suggestions for particular functions\n- Debugging specific line ranges\n- Code reviews on targeted areas\n\n## Features\n\n### Core IDE Server ✅\n- **WebSocket MCP Server**: Full Model Context Protocol compatibility\n- **Auto-naming**: IDE names based on directory (`claude-term-{dirname}`)\n- **Duplicate Detection**: Prevents multiple servers with same name\n- **Authentication**: WebSocket header-based authentication support\n\n### Interactive Line Selection ✅ \n- **fzf Integration**: Beautiful, fast fuzzy-finding interface\n- **Multi-line Selection**: Select multiple lines with Tab\n- **Real-time Sending**: Selected lines sent immediately via `selection_changed`\n- **Context Preservation**: Full file content included for context\n- **Graceful Fallbacks**: Works without fzf (basic prompt fallback)\n\n### File Operations \u0026 Sharing ✅\n- **File Sending**: Send complete files via `at_mentioned` events \n- **Resource Management**: Active file tracking for Claude access\n- **Interactive File Browser**: fzf integration for file selection\n- **Syntax Highlighting**: bat-powered code display\n\n### Search \u0026 Discovery ✅\n- **ripgrep Integration**: Fast, powerful code search\n- **Interactive Results**: Search results with context\n- **Pattern Matching**: Full regex support\n\n### Git Review \u0026 Push Workflow ✅\n- **Unpushed Commit Detection**: Automatically finds commits ahead of origin\n- **Less Pager Integration**: Scrollable diff review with clean display (no temp file paths)\n- **Delta Syntax Highlighting**: Beautiful, color-coded diff display via stdin\n- **Single Approval Flow**: No duplicate confirmation prompts \n- **Smart Reject**: Undo commits while preserving working directory changes\n- **Multi-commit Support**: Handles single or multiple unpushed commits\n- **Readline Stability**: Robust input handling without buffering issues\n\n### Clean Edit Experience ✅\n- **Streamlined File Editing**: Simple file modification notifications\n- **Consolidated Diff Review**: All changes reviewed together via `/review-push`\n- **No Scattered Diffs**: Clean editing experience without interrupting individual file diffs\n\n## Command Line Options\n\n```bash\n# Start both IDE server and MCP server (recommended)\nnode dist/cli.js start\n\n# Custom options for IDE server\nnode dist/cli.js start --name my-ide-server\nnode dist/cli.js start --port 8080  \nnode dist/cli.js start --workspace /path/to/project\n\n# Start only MCP server (stdio transport)\nnode dist/cli.js mcp --name my-mcp-server\n\n# Enable debug logging\nnode dist/cli.js start --debug\n```\n\n**Available Commands:**\n- `start`: Start both IDE server and MCP server (recommended)\n- `mcp`: Start only MCP server with stdio transport\n\n## Development\n\n### Tech Stack\n- **Language**: Node.js with TypeScript\n- **CLI Framework**: commander\n- **Testing**: jest + ts-jest\n- **Code Style**: eslint + prettier\n\n### Development Commands\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Test\nnpm test\n\n# Lint\nnpm run lint\n\n# Type check\nnpm run typecheck\n```\n\n### Testing Your Changes\n\n```bash\n# Build and test\nnpm run build\nnode dist/cli.js start --name test-ide\n\n# Test with debug logging\nCLAUDE_TERM_DEBUG=1 node dist/cli.js start --name debug-test\n\n# In another terminal  \nclaude\n# Then /ide and select test-ide\n\n# Test core features\n# 1. IDE server features (once connected via /ide)\n/send package.json           # File sharing\n/browse                     # File browser\n/cat src/main.js            # Interactive line selection ⭐\n/search \"export.*function\"  # Code search\n/rp                         # Git review \u0026 push workflow ⭐\n\n# 2. MCP tools (available in Claude Code)\n# Ask Claude: \"Can you check git status and review any commits?\"\n# Claude will use git_status and review_push tools automatically\n```\n\n## Comparison with Traditional IDEs\n\n| Feature | Traditional IDE | claude-term |\n|---------|----------------|-------------|\n| **Resource Usage** | High (GB of RAM) | Minimal (MB of RAM) |\n| **Installation** | Complex setup | Simple npm install |\n| **Customization** | IDE-specific | Your terminal, your rules |\n| **Remote Work** | X11/VNC required | SSH-friendly |\n| **Integration** | IDE extensions | Native CLI tools + MCP |\n| **Line Selection** | Mouse/keyboard in GUI | fzf-powered terminal interface |\n| **AI Tools** | IDE-specific extensions | Custom MCP tools + IDE server |\n\n## CLI Tool Dependencies (Recommended)\n\n```bash\n# For the best experience, install these tools:\n\n# Interactive file selection and line picker\nbrew install fzf\n\n# Syntax highlighting  \nbrew install bat\n\n# Beautiful diffs\nbrew install git-delta\n\n# Fast search\nbrew install ripgrep\n```\n\n**Without these tools**, claude-term gracefully falls back to basic alternatives, but the experience is significantly enhanced with them.\n\n## Troubleshooting\n\n### \"IDE server already running\"\n```bash\n# If you see this warning, either:\n# 1. Use the existing session in Claude (/ide)\n# 2. Use a different name:\nnode dist/cli.js start --name my-project-v2\n# 3. Remove the old lock file:\nrm ~/.claude/ide/{port}.lock\n```\n\n### Connection Issues\n- Ensure `claude-term` is running and shows \"Waiting for connection...\"\n- Check that the IDE name matches what you see in Claude's `/ide` list\n- Verify the workspace path is correct\n- Try debug mode: `CLAUDE_TERM_DEBUG=1 node dist/cli.js start`\n\n### Line Selection Issues\n- Ensure `fzf` is installed: `brew install fzf`\n- Check that files exist before opening with `/cat`\n- Use `/browse` for guided file selection if needed\n- Try basic selection without fzf as fallback\n\n### File Sending Issues  \n- Ensure Claude Code is connected (you see the interactive prompt `\u003e`)\n- Check that files exist before sending: `ls path/to/file`\n- Use `/browse` for interactive file selection with preview\n\n### MCP Tools Issues\n- Ensure MCP server is added: `claude mcp list` should show your server\n- Check MCP server status: Look for \"Added stdio MCP server...\" message\n- Verify MCP server path: `node dist/mcp-server.js` should exist and be executable\n- For permission issues: Ensure the workspace directory is accessible\n- Debug MCP issues: Use `node dist/cli.js start --debug` for verbose logging\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Follow the TDD approach (write tests first)\n4. Ensure all tests pass: `npm test`\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpppp606%2Fclaude-term","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpppp606%2Fclaude-term","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpppp606%2Fclaude-term/lists"}