⭐ Teleport - Jump to Code That Matters

Smart Symbol-Based Bookmarks for VS Code - Never lose your place again. Teleport to functions, classes, and methods that survive refactoring, renaming, and code movement.

📖 Table of Contents

Why Teleport?
Features
Installation
Quick Start
Commands
Keyboard Shortcuts
Configuration
Development
Architecture
Roadmap
Contributing
License

🎯 Why Teleport?

The Problem with Traditional Bookmarks

// ❌ Traditional bookmarks save line numbers
// File: payment.ts:187
// Problem: Code changes, refactoring happens, bookmark breaks!

// PaymentService.retry()  ← Line 187
// After refactoring → Line 203
// Bookmark is now pointing to wrong code! 💥

The Teleport Solution

// ✅ Teleport saves symbol paths
// File: payment.ts
// Symbol: PaymentService.retry()
// Always finds the function, no matter where it moves!

⭐ PaymentService.retry()
   └── Survives rename, move, and refactoring! 🎯

Traditional Bookmarks ❌	Teleport ✅
Save line numbers	Save symbol paths
Break on code changes	Survive refactoring
Show file:line	Show symbol names
Manual updates	Auto-repair
Line-based	Structure-based

✨ Features

1. 🎯 Symbol-Based Bookmarks

Bookmark functions, classes, methods, and other symbols instead of line numbers.

⭐ PaymentService.retry()
⭐ AuthController.login()
⭐ CacheManager.invalidate()
⭐ GraphTraversal.bfs()

2. 🔄 Auto-Repair

When a symbol is renamed or moved, Teleport automatically finds and repairs the bookmark.

⚠ Symbol "retry()" not found
🔍 Searching for similar symbol...
✅ Found "retryPayment()"
💡 Repair bookmark? [YES] [NO]

3. ⚡ Quick Teleport (`Ctrl+Shift+J`)

Instantly search and teleport to any bookmark without opening the sidebar.

> auth
⭐ Auth Login
⭐ Auth Logout
⭐ Auth Middleware

4. 📂 Smart Grouping

Bookmarks are automatically organized by file and category.

📁 payment.ts
   ⭐ PaymentService.retry()
   ⭐ PaymentService.refund()
📁 auth.ts
   ⭐ AuthController.login()
   ⭐ AuthController.logout()

5. 🔍 Intelligent Search

Fuzzy search finds bookmarks even with partial names.

Search: "pay retry" → ⭐ PaymentService.retry()
Search: "auth log" → ⭐ AuthController.login()

6. 💾 Persistent Storage

Bookmarks are saved in workspace state - no config files, no git changes.

7. 🎨 Custom Categories

Organize bookmarks with custom categories.

⭐ Payments
⭐ Performance
⭐ Bug Fixes
⭐ Sprint 18
⭐ Research

8. 🕒 Recent Bookmarks

Automatically tracks your most used bookmarks.

Recent
⭐ retry()
⭐ login()
⭐ createInvoice()

9. 📍 Status Bar Integration

See your current bookmark and jump instantly.

⭐ Retry Payment  ← Click to open sidebar

10. 🚀 Breadcrumb Navigation

Always know where you are.

⭐ retry()
  └── PaymentService
       └── services/payment.ts

📦 Installation

From VS Code Marketplace (Coming Soon)

# Search for "Teleport" in VS Code Extensions
# Or install via command line
code --install-extension yourusername.teleport

Manual Installation

# Clone the repository
git clone https://github.com/yourusername/teleport.git
cd teleport

# Install dependencies
npm install

# Build the extension
npm run compile

# Package the extension
npm run package
# Install the .vsix file
code --install-extension teleport-0.1.0.vsix

🚀 Quick Start

1. Add Your First Teleport Point

# Open any TypeScript/JavaScript file
# Place cursor on a function/class
# Press: Ctrl+Alt+K
# Enter a name: "Retry Payment"
# Done! ⭐ Bookmark created!

2. Teleport to It

# Press: Ctrl+Shift+J
# Type: "retry"
# Press: Enter
# You're instantly teleported! 🚀

3. Manage Bookmarks

# Open sidebar: Click ⭐ icon in activity bar
# Or: Ctrl+Shift+E then click Teleport
# Manage all your teleport points

⌨️ Commands

Core Commands

Command	Description
`Teleport: Add Bookmark`	Add bookmark at cursor position
`Teleport: Toggle Bookmark`	Add/remove bookmark
`Teleport: Remove Bookmark`	Remove existing bookmark
`Teleport: Quick Teleport`	Quick search and teleport
`Teleport: Show Sidebar`	Open teleport sidebar
`Teleport: Rename Bookmark`	Rename a bookmark

Navigation Commands

Command	Description
`Teleport: Next Bookmark`	Jump to next bookmark
`Teleport: Previous Bookmark`	Jump to previous bookmark
`Teleport: Show Current`	Show current bookmark info

Management Commands

Command	Description
`Teleport: List All`	List all bookmarks
`Teleport: Clear All`	Remove all bookmarks
`Teleport: Export`	Export bookmarks to JSON
`Teleport: Import`	Import bookmarks from JSON

⌨️ Keyboard Shortcuts

Shortcut	Action
`Ctrl+Alt+K`	Toggle bookmark
`Ctrl+Shift+J`	Quick teleport
`Ctrl+Alt+Down`	Next bookmark
`Ctrl+Alt+Up`	Previous bookmark
`Ctrl+Shift+E`	Focus sidebar

⚙️ Configuration

{
  // Show current bookmark in status bar
  "teleport.showStatusBar": true,

  // Automatically suggest repair for broken bookmarks
  "teleport.autoRepair": true,

  // Maximum bookmarks to keep in recent list
  "teleport.recentLimit": 10,

  // Show symbols icons in sidebar
  "teleport.showIcons": true,

  // Default category for new bookmarks
  "teleport.defaultCategory": "",

  // Enable telemetry
  "teleport.telemetry": false
}

🔧 Development

Prerequisites

Node.js 18+
VS Code 1.85.0+
TypeScript 5.2+

Setup Development Environment

# Clone repository
git clone https://github.com/yourusername/teleport.git
cd teleport

# Install dependencies
npm install

# Watch for changes
npm run watch

# Open in VS Code
code .

# Press F5 to start debugging

Project Structure

teleport/
├── src/
│   ├── extension.ts          # Main entry point
│   ├── commands/             # Command handlers
│   │   ├── addBookmark.ts
│   │   ├── removeBookmark.ts
│   │   └── quickTeleport.ts
│   ├── services/             # Business logic
│   │   ├── BookmarkManager.ts
│   │   ├── SymbolResolver.ts
│   │   └── StorageManager.ts
│   ├── providers/            # UI providers
│   │   ├── SidebarProvider.ts
│   │   └── TeleportTreeItem.ts
│   ├── ui/                   # UI components
│   │   ├── QuickPick.ts
│   │   └── StatusBar.ts
│   └── types/                # TypeScript types
│       └── index.ts
├── resources/                # Icons and assets
│   └── teleport-icon.svg
├── package.json              # Extension manifest
├── tsconfig.json            # TypeScript config
└── README.md                # Documentation

Build Commands

# Compile TypeScript
npm run compile

# Watch mode
npm run watch

# Lint code
npm run lint

# Package extension
npm run package

# Test extension
npm run test

Debugging

Open project in VS Code
Press F5 to launch Extension Development Host
Open a TypeScript/JavaScript file
Test features: Ctrl+Alt+K to add, Ctrl+Shift+J to teleport

🏗️ Architecture

Core Components

graph TD
    A[VS Code API] --> B[Extension Entry]
    B --> C[BookmarkManager]
    B --> D[SymbolResolver]
    B --> E[StorageManager]
    C --> F[SidebarProvider]
    C --> G[Commands]
    D --> H[Language Server]
    E --> I[Workspace State]
    F --> J[TreeView UI]
    G --> K[Quick Pick UI]

Data Flow

// 1. User adds bookmark
User → Editor → SymbolResolver → BookmarkManager → StorageManager

// 2. User teleports
User → QuickPick → BookmarkManager → SymbolResolver → Editor

// 3. Auto-repair
BookmarkManager → SymbolResolver → SimilarityCheck → Editor

Storage Schema

interface TeleportBookmark {
  id: string; // Unique identifier
  uri: string; // File URI
  symbolPath: string[]; // ['PaymentService', 'retry']
  kind: vscode.SymbolKind; // Method, Function, etc.
  label: string; // 'Retry Payment'
  category?: string; // 'Payments'
  fingerprint?: string; // Unique hash for matching
  createdAt: number; // Timestamp
  updatedAt: number; // Last access time
}

🗺️ Roadmap

Version 0.1.0 (MVP) ✅

✅ Symbol-based bookmarks
✅ Sidebar with grouping
✅ Quick teleport
✅ Keyboard shortcuts
✅ Persistent storage

Version 0.2.0 (Coming Soon)

🔄 Auto-repair for renamed symbols
🎨 Custom categories
🔍 Fuzzy search
📊 Recent bookmarks
🎯 Go to next/previous

Version 0.3.0 (Planned)

🌐 Multiple language support
- ✅ TypeScript/JavaScript
- ✅ Python
- ✅ Go
- ✅ Java
- ✅ C#
- ✅ PHP
🔄 Symbol conflict resolution
📝 Bulk operations
🏷️ Tag support

Version 1.0.0 (Future)

🤖 AI-powered symbol matching
🌟 Community bookmarks
🔄 Sync across devices
📊 Analytics dashboard
🤝 Team collaboration

🤝 Contributing

We welcome contributions! 🎉

How to Contribute

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow TypeScript best practices
Write meaningful commit messages
Add tests for new features
Update documentation
Ensure linting passes

Report Issues

Use GitHub Issues
Include VS Code version
Provide steps to reproduce
Attach screenshots if applicable

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with ❤️ for the VS Code community
Inspired by the need for better code navigation
Thanks to all contributors and testers

📞 Support

📧 Email: support@teleport.dev
🐦 Twitter: @teleport_dev
💬 Discord: Join our community
📖 Documentation: docs.teleport.dev

⭐ Star History

Made with ❤️ by the Teleport Team

"Jump to code that matters." 🚀

Name		Name	Last commit message	Last commit date
.vscode		.vscode
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
AGENTS.md		AGENTS.md
README.md		README.md
opencode.json		opencode.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation