supercode-cli 0.2.0

SuperCode: explicit-hole AI implementation generator and minimal super frontend

SuperCode

SuperCode is an experimental deterministic glue frontend for compilers, interpreters, generated implementations, and cross-language bindings, with optional AI hole filling.

super is the glue. The LLM only fills missing holes.

SuperCode does not rewrite your source code. It tracks explicit super_func, super_export_func, super_import_func, super_struct, super_class, sc.super_func, and sc.import_func forms, resolves existing implementations first, and only asks an implementation provider when something is missing.

Stable syntax and command semantics are documented in docs/syntax.md.

Warning

• SuperCode is experimental.
• It calls an LLM.
• It generates code.
• Generated code may be wrong.
• Inspect .supercode/impl before trusting generated code.
• Do not use SuperCode for production, security-critical, financial, safety-critical, or unreviewed code paths.

How It Works

SuperCode has two separate layers:

• Deterministic core: scan, resolve, reuse, build, link, import, run, inspect, and verify.
• Implementation providers: LLM, mock, handwritten, generated, or external implementations.

The default rule is simple: existing implementations are reused. Missing implementations may be generated. --offline forbids generation and fails clearly when an implementation is missing.

Installation

Arch Linux:

yay -S python-supercode-cli-git

Linux / macOS:

uv tool install supercode-cli

Alternative:

pipx install supercode-cli

If you know exactly how you want to manage your Python environment, you can also install with pip, but uv tool install / pipx / AUR are the recommended user-facing paths.

Verify:

super --help
super init

Names:

• PyPI distribution name: supercode-cli
• AUR package name: python-supercode-cli-git
• CLI command: super
• Python import name: supercode
• C header: supercode.h
• C++ header: supercode.hpp

Quick Start

super init
export OPENROUTER_API_KEY="your_api_key_here"
# edit supercode.toml if needed
super examples/c_local_func/main.c -o /tmp/sc-local
/tmp/sc-local
super inspect

No-AI / Offline Glue

AI is not required when implementations already exist or are handwritten and registered.

super build examples/no_ai/c_export/main.c -o /tmp/sc-c --offline
/tmp/sc-c

super build examples/no_ai/cpp_import/main.cpp -o /tmp/sc-cpp --offline
/tmp/sc-cpp

super build examples/no_ai/python_import/main.py --offline

These examples use a handwritten C implementation registered in examples/no_ai/supercode.toml. The same export is called from C, C++, and Python without an API key, without --mock, and without runtime LLM calls.

Use super verify and super inspect to audit resolved implementations:

super verify examples/no_ai/c_export/main.c
super inspect

LLM Configuration

SuperCode reads LLM settings from supercode.toml.

• Do not put a raw API key into supercode.toml.
• api_key_env is the name of an environment variable, not the key itself.
• Put the actual key into your shell environment.

OpenRouter + DeepSeek example:

[llm]
provider = "openai-compatible"
base_url = "https://openrouter.ai/api/v1"
api_key_env = "OPENROUTER_API_KEY"
model = "deepseek/deepseek-v4-pro"
temperature = 0.1

export OPENROUTER_API_KEY="your_api_key_here"

DeepSeek direct example:

[llm]
provider = "openai-compatible"
base_url = "https://api.deepseek.com"
api_key_env = "DEEPSEEK_API_KEY"
model = "deepseek-v4-flash"
temperature = 0.1

export DEEPSEEK_API_KEY="your_api_key_here"

The model field is user-configurable. Change it to match the provider and model you want to use.

Minimal LLM Config Change

If you only want to change the key, change the environment variable value:

export OPENROUTER_API_KEY="new_key_here"

If you want to switch providers, only change these four fields in supercode.toml:

• provider
• base_url
• api_key_env
• model

Example:

[llm]
provider = "openai-compatible"
base_url = "https://your-provider.example/v1"
api_key_env = "YOUR_PROVIDER_API_KEY"
model = "your/model-name"

export YOUR_PROVIDER_API_KEY="your_key_here"

Mock Mode

• --mock does not call an LLM.
• --mock does not validate AI generation quality.
• --mock only validates scanner/emitter/build plumbing.
• Real SuperCode behavior requires a real LLM backend.

Example:

super examples/c_local_func/main.c -o /tmp/sc-local --mock

C Local super_func

#include <stdio.h>
#include <supercode.h>

int mode_min_tie(const int *a, int n) {
    // Return the most frequent element; if there is a tie, return the smallest value.
    return super_func(int, a, n);
}

int main(void) {
    int a[] = {3, 1, 3, 1, 1};
    printf("%d\n", mode_min_tie(a, 5));
    return 0;
}

• User source is not rewritten.
• .supercode/impl contains only the generated helper implementation.
• It does not contain a copy of the full source file.

C super_export_func and Python Binding

super_export_func(mode_min_tie, int, const int *a, int n);

This generates:

• a C implementation
• a shared library
• a Python ctypes binding

Python usage:

from supercode_generated import mode_min_tie

print(mode_min_tie([3, 1, 3, 1, 1]))

C super_struct

// An int dynamic array with create, destroy, push, get, and size operations.
super_struct(IntVec);

• super_struct(IntVec) generates an opaque C API.
• The struct layout lives in .supercode/impl.
• The user only sees declarations.

C++ super_class

#include <iostream>
#include <supercode.hpp>

// A fixed-capacity LRU cache with int keys and double values.
super_class(LRUCache);

int main() {
    LRUCache c(2);
    c.put(1, 3.14);
    std::cout << c.get(1) << "\n";
}

• The generated C++ class uses a PImpl-style implementation.
• User source is not rewritten.

Python Local sc.super_func

import supercode as sc

def mode_min_tie(a: list[int]) -> int:
    # Return the most frequent element; if there is a tie, return the smallest value.
    return sc.super_func(int, a)

print(mode_min_tie([3, 1, 3, 1, 1]))

• Run Python SuperCode source files with super file.py.
• Plain python file.py will fail unless a generated registry already exists.
• Runtime dispatch does not call the LLM.

IDE Support

super init

This generates:

• supercode.toml
• .clangd
• pyrightconfig.json
• .supercode/include/supercode_ide.h

Notes:

• Run super init --force if you have older generated config files.
• Restart clangd / pyright after super init --force.
• .clangd uses packaged include paths.
• pyrightconfig.json adds runtime and generated paths.

IDE Troubleshooting

If clangd still reports supercode.h file not found, Type specifier, or undeclared function:

1. Re-run:

super init --force

2. Restart clangd / your LSP client.

3. Confirm that .clangd uses absolute packaged include paths.

4. For Python IDE support, confirm that pyrightconfig.json contains:

   • .
   • .supercode/bindings/python
   • .supercode/py_impl
   • the SuperCode runtime package path

5. If Python still reports import not found, restart pyright / basedpyright / your Python LSP.

6. Validate syntax directly:

clang -fsyntax-only \
  -I"$PWD/include" \
  -I"$PWD/.supercode/include" \
  -DSUPERCODE_IDE=1 \
  -include "$PWD/.supercode/include/supercode_ide.h" \
  examples/c_export_func/main.c

clang++ -std=c++17 -fsyntax-only \
  -I"$PWD/include" \
  -I"$PWD/.supercode/include" \
  -DSUPERCODE_IDE=1 \
  -include "$PWD/.supercode/include/supercode_ide.h" \
  examples/cpp_class/main.cpp

What SuperCode Does Not Do

• It does not require an LLM when a matching handwritten or generated implementation already exists.
• It does not rewrite source files.
• It does not copy full source files into .supercode.
• It does not fix syntax errors.
• It does not make bare gcc, g++, or python understand SuperCode holes.
• Use super, not bare compilers/interpreters, for files containing SuperCode holes.
• It is not a production compiler.

Current Support Matrix

Supported:

• C local super_func
• C super_export_func
• C super_struct
• C++ super_class
• Python local sc.super_func
• Python ctypes binding for exported C functions
• C/C++ super_import_func for registered exports
• Python sc.import_func for registered exports
• no-AI offline C/C++/Python glue examples
• super build, super generate, and super verify
• clangd / pyright initialization through super init

Not yet supported or still experimental:

• CUDA
• Rust
• Java
• full supermake
• complex multi-file projects
• complex C/C++ macros/templates
• production use

Boundaries

• SuperCode does not modify user source files.
• SuperCode does not copy full source files into .supercode.
• .supercode/impl contains generated implementation units only.
• super init does not call an LLM and does not generate implementations.
• The manifest stores locations, hashes, generated symbols, and generated file paths, not raw source lines.
• Generated implementations do not include user source files.
• Generated implementations do not copy user wrapper functions.
• AI generation is limited to explicit holes.

Super-Fusion Status

super is supposed to glue every language into one cursed toolchain.

Language / Runtime	Super-fused
C	✅
Python	✅
C++	✅ partial
Rust	❌
Java	❌
JavaScript	❌
TypeScript	❌
Go	❌
Zig	❌
Swift	❌
Kotlin	❌
Scala	❌
C#	❌
F#	❌
Objective-C	❌
Objective-C++	❌
CUDA	❌
HIP	❌
OpenCL C	❌
SYCL	❌
Metal Shading Language	❌
GLSL	❌
HLSL	❌
WGSL	❌
ISPC	❌
Fortran	❌
Julia	❌
R	❌
MATLAB	❌
Octave	❌
Mathematica / Wolfram Language	❌
Maple	❌
SageMath	❌
Scilab	❌
Maxima	❌
LINGO	❌
GAMS	❌
AMPL	❌
MiniZinc	❌
Modelica	❌
Simulink	❌
LabVIEW	❌
SQL	❌
PL/pgSQL	❌
T-SQL	❌
PL/SQL	❌
MySQL Stored Programs	❌
SQLite SQL	❌
SPARQL	❌
Cypher	❌
Datalog	❌
Prolog	❌
Mercury	❌
Erlang	❌
Elixir	❌
Gleam	❌
Haskell	❌
OCaml	❌
Standard ML	❌
F*	❌
Coq / Gallina	❌
Lean	❌
Agda	❌
Idris	❌
Futhark	❌
Elm	❌
PureScript	❌
ReasonML	❌
ReScript	❌
Clojure	❌
Common Lisp	❌
Scheme	❌
Racket	❌
Guile	❌
Emacs Lisp	❌
AutoLISP	❌
Lua	❌
Ruby	❌
PHP	❌
Perl	❌
Raku	❌
Tcl	❌
Groovy	❌
Dart	❌
CoffeeScript	❌
LiveScript	❌
JSX	❌
TSX	❌
WebAssembly	❌
WebAssembly Text / WAT	❌
Bash	❌
Zsh	❌
Fish	❌
POSIX sh	❌
PowerShell	❌
Batch / CMD	❌
VBScript	❌
AppleScript	❌
AutoHotkey	❌
Make	❌
CMake	❌
Meson DSL	❌
Bazel Starlark	❌
Ninja	❌
Dockerfile	❌
HCL / Terraform	❌
Nix	❌
Dhall	❌
Jsonnet	❌
YAML	❌
TOML	❌
JSON	❌
XML	❌
HTML	❌
CSS	❌
Sass / SCSS	❌
Less	❌
Regex	❌
AWK	❌
sed	❌
M4	❌
Vala	❌
Nim	❌
Crystal	❌
D	❌
V	❌
Odin	❌
Jai	❌
Carbon	❌
Mojo	❌
Chapel	❌
Pony	❌
Red	❌
Ring	❌
Hack	❌
Haxe	❌
Fantom	❌
Eiffel	❌
Ada	❌
SPARK	❌
Pascal	❌
Delphi / Object Pascal	❌
Free Pascal	❌
Modula-2	❌
Modula-3	❌
Oberon	❌
BASIC	❌
Visual Basic	❌
VB.NET	❌
QBasic	❌
FreeBASIC	❌
COBOL	❌
RPG	❌
JCL	❌
AdaScript	❌
Assembly	❌
x86 Assembly	❌
ARM Assembly	❌
RISC-V Assembly	❌
LLVM IR	❌
MLIR	❌
Verilog	❌
SystemVerilog	❌
VHDL	❌
Chisel	❌
Bluespec	❌
FIRRTL	❌
Q#	❌
OpenQASM	❌
Cirq	❌
Qiskit circuits	❌
Solidity	❌
Vyper	❌
Move	❌
Cairo	❌
Michelson	❌
Clarity	❌
Plutus	❌
DAML	❌
TeX	❌
LaTeX	❌
BibTeX	❌
Typst	❌
Markdown	❌
reStructuredText	❌
AsciiDoc	❌
Graphviz DOT	❌
Mermaid	❌
PlantUML	❌
G-code	❌
PostScript	❌
Processing	❌
Arduino	❌
Scratch	❌
Blockly	❌
Logo	❌
Smalltalk	❌
Self	❌
Io	❌
Forth	❌
Factor	❌
APL	❌
J	❌
K	❌
Q / KDB+	❌
BQN	❌
Uiua	❌
Excel formulas	❌
Google Sheets formulas	❌
SAS	❌
Stata	❌
SPSS Syntax	❌
ABAP	❌
Apex	❌
PeopleCode	❌
Progress OpenEdge ABL	❌
ColdFusion Markup Language	❌
ActionScript	❌
UnrealScript	❌
GDScript	❌
AngelScript	❌
Squirrel	❌
Ren'Py	❌
Ink	❌
Inform 7	❌
LLVM TableGen	❌
ANTLR grammar	❌
Tree-sitter grammar	❌
Yacc / Bison	❌
Lex / Flex	❌
Brainfuck	❌
Ook!	❌
Befunge	❌
Piet	❌
Whitespace	❌
INTERCAL	❌
LOLCODE	❌
Shakespeare Programming Language	❌
ArnoldC	❌
Chef	❌
Malbolge	❌
SuperLang, a custom Turing-complete language that does not exist	❌