SuperCoder: A Terminal-Based Coding Assistant for Searching, Editing, and Debugging

SuperCoder is a coding assistant designed to run directly within your terminal. It streamlines the development process by providing tools for code searching, project navigation, file editing, and bug fixing—all controlled through natural language. Instead of manual navigation, you can simply ask the assistant to find code, modify a file, or display the project hierarchy. SuperCoder’s capabilities are built around several core tools: code search, code editing, file reading, project structure browsing, and code execution.

SuperCoder Features

1. Code Search: Perform complex searches across your entire project to locate specific patterns or logic quickly.
2. Project Structure Exploration: Access an organized, high-level view of your folders and files to understand the project layout.
3. Code Editing: Modify your codebase using plain English instructions, removing the need to hunt through files manually.
4. Error Fixing: Automatically identify and resolve bugs or apply code improvements based on your specific requests.
5. Cursor Rules Support: Utilize "cursor rules" to enable the assistant to intelligently understand and edit code at precise locations.

How to Install SuperCoder

1. Download the ZIP archive from the official releases page.
2. Extract the file to a directory on your computer. Ensure that the bin/supercoder file (or bin/supercoder.bat for Windows users) is included in your system’s PATH environment variable.
3. Open a terminal in the project folder you wish to work on and execute the supercoder command.

How to Use SuperCoder

Configure API Access

Option 1: Using the OpenAI API

Before launching the tool, set the OPENAI_API_KEY environment variable. You can obtain this key from your OpenAI dashboard.

export OPENAI_API_KEY=<YOUR_API_KEY>
export OPENAI_MODEL=<MODEL_NAME> # Defaults to "o3-mini". Monitor your usage costs accordingly.

Option 2: Using a local model or an OpenAI-compatible API

If you prefer to use a local model or a third-party OpenAI-compatible endpoint, configure these environment variables:

export SUPERCODER_BASE_URL=<URL>
export SUPERCODER_API_KEY=<KEY>
export SUPERCODER_MODEL=<MODEL>

If you are using Google Gemini, you must also set SUPERCODER_GEMINI_MODE=true. Note that your chosen model must support tool calling.

Run the Coding Agent

After building the project or unzipping the binary, run the executable. Once the agent is active, you can enter natural language commands such as:

• “Search for usage of function XYZ”
• “Edit path/to/file.scala to add a new method”
• “Show me the project structure”

The agent will interpret your instructions and invoke the appropriate tools to complete the task.

Supported Tools

• CodeSearchTool: Locates specific code patterns within the project.
• CodeEditTool: Performs direct edits on your project files.
• FileReadTool: Retrieves and displays the contents of specific files.
• ProjectStructureTool: Provides a comprehensive overview of the directory and file hierarchy.
• CodeExecutionTool: Runs shell commands based on the agent's internal evaluation.

How to Build SuperCoder from Source

1. Clone the repository:

git clone <repository-url>
cd SuperCoder

2. Build the project using SBT:

sbt compile

3. Run the test suite to verify the installation:

sbt test