🚀 Just Code

Just Code is a rapid development tool that bridges the gap between your local development environment and a AI (LLM) chat interface. It allows you to:

1. Send your entire project's context to an LLM with a single click and prompt your task.
2. Deploy code generated by the LLM in many files back to your local files with another single click.
3. Instantly Undo and Redo any changes that don't work as expected.

This creates a tight, safe, and incredibly fast feedback loop for iterating on code with AI assistance. Because the LLM receives the full context, it can generate scripts that create, modify, and delete dozens of files at once, allowing you to implement complex features with a single deployment.

---

🚀 Quick Start Guide

1. Go to Your LLM

Navigate to your favorite AI chat interface. We highly recommend Google AI Studio with the Gemini 2.5 Pro model for the best results.

2. Open JustCode

Click the JustCode icon in your Chrome toolbar. We suggest pinning it for easy access!

3. Select Your Project Folder

In the "Browser (JS) Mode", click "Select Project Folder". You may need to grant permission 2-3 times until Chrome offers the "Allow on every visit" option. This is a crucial step for persistent access.
Alternatively, for more advanced control, check out the Server Mode setup.

4. Get Context & Add Your Task

Click "Get Context". This will load your project files into the AI's chat box. Scroll to the bottom and type your task, for example: "Add a new feature that does X and Y."

5. Filter Large Projects (If Needed)

If your project is large, you'll get a prompt to create an "exclude list". Just send this prompt to the AI. It will reply with a list of files to ignore. Copy this list, paste it into the "Exclude Patterns" field in your JustCode profile, and click "Get Context" again. You may need to repeat this process a few times to fine-tune your exclusions until the project size is under the limit.
Tip: Most projects are 50k-700k characters. If yours is larger, you likely have unneeded files that should be excluded.

6. Deploy Code

After the AI generates its response (a bash script), simply click "Deploy Code" in the JustCode extension. The changes will be applied directly to your local files.

7. Verify & Undo

Check the changes in your IDE. If the result isn't what you expected, just click "Undo". Don't be discouraged if it's not perfect—around 15% of AI answers have minor mistakes. Refine your prompt and try again!

8. Support the Project

If you find JustCode useful, please consider supporting the project by leaving a star on the GitHub repository. It helps a lot! Thanks in advance!

---

💡 Pro Tip: Recommended LLM
While JustCode can work with many LLMs, it is highly optimized for and tested with Google AI Studio using the Gemini 2.5 Pro model. Its large context window (1 million tokens) and strong instruction-following capabilities provide the most reliable results.

⚙️ How It Works

The system consists of a Chrome Extension that can operate in two different backend modes, which you can select per-profile within the extension:

• 🖱️ Browser (JS) Backend (Default & Recommended): This mode runs entirely within your browser. It uses the modern File System Access API to directly and safely read your project files and write changes back.

  • Pros: No Python or server setup required. It's the simplest and fastest way to get started.
  • Cons: Requires you to grant permission for each project folder you want to work with, for first project permissions should be granted twice.

• 🐍 Server Backend: This optional mode uses a local Flask server (app.py) that you run on your machine. The extension communicates with this server to access your filesystem.

  • Pros: Can work with any project path you provide without needing per-folder browser permissions.
  • Cons: Requires Python and leaving a terminal process running in the background.

The Chrome Extension (chrome_extension/) provides a unified user-friendly interface for both modes, including multi-profile management, settings, and direct action buttons.

Shortcuts

• Global Shortcuts (Work even when the popup is closed):

  • Get Context: (ALT + ←) or (⌥←)
  • Deploy Code: (ALT + →) or (⌥→)
  • Undo: (ALT + <) or (⌥<)
  • Redo: (ALT + >) or (⌥>)

• Popup-Only Shortcuts (Work only when the popup is open):

  • Switch Profile Left: (ALT + A) or (⌥A)
  • Switch Profile Right: (ALT + S) or (⌥S)

Note on Shortcuts: If a shortcut doesn't work, you may need to set or reset it. Go to chrome://extensions/shortcuts in your browser, find "JustCode", and assign your preferred shortcuts. The ALT + ← shortcut might conflict with the browser's "Back" navigation; you can easily remap it on the shortcuts page.

↩️ Automatic Undo/Redo History

Never fear a bad deployment again. Just Code includes a powerful safety net that works for both Browser (JS) and Server modes:

• Automatic History: When you click Deploy Code, two scripts are saved:
  1. The deployment script itself (which becomes the "redo" script).
  2. An automatically generated "undo" script that perfectly reverses the deployment.
• Instant Recovery: If a deployment produces an undesirable result, simply click the Undo button. Your files are instantly restored. Clicked Undo by mistake? Just click Redo.
• Intelligent History: The undo/redo history works just like in a text editor. If you undo several changes and then make a new deployment, the old "redo" history is cleared, as it no longer applies to the new state of your project.

This feature allows you to experiment and iterate with AI-generated code fearlessly, knowing you can instantly step backward and forward through your changes.

✅ Prerequisites

• 🌐 Google Chrome or a Chromium-based browser that supports loading unpacked extensions.

For Server Mode Only:

• 🐍 Python 3.10 or higher
• 📦 pip and venv (usually included with Python)
• 🐙 Git (if you want to use the built-in update feature via git pull)

🛠️ Setup

Stage 1: Get the Code

You have two options:

• A) Download ZIP (Easiest):

  1. Go to the JustCode GitHub repository.
  2. Click Code > Download ZIP.
  3. Unzip the file on your computer.

• B) Git Clone (For updates & server mode):

  git clone https://github.com/achendev/justcode.git
  cd justcode

Stage 2: Load the Chrome Extension

1. Load the Extension:

   • Open Chrome and navigate to chrome://extensions/.
   • Enable Developer mode using the toggle switch (usually in the top-right corner).
   • Click the Load unpacked button.
   • In the file dialog, select the chrome_extension folder located inside your unzipped or cloned justcode project directory.

2. Pin the Extension:

   • Click the puzzle piece icon 🧩 in the Chrome toolbar, find JustCode, and click the pin icon to keep it visible.

Stage 3: Configure a Profile

1. Open the JustCode extension popup. A default profile is already created for you.
2. Choose your backend mode using the toggle button next to the project location input:
   • 🖱️ Browser (JS) Mode (Default): Runs entirely in the browser.
   • 🐍 Server Mode: Connects to a local Python server.

Using Browser (JS) Mode

1. Make sure the browser icon is selected in the backend toggle.
2. Click the Select Project Folder button. A new small window will open.
3. In the new window, click the "Select Folder" button again. This user gesture is required for Chrome to show the folder picker.
4. Choose your project's root directory and click Allow.
5. Granting Persistent Access: Due to Chrome's security policies, you'll have to grant permission more than once to establish persistent access for a project. For second time the browser will offer an "Allow on every visit", it's required.

Using Server Mode

1. Make sure the server icon is selected in the backend toggle.
2. Follow the OS-specific instructions in the "Running the Server (Optional)" section below to start the local Python server.
3. In the extension, enter the full, absolute path to your project in the "Project Location" text field (e.g., /Users/yourname/projects/my-app or C:\Users\yourname\projects\my-app).

Running the Server (Optional - Only for Server Backend)

The provided helper scripts (app.sh for macOS/Linux, app.bat for Windows) automate the entire server setup process, including creating a virtual environment and installing dependencies.

🍎 macOS & 🐧 Linux

1. Open a terminal in the justcode directory.
2. Run the helper script:

   ./app.sh

   The script will create a venv directory, install requirements, and start the server. Keep this terminal window open while you use the server backend.

🪟 Windows

1. Open PowerShell or Command Prompt in the justcode directory.
2. Run the helper script:

   .\app.bat

   Alternatively, you can simply double-click the app.bat file in Windows Explorer. The script will create a venv directory, install dependencies, and start the server. Keep the terminal window open.

---

🔧 Server Configuration

This section applies only if you are using the Server Backend. You can configure the server's listening address and port using a .env file in the project root.

1. Copy the example file: cp env.example .env (or copy .env.example .env on Windows).
2. Edit .env:
   • FLASK_RUN_HOST: The IP address to bind to.
     • 127.0.0.1 (Default): Accessible only from your own computer.
     • 0.0.0.0: Accessible from other devices on your network. Use with caution on trusted networks only.
   • FLASK_RUN_PORT: The port to listen on (e.g., 5010).

If you change the server URL or port, remember to update it in the extension's profile settings.

🗂️ Handling Large Projects: Automatic Context Filtering

LLMs have a context window limit, meaning you can't always send your entire project's source code at once. JustCode has a smart feature to help you manage this.

Context Size Limit

In each profile's settings (click the ⚙️ button), you can set a Context Size Limit in characters. The default is 3,000,000.

Automatic Exclusion Suggestions

If you click Get Context and the tool determines that your project's content exceeds this limit, it won't send the code. Instead, it will do the following:

1. Analyze Your Project: It quickly scans your project's file structure and the size of each file.
2. Generate a Smart Prompt: It sends this file tree analysis to the LLM, asking it to suggest which files and directories should be excluded to shrink the context size. The prompt is specifically designed to identify common non-essential files like node_modules, build artifacts, large data files, and logs.
3. Receive Exclusion Patterns: The LLM will respond with a comma-separated list of patterns (e.g., node_modules/,dist/,*.log).
4. Update and Retry: You can then copy this list, paste it into your profile's "Exclude Patterns" field, and click Get Context again.

This workflow turns the tedious task of manually curating a large project's context into a quick, AI-assisted process.

⚠️ Security Warning

This tool executes code generated by an LLM directly on your machine. This is not foolproof.

• ALWAYS review the bash script before clicking "Deploy Code". Malicious commands can delete files.
• An undo/redo history is created automatically, giving you a way to recover from mistakes, but it's not a substitute for careful review.
• This tool is intended for personal development and rapid prototyping.
• Use at your own risk.

📂 Project Structure

justcode/
├── app.py                      # Main Flask application runner (for Server Backend)
├── app.sh                      # Helper script to run server on macOS/Linux
├── app.bat                     # Helper script to run server on Windows
├── chrome_extension/
│   ├── css/                    # Stylesheets for the extension popup
│   ├── js/                     # JavaScript modules
│   │   ├── background.js       # Service worker for handling background tasks (like shortcuts)
│   │   ├── content_script/     # Logic injected into web pages (e.g., for notifications)
│   │   ├── context_builder/    # Logic for building prompts for the LLM
│   │   │   └── paste_handlers/ # Site-specific logic for pasting text/files
│   │   ├── db/                 # IndexedDB wrapper for storing folder handles
│   │   ├── deploy_code/        # Logic for parsing and executing deployment scripts
│   │   │   ├── answer_extractors/ # Site-specific logic for extracting code from LLM answers
│   │   │   └── robust_fallback_handlers/ # Logic for special cases like toggling raw mode
│   │   ├── event_listeners/    # Attaches event listeners to UI elements
│   │   ├── get_context/        # Strategies for getting project context (JS vs Server)
│   │   ├── popup/              # Modules specifically for the popup's lifecycle and UI
│   │   ├── ui_handlers/        # Modules for handling UI events and rendering
│   │   │   ├── html_generators/ # Functions that generate HTML strings for UI components
│   │   │   └── profile_actions/# Handlers for profile creation, navigation, and state
│   │   ├── default_instructions.js # The default prompt instructions for the LLM
│   │   ├── deploy_code.js      # Main facade for deploying code
│   │   ├── event_attacher.js   # Central point for attaching all event listeners
│   │   ├── file_system_manager.js # Manages File System Access API handles (for JS Backend)
│   │   ├── get_context.js      # Main facade for getting context
│   │   ├── picker.js           # Logic for the folder picker window (JS Backend)
│   │   ├── storage.js          # Manages user profiles in chrome.storage
│   │   ├── ui.js               # Main UI rendering and state management
│   │   └── undo_redo.js        # Handles Undo/Redo logic for both modes
│   ├── manifest.json           # Extension configuration
│   ├── picker.html             # A dedicated window for the folder picker (JS Backend)
│   └── popup.html              # Extension popup UI
├── server/                     # Backend server logic (for Server Mode)
│   ├── tools/                  # Utility modules for the server
│   │   ├── context_generator.py # Generates project context string
│   │   ├── history_manager.py  # Manages undo/redo script files
│   │   ├── script_executor.py  # Parses and executes deployment scripts
│   │   └── utils.py            # Common server utilities (path safety, etc.)
│   ├── deploy_code_endpoint.py # Handles /deploycode endpoint
│   ├── get_context_endpoint.py # Handles /getcontext endpoint
│   ├── redo_endpoint.py        # Handles /redo endpoint
│   ├── undo_endpoint.py        # Handles /undo endpoint
│   └── update_endpoint.py      # Handles /update endpoint for git pull
├── .env.example                # Example environment file for server config
├── requirements.txt            # Python dependencies (for Server Backend)
└── README.md                   # This file