Skip to content

README.md

Latest commit

 

History

History
316 lines (245 loc) · 14.5 KB

README.md

File metadata and controls

316 lines (245 loc) · 14.5 KB

🤖 SuperCoder

Version Python License

AI Coding Assistant for the Terminal — A powerful, extensible, and terminal-native coding agent designed to help you build, search, and fix code with natural language.

🆕 What's New in v0.3.0

  • Native API Tool Calling: Migrated from text-based streaming parsing to native OpenAI-compatible tools parameter. More reliable, no format-dependent parsing. Streaming mode still available via --stream.
  • Interactive Session Picker: /continue now shows an arrow-key navigable session list with relative timestamps ("5m ago") and message counts. No more typing numbers.
  • Visual Session History: Restored sessions render full conversation history with the same styling as live output — tool calls interleaved with results, reasoning blocks, markdown responses.
  • Message Display Types: Each message now stores its role (user_input, thinking, response, tool_call, tool_result, error) for accurate session restoration. Backward compatible with old sessions.
  • Fuzzy Matching for Edits: Three-tier edit matching — exact → whitespace-normalized → fuzzy (SequenceMatcher) — so local/weak models with formatting inconsistencies still apply edits correctly.
  • Lean Prompt Mode: Optional 75% shorter system prompts for weak/local models via lean: true in model profile config.
  • Parser Hardening: Fixed 4 Qwen3.5-4B failure modes — missing closing tags, single-quoted JSON, extra characters, and hallucinated tool names.
  • Live Generation Progress: Spinner shows token count, phase label ("response" / "tool call"), and elapsed time during generation. Works even when providers buffer output.
  • Streaming Abort: Double-ESC now works during active API streaming, with checkpoint rollback on abort.
  • Inline Auto-suggest: Gray-text suggestions for slash commands while typing. Enter to accept.
  • Command Approval Menu: Instant key-press approval ([y]/[a]/[n]) for shell commands instead of typing.
  • Interactive Setup Wizard: On first launch, a guided TUI wizard configures provider, model, context size, and API key.
  • Full Traceback Logging: All exceptions logged with complete Python tracebacks to ~/.supercoder/logs/ (JSONL format).

v0.2.9

  • Enhanced Autocomplete: Added intelligent autocompletion for slash commands and file paths using prompt_toolkit.
  • Multiline Input Support:
    • Use { ... } blocks for pasting large snippets of code.
    • Use Alt+Enter (or Esc+Enter) to insert newlines without submitting the message.
  • Improved Streaming Output: Integrated a custom markdown streaming renderer for smoother, live-updating responses that work better with terminal scrollback.

v0.2.8

  • Reasoning Block Display: Added dedicated support for displaying model "thinking" or "reasoning" steps. Reasoning is displayed in a distinct 💭 Reasoning block before the main response or tool calls.
  • Incremental Multi-Stage Output: Improved the REPL to display reasoning and tool calls incrementally. Long multi-turn interactions are now much easier to follow as each stage is rendered as it happens.
  • Improved GLM-4 Integration: Enhanced tool call parsing and filtering specifically for GLM-4 models, ensuring that raw tool tags are hidden from the final output even if they appear in the reasoning stream.
  • Advanced Session Logging: Added detailed logging of reasoning steps and streaming events to .supercoder/logs/, making it easier to analyze model behavior and debug complex interactions.

v0.2.7

  • Model-Specific Context Limits: Each model profile can now have its own max_context_tokens limit. This allows automatic switching between models with different context window sizes (e.g., 8k for local models vs 128k for cloud models) without manual reconfiguration.
  • Improved Context Management: Default context limits specified in config.yaml are now correctly respected unless overridden by the CLI flag.

v0.2.6

  • GLM-4 Support: Added a dedicated glm_tool_call format support specifically optimized for GLM-4.7-Flash and similar models.
  • Multi-Tool Support for GLM: The agent can now parse multiple tool calls in a single GLM model response.
  • Improved Display Filtering: Enhanced response filtering to hide raw GLM tool call tags from the assistant's output panel.

v0.2.5

  • Multiple Tool Call Support: Updated the parser framework to support models that send multiple tool calls in one turn across different formats.

v0.2.4

  • Atomic File Writes: Enhanced reliability by using temporary files for all write operations, preventing data loss on crashes.
  • Checkpoint & Rollback: Automatic backup before every file modification. Use /undo to revert changes instantly.
  • Graceful Interruption: Press Double-ESC during agent work to stop it safely without losing session state or leaving messy file edits.
  • Improved Undo Integration: The agent is now aware when you perform an undo and will re-evaluate file contents accordingly.

✨ Core Features

🔍 Code Search

Performs complex code searches across your project to quickly locate specific patterns using git grep with context-aware output and fallback to standard grep.

📁 Project Structure Exploration

Provides an organized, tree-based view of your project's folders and files, intelligently ignoring build artifacts and junk files (.git, node_modules, etc.).

✏️ Intelligent Code Editing

Modifies your codebase seamlessly using diff-based operations. Every edit is atomic and protected by a checkpoint system:

  • Atomic Writes: Changes are written to temporary files first, then moved to the original path.
  • Auto-Backups: Original file state is saved before any modification.
  • Smart Undo: Revert any number of changes with the /undo command.
  • Operations: search_replace, insert_after, replace_lines, and create.

📜 Supercoder Rules (Custom rules)

Leverage project-specific rules to guide the agent. Place .md files in .supercoder/rules/ and they will be automatically loaded into the agent's context.

🗺️ RepoMap Support

Uses tree-sitter and networkx to generate a high-level map of your repository, helping the LLM understand relationships between files and symbols.

🧠 Context Management

  • Token Counter: Real-time monitoring of context usage.
  • Smart Compaction: Use /compact to summarize conversation history and free up token space without losing key context.

💾 Session Persistence

  • Auto-Save: Your conversation is automatically saved after each message exchange.
  • Interactive Resume: Use /continue to browse sessions with arrow keys and select one to restore.
  • Visual History: Restored sessions render full conversation with original styling — tool calls, reasoning, markdown responses.
  • Session Storage: Up to 10 sessions stored in .supercoder/sessions/.
  • Compact Integration: When you /compact, the session file is also updated with the summary.

🚀 Getting Started

Installation

From GitHub (recommended):

pip install git+https://github.com/Mage212/supercoder.git

For development (editable mode):

git clone https://github.com/Mage212/supercoder.git
cd supercoder
uv sync --dev
uv run supercoder

First Run — Interactive Setup

On first launch, if no config file or API key is found, SuperCoder automatically starts an interactive setup wizard:

╭──────────────────────────────────────────────────────╮
│ 🚀 SuperCoder Setup                                  │
│ No API key configured. Let's set up your provider!   │
╰──────────────────────────────────────────────────────╯

Choose a provider:
  1. OpenAI           (https://api.openai.com/v1)
  2. OpenRouter       (https://openrouter.ai/api/v1)
  3. Anthropic via OR (https://openrouter.ai/api/v1)
  4. Ollama (local)   (http://localhost:11434/v1)
  5. Custom endpoint

Provider (1): 2
...
✓ Configuration saved to: ~/.supercoder/config.yaml

After saving, the REPL starts immediately — no restart needed.

SuperCoder supports multiple models and endpoints. Configure them via environment variables or a config file.

Configuration files (in order of priority):

  1. Environment variables (highest priority)
  2. .supercoder.yaml in your project directory
  3. ~/.supercoder/config.yaml (global config)

Environment Variables:

export SUPERCODER_API_KEY="sk-..."
export SUPERCODER_MODEL="gpt-4o"
export SUPERCODER_BASE_URL="https://api.openai.com/v1"  # Optional

Custom Endpoints (OpenRouter, Ollama, LM Studio, etc.):

export SUPERCODER_BASE_URL="https://openrouter.ai/api/v1"
export SUPERCODER_API_KEY="sk-or-..."
export SUPERCODER_MODEL="openai/gpt-4o"

Example ~/.supercoder/config.yaml:

# Default model profile to use on startup
default_model: "default"

# Model profiles - define multiple LLM configurations
models:
  default:
    api_key: "sk-..."
    endpoint: "https://api.openai.com/v1"
    model: "gpt-4o-mini"
  
  # OpenRouter with Qwen-style model
  openrouter-qwen:
    api_key: "sk-or-v1-..."
    endpoint: "https://openrouter.ai/api/v1"
    model: "openai/gpt-oss-20b:free"
    tool_calling_type: "qwen_like"  # See Tool Calling Types below
  
  # Local Ollama
  ollama:
    api_key: "ollama"
    endpoint: "http://localhost:11434/v1"
    model: "qwen2.5-coder:7b"
    tool_calling_type: "supercoder"

# Shared settings (applied to all models)
temperature: 0.2
max_context_tokens: 32000
request_timeout: 60.0
debug: false

Tool Calling Types

Different models expect tools to be called in different formats. Use tool_calling_type to specify the format:

Type Format Best for
supercoder (default) <@TOOL>{"name": "...", "arguments": {...}}</@TOOL> Most instruction-following models
qwen_like to=tool:name {"arg": "value"} Qwen, GPT-OSS, DeepResearch models
json_block ```json {"tool": "...", "arguments": {...}} ``` Models trained on markdown
xml_function <function_call name="...">...</function_call> XML-style models
glm_tool_call <tool_call>name<arg_key>k</arg_key><arg_value>v</arg_value></tool_call> GLM-4 models

⌨️ Usage

Launch the interactive REPL:

supercoder

CLI Options

supercoder --help
supercoder --model gpt-4o              # Use specific model or profile name
supercoder --endpoint http://...       # Override LLM API endpoint
supercoder --temperature 0.5           # Override temperature
supercoder --debug                     # Enable debug mode
supercoder --no-repo-map               # Disable RepoMap
supercoder --max-context 16000         # Override context token limit

Slash Commands

Command Description
/ask Switch to Ask mode (Q&A without edits)
/ask <question> Ask one question without editing, then return to previous mode
/code Switch to Code mode (full editing)
/code <request> Execute one request in code mode, then return to previous mode
/undo Revert changes to a specific checkpoint
/help Show available commands
/continue Resume a previous session (interactive picker)
/compact Summarize history to save context tokens
/stats View current token usage and context status
/clear Clear conversation history
/config Show current active configuration
/models List available model profiles
/model <name> Switch to a specific model profile
/debug Toggle verbose debug logging
/exit Exit the application

🛡️ Safety & Integrity

Atomic File Writes

SuperCoder uses an AtomicFileWriter to ensure that files are never left in a corrupted state if a write operation is interrupted. This uses the tempfile + os.replace pattern, which is standard for safe filesystem operations.

Checkpoint System

Every user message that leads to a file modification creates a new Checkpoint.

  • Backups: Stored in project-local .supercoder/checkpoints/.
  • Created Files: Tracked and automatically deleted on rollback.
  • Rotation: Automatically keeps only the last 10 checkpoints to save space.
  • Self-Healing: Incomplete or orphaned checkpoint directories are automatically cleaned on startup.

Command Execution Confirmation

Before running any shell command, SuperCoder pauses and asks for explicit approval:

⚡ Run Command?
Command:
  <the command to execute>
  [y] Yes   [a] Always allow   [n] No

Single keypress response — [a] remembers approval for the rest of the session.

Interruption (ESC-ESC)

Press ESC twice to abort at any time — during generation, tool calls, or streaming.

  1. The keyboard listener detects the interrupt.
  2. The current LLM stream is aborted immediately.
  3. Any partial file changes from the current turn are rolled back automatically.

📁 Project Structure

supercoder/
├── agent/            # CoderAgent logic and prompts
├── context/          # Token counting, context window, and session management
├── llm/              # LLM providers (OpenAI-compatible endpoints)
├── repomap/          # Repository mapping logic (tree-sitter)
├── tools/            # Core tools (Search, Edit, Structure, Exec)
├── rules_loader.py   # Supercoder Rules loading logic
├── config.py         # Configuration management
├── logging.py        # Conversation logging (JSONL → ~/.supercoder/logs/)
├── setup_wizard.py   # Interactive first-run setup wizard
├── repl.py           # Interactive REPL interface
└── main.py           # CLI entry point

📦 Dependencies

Core:

  • openai — LLM API client
  • click — CLI framework
  • rich — Beautiful terminal output
  • prompt-toolkit — Interactive input
  • networkx — Graph-based RepoMap
  • tree-sitter-languages — Code parsing for RepoMap
  • tiktoken — Token counting
  • pyyaml — Configuration files
  • questionary — Interactive terminal prompts

⚖️ License

MIT