ReCodeX Extension

Turn research papers into executable code — and verify it actually works.

ReCodeX is a VS Code extension that transforms academic research papers (PDFs) into runnable code implementations. Simply upload a paper, and ReCodeX will analyze it and generate the corresponding source code files directly in your workspace.

Features

• PDF Upload: Select and upload research papers directly from VS Code
• Automatic Code Generation: Converts paper algorithms and methods into executable code
• Workspace Integration: Generated files are organized in your project directory
• Real-time Progress Tracking: Visual progress bar shows processing status
• Backend Health Monitoring: Live connectivity status indicator
• Secure File Handling: Path validation and sanitization for safe file operations

Installation

From Source

1. Clone the repository:

   git clone https://github.com/your-username/recodex-extension.git
   cd recodex-extension
   

2. Install dependencies:

   npm install
   

3. Compile the extension:

   npm run compile
   

4. Press F5 in VS Code to launch the Extension Development Host.

From VSIX Package

1. Build the package:

   npm run package
   

2. Install the .vsix file via VS Code:

   • Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
   • Run "Extensions: Install from VSIX..."
   • Select the generated .vsix file

Requirements

• VS Code: Version 1.107.0 or higher
• Backend Service: A running ReCodeX backend server (default: http://localhost:8000)

Uploading PDF Files

ReCodeX makes it easy to upload research papers and generate code. Here's everything you need to know about the PDF upload process.

How to Upload a PDF

There are two ways to upload a research paper:

Method 1: Using the Command Palette

1. Open the Command Palette (Cmd+Shift+P on macOS / Ctrl+Shift+P on Windows/Linux)
2. Type "ReCodeX: Upload Research Paper"
3. Press Enter
4. Select your PDF file from the file dialog

Method 2: Using the Sidebar

1. Click the ReCodeX icon (beaker) in the Activity Bar on the left side of VS Code
2. In the sidebar panel, click the "Upload Research Paper" button
3. Select your PDF file from the file dialog

PDF File Requirements

Upload Process Step-by-Step

+-------------------------------------------------------------------+
|  1. SELECT FILE                                                    |
|     --> File dialog opens -> Choose your PDF                      |
|                                                                    |
|  2. FILE VALIDATION                                                |
|     --> Extension verifies PDF format                             |
|                                                                    |
|  3. SAVE PDF LOCALLY                                               |
|     --> PDF saved to .recodex/uploads/ in your workspace          |
|                                                                    |
|  4. UPLOAD TO BACKEND                                              |
|     --> PDF sent via multipart/form-data to /implement            |
|     --> Progress bar shows real-time status                       |
|                                                                    |
|  5. CODE GENERATION                                                |
|     --> Backend analyzes paper and generates code                 |
|                                                                    |
|  6. FILE CREATION                                                  |
|     --> Generated files written to workspace:                     |
|         <paper-name>/                                              |
|           +-- src/main.py                                          |
|           +-- requirements.txt                                     |
|           +-- README.md                                            |
|           +-- ...                                                  |
|                                                                    |
|  7. COMPLETION                                                     |
|     --> Success message displayed with file count                 |
|     --> Upload another paper to create another directory          |
+-------------------------------------------------------------------+

What Happens During Upload

1. File Selection

   • A native file picker dialog opens
   • Only PDF files can be selected (filtered by .pdf extension)
   • The file path is validated before proceeding

2. Reading the PDF

   • The PDF file is read from disk as binary data
   • File contents are prepared for transmission

3. Local Storage

   • The PDF is saved to .recodex/uploads/ in your workspace
   • Filename includes timestamp for uniqueness (e.g., 2024-01-15T10-30-00_paper.pdf)
   • This allows you to reference the original paper later

4. Backend Communication

   • The PDF is sent to the backend via HTTP POST request
   • Uses multipart/form-data encoding for file upload
   • Request includes:
     • Binary PDF file data
     • Original filename

5. Processing

   • Backend analyzes the research paper
   • Extracts algorithms, methods, and implementation details
   • Generates corresponding source code

6. File Generation

   • Response contains generated file paths and contents
   • Files are written to <paper-name>/ directory at workspace root
   • Each paper gets its own directory for easy organization

Progress Tracking

During upload and processing, the sidebar displays:

• Progress Bar: Visual indicator with percentage (0-100%)
• Status Messages: Current operation being performed
• Connection Status: Green dot (connected) or red dot (disconnected)

Generated Output Structure

Each PDF gets its own directory at the workspace root, allowing you to work on multiple research papers:

your-workspace/
├── .recodex/
│   └── uploads/                    # Uploaded PDFs are saved here
│       ├── 2024-01-15T10-30-00_attention_paper.pdf
│       └── 2024-01-15T11-45-00_transformer_paper.pdf
│
├── attention_paper/                # First paper's implementation
│   ├── src/
│   │   ├── main.py
│   │   └── utils.py
│   ├── requirements.txt
│   ├── README.md
│   └── .gitignore
│
└── transformer_paper/              # Second paper's implementation
    ├── src/
    │   ├── main.py
    │   └── utils.py
    ├── requirements.txt
    ├── README.md
    └── .gitignore

This structure allows you to:

• Upload multiple papers one after another
• Keep each implementation separate and organized
• Compare different paper implementations side by side

Handling Existing Files

If generated files already exist in your workspace:

1. A confirmation dialog will appear
2. Choose "Yes" to overwrite existing files
3. Choose "No" to cancel and preserve existing files

Supported PDF Content

ReCodeX works best with:

• Machine learning research papers
• Algorithm descriptions and pseudocode
• Technical specifications
• Academic papers with clear methodology sections
• Papers containing mathematical formulas and implementations

Troubleshooting PDF Upload

Viewing Upload Logs

To see detailed upload and processing logs:

Method 1: Sidebar Button

1. Click "View Logs" in the ReCodeX sidebar

Method 2: Output Panel

1. Open Output panel (View -> Output or Cmd+Shift+U)
2. Select "ReCodeX" from the dropdown menu

Logs include:

• File selection events
• Upload progress
• Backend responses
• Error details with stack traces

Backend API

ReCodeX communicates with a backend service that processes PDFs and returns generated code.

Full API Documentation: See docs/BACKEND_API.md for complete backend implementation guide including:

• Detailed endpoint specifications
• Request/response schemas
• Implementation examples (Python, Node.js, Go)
• Security considerations
• Deployment checklist

Quick Reference

Implement Endpoint

POST /implement
Content-Type: multipart/form-data

Form Fields:
  - file: PDF binary data (required)
  - query: Custom prompt (optional)
  - chunk_size: Text chunk size (optional)
  - chunk_overlap: Chunk overlap (optional)
  - top_k_retrieve: Retrieval count (optional)
  - top_k_rerank: Rerank count (optional)

Response:

{
  "success": true,
  "filename": "paper.pdf",
  "chunks_count": 42,
  "implementation": "# Full generated implementation code here...",
  "error": null
}

Running the Mock Server (Development)

For testing without a real backend:

npm run mock-server

This starts a mock server on port 8000 that:

• Accepts any PDF upload
• Returns sample Python files after a 1.5-second delay
• Useful for testing the extension UI and workflow

Development

Project Structure

recodex-extension/
├── src/
│   ├── api/
│   │   ├── backendClient.ts     # HTTP client for backend API
│   │   └── types.ts             # TypeScript interfaces
│   ├── commands/
│   │   └── uploadPaper.ts       # Upload command handler
│   ├── ui/
│   │   └── sidebarProvider.ts   # Webview sidebar UI
│   ├── utils/
│   │   ├── logger.ts            # Output channel logging
│   │   ├── paths.ts             # Path validation utilities
│   │   └── pdf.ts               # PDF file utilities
│   ├── workspace/
│   │   ├── fileWriter.ts        # Safe file writing
│   │   └── projectLayout.ts     # Project directory setup
│   └── extension.ts             # Extension entry point
├── test-fixtures/
│   ├── mock-server.js           # Mock backend for testing
│   └── sample-paper.pdf         # Sample PDF for testing
└── package.json

Available Scripts

Debugging

1. Open the project in VS Code
2. Press F5 to launch Extension Development Host
3. Set breakpoints in TypeScript files
4. Use the Debug Console to inspect variables

Security

ReCodeX implements several security measures to protect your system:

• Path Traversal Prevention: Rejects paths containing .. or absolute paths
• Filename Sanitization: Removes dangerous characters (<>:"|?*)
• Workspace Boundary Enforcement: All files written within workspace root only
• Content Security Policy: Webview restricted to extension resources
• Input Validation: All API responses validated before processing
• No Arbitrary Code Execution: Generated files are written, not executed

Dependencies

Production

Development

Contributing

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

Development Setup

# Clone your fork
git clone https://github.com/your-username/recodex-extension.git
cd recodex-extension

# Install dependencies
npm install

# Start development
npm run watch

# In another terminal, start mock server
npm run mock-server

# Press F5 in VS Code to test

License

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

Support

• Issues: GitHub Issues
• Documentation: Check this README and inline code comments
• Logs: Use the "View Logs" button in the sidebar for debugging