Active Context

Bridge VS Code to your external tools with a professional-grade REST API.

Active Context exposes your current editor state—the file you're working on and any selected text—through a local HTTP endpoint with advanced port management, cross-platform process detection, and intelligent error handling. Perfect for integrating VS Code with AI tools, automation scripts, MCP servers, or custom workflows.

🚀 What it does

• Real-time context sharing: Instantly access your active file path and selected text from any local tool
• Advanced port management: Smart port validation, reserved port detection, and automatic alternatives
• Cross-platform process detection: See exactly which process is using a port (Windows/Linux/macOS)
• Professional notifications: Rich error messages with actionable solutions
• Port scanner tool: Find available ports across development and system ranges
• Secure by design: Local-only server (127.0.0.1) keeps your data private

📋 Use Cases

• AI-powered coding: Send your current selection to language models for analysis or refactoring
• Custom automation: Build scripts that react to your current editor context
• Documentation tools: Generate docs based on selected code snippets
• Code review workflows: Extract context for external review systems
• Learning tools: Create personalized coding tutorials based on your active work

🔧 How it works

1. Install the extension from the marketplace
2. Select any text in your editor (or leave empty for just the file path)
3. Query http://localhost:3000/context from your tool

Example response:

{
  "filePath": "/Users/you/project/src/components/Button.tsx",
  "selectedText": "const Button = ({ children, onClick }) => {\n  return <button onClick={onClick}>{children}</button>;\n};"
}

⌨️ Command Palette

Access these commands via Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS):

Tip: Type "Active Context" in Command Palette to see all available commands.

⚙️ Configuration

• Port setting: Change the server port in VS Code Settings → "Active Context: Server Port" (default: 3000)
• Smart validation: Real-time port validation with process detection and safety warnings
• Recommended ranges: 3000-3100 (development), 49152-65535 (dynamic/private)
• Auto-restart: The server automatically restarts when you change the port

🔒 Security & Privacy

• Local only: The server binds to 127.0.0.1 (localhost), preventing remote access
• No data collection: Your code never leaves your machine
• Opt-in sharing: Only exposes data when you actively query the endpoint

🛠️ Integration Examples

cURL

curl http://localhost:3000/context

Python

import requests
response = requests.get('http://localhost:3000/context')
context = response.json()
print(f"Working on: {context['filePath']}")

Node.js

const response = await fetch('http://localhost:3000/context');
const { filePath, selectedText } = await response.json();

🔧 Advanced Features

Port Management

• Process Detection: See exactly which process is using a port (e.g., "Port 3000 is in use by Code.exe (PID: 35596)")
• Reserved Port Prevention: Automatically prevents using system ports (80, 443, etc.) with helpful messages
• Privileged Port Warnings: Warns against ports below 1024 that require admin privileges
• Smart Alternatives: Suggests available alternative ports when conflicts occur
• One-click Solutions: Notifications include actionable buttons ("Use Port 3001", "Open Settings")

Port Scanner

• Multiple Ranges: Scans both development ports (3000-3100) and system dynamic ports (49152-49200)
• Progress Indication: Real-time progress with current port being scanned
• Detailed Results: View all available ports or select one directly
• Quick Apply: Instantly update configuration from scan results

Error Handling

• Graceful Fallbacks: Robust error handling that doesn't crash your extension
• Actionable Notifications: Error messages include solutions, not just problems
• Cross-platform Support: Process detection works on Windows, macOS, and Linux

💡 Pro Tips

• Multi-line selections: The extension preserves exact formatting, including newlines and indentation
• Empty selections: When nothing is selected, selectedText returns an empty string
• Cross-platform paths: Windows paths are normalized to forward slashes for consistency
• Real-time updates: The endpoint always reflects your current editor state
• Port conflicts: When you see port conflict notifications, use the suggested alternatives or run "Scan Available Ports"

🛠️ Troubleshooting

Common Issues

"Port already in use" errors:

• Check the notification for which process is using the port
• Use "Active Context: Scan Available Ports" command (Ctrl+Shift+P) to find alternatives
• Try the suggested alternative port from the notification

Server not starting:

• Avoid ports below 1024 (require admin privileges)
• Don't use reserved system ports (80, 443, etc.)
• Use recommended ranges: 3000-3100 or 49152-65535

Process detection not working:

• Process detection gracefully falls back to generic messages
• Requires appropriate system commands (netstat, ss, lsof) to be available
• Works on Windows, macOS, and most Linux distributions

Security Considerations

• Localhost only: Server binds to 127.0.0.1 (not accessible remotely)
• Process detection: Uses standard system tools (netstat, ss, lsof) - no elevated privileges required
• No data persistence: Context is fetched on-demand, not stored or cached
• Minimal exposure: Only exposes active file path and selected text

🚀 Getting Started

1. Install from the VSCode Marketplace
2. Configure your preferred port in Settings → "Active Context: Server Port" (optional)
3. Test with: curl http://localhost:3000/context
4. Use Command Palette commands above for port management and troubleshooting
5. Integrate with your favorite AI tools, automation scripts, or workflows

📦 What's New in v0.2.0

• ✨ Enterprise-grade port management with process detection
• 🔍 Cross-platform process identification (Windows/Linux/macOS)
• ⚡ Port scanner tool for finding available ports
• 🛡️ Smart security warnings for reserved and privileged ports
• 🎯 Professional notifications with one-click solutions
• 📋 Enhanced Command Palette integration

📞 Support & Resources

• 🐛 Issues: Report bugs or request features on GitHub
• 📖 Developer docs: See README-dev.md for technical details and contributing
• 🤖 MCP Integration: Perfect companion for Model Context Protocol servers
• ✅ Compatibility: VSCode 1.80+ on Windows, macOS, and Linux
• 📜 License: MIT (free and open source)

Ready to supercharge your coding workflow? Install Active Context and join thousands of developers building powerful integrations with AI tools, automation scripts, and custom workflows.