booklet.md

enc: the english to anything transpiler

enc is cc for english. it is a powerful tool that transpiles plain english descriptions into functional code in any programming language. by leveraging generative AI, enc allows you to write software by describing its behavior, supporting iterative refinement through automated testing and a self-hosting design.

overview

at its core, enc takes an input file (typically .en) and an output destination. it consults a large language model to generate code that matches your description.

example

if you have hello.en:

hello: output the string "hello, <input>!" based on the user's input
main: call the hello function with the first argv. default to "world"

running enc hello.en -o hello.rs produces a ready-to-compile rust program.

quick start

1. download: grab the latest release for your platform.
2. setup: create a .enc.env file with your api keys (google, anthropic, or openai).
3. configure: run ./enc --show-config to verify settings.
4. transpile:

   $ echo "print the first 10 fibonacci numbers" > fib.en
   $ ./enc fib.en -o fib.py
   $ python fib.py

installation

installation is managed per-user. ensure ~/.local/bin/ is in your PATH.

$ git clone https://github.com/khimaros/enc
$ make install

to remove the program and its resources:

$ make uninstall

configuration

enc uses a layered configuration system where higher priority sources override lower ones:

1. command line flags (highest)
2. environment variables
3. working directory config (./.enc.env)
4. home directory config (~/.enc.env)
5. hardcoded defaults (lowest)

settings and environment variables

setting	environment variable	default / description
PROVIDER	PROVIDER	google (also supports anthropic, openai)
MODEL	MODEL	provider-specific (e.g., gemini-2.5-pro, gpt-4o-mini)
MAX_TOKENS	MAX_TOKENS	maximum tokens for model output
THINKING_BUDGET	THINKING_BUDGET	budget for extended reasoning models (e.g., claude 3.7)
SEED	SEED	integer for deterministic output
HACKING_CONVENTIONS	HACKING_CONVENTIONS	path to style guide (default: ./HACKING.md)
TIMEOUT	TIMEOUT	api request timeout in seconds (default: 1800)
CONTEXT_FILES	CONTEXT_FILES	colon-separated list of files to include in the prompt
*_API_KEY	GEMINI_API_KEY, etc.	api authentication keys
OPENAI_API_BASE	OPENAI_API_BASE	custom endpoint for openai-compatible apis
LOGS_PATH	LOGS_PATH	directory for execution logs (default: ./log/)
RESOURCES_PATH	RESOURCES_PATH	search path for prompt templates and metadata
TEST_COMMAND	TEST_COMMAND	command to run after generation to validate output
TEST_ITERATIONS	TEST_ITERATIONS	retry limit if TEST_COMMAND fails (default: 3)

command line flags

usage: enc <INPUT_FILE> -o <OUTPUT_FILE> [OPTIONS]

flag	description
-o, --output	required. the path for the generated source code
--provider	set the ai provider
--model	set the specific model
--test-command	specify a command to validate the output
--test-iterations	number of refinement attempts (use -1 for infinite)
--context-files	additional files to provide to the llm
--show-config	prints the final redacted configuration and exits
--hacking-conventions	path to a style guide file

makefile targets

the provided Makefile handles building, installation, and self-hosting tasks.

target	description
default	alias for build-release
install	installs the rust release binary to ~/.local/bin/enc
install-rust-release	builds and installs the rust edition
install-python	installs the python edition and required resources
install-cpp	installs the c++ edition
install-resources	installs templates, pricing, and language maps to XDG_DATA_HOME
uninstall	removes binary and shared resource files
build	compiles all editions (rust, cpp, python, typescript)
build-release	compiles the rust edition in release mode
clean	deletes build artifacts, caches, and temporary test files
transpile-rust	uses enc to regenerate src/enc.rs from src/enc.en
transpile-python	uses enc to regenerate src/enc.py from src/enc.en
test	runs the standard test suite for the rust edition
test-rust	runs tests against the rust binary
test-python	runs tests against the python edition
precommit	alias for test
bootstrap-python	creates the initial python version using enc.bootstrap.py
bootstrap-rust	creates the initial rust version using enc.bootstrap.py
hello	runs a complete end-to-end test using the google provider
docs	generates icons, booklets, and terminal casts

overall design

enc is designed to be a transparent, iterative pipeline between human language and machine code.

the transpilation loop

1. context gathering: enc reads the input .en file, any CONTEXT_FILES, and the HACKING_CONVENTIONS.
2. prompt expansion: it populates a template (res/prompt.tmpl) with this data, including the target language name identified via res/languages.json.
3. api execution: it calls the selected provider (google, anthropic, or openai). it supports streaming for real-time feedback and handles provider-specific nuances like thinking tokens and seed support.
4. validation: the response is stripped of markdown fences. if the output is empty, it errors out.
5. iterative refinement: if a TEST_COMMAND is provided, enc runs it. if it fails, the stdout/stderr and the failed code are sent back to the llm for a "bug fix" iteration. this continues until success or the iteration limit.
6. reporting: after completion, a detailed summary of tokens used, estimated costs (based on res/pricing.json), and elapsed time is displayed.

self-hosting and editions

enc is self-hosting. the logic is defined in src/enc.en.

• the bootstrap edition (src/enc.bootstrap.py) was created using aider.
• the production editions (rust, python, etc.) are generated by running enc (or the bootstrap version) on src/enc.en.

security and safety

• api keys are redacted in all logs and console output.
• test commands are executed in a restricted environment whitelisting only essential variables like PATH, RUSTUP_HOME, and CARGO_HOME.
• logs are timestamped and stored in a dedicated directory for debugging failed generations.