Clojure/Nim
A Clojure dialect that compiles to Nim, then to C, then to native binaries.
What is this?
Clojure/Nim is an AI-first implementation of the Clojure language targeting the Nim ecosystem. Instead of running on the JVM or JavaScript, it compiles Clojure code directly to Nim source, which then compiles to C and finally to a native binary.
Why?
- Native Performance: Compiles to C via Nim. No JVM warmup, no GC pauses.
- Tiny Binaries: Single-file executables, often under 1MB.
- Nim Ecosystem: Direct access to Nim and C libraries via FFI.
- AI-Native: Built for AI agents working in terminals — structured JSON REPL, batch evaluation, git integration.
Quick Start
# Clone
git clone https://gitlab.com/balvatar/lisp-nim.git
cd lisp-nim
# Build
make build
# Run a file
./cljnim run examples/hello.clj
# Start human REPL
./cljnim repl
# Start AI REPL (JSON mode)
./cljnim repl --json
Examples
Hello World
;; examples/hello.clj
(println "Hello, Nim world!")
(println (+ 1 2 3))
$ ./cljnim run examples/hello.clj
Hello, Nim world!
6
Functions & Recursion
;; examples/math.clj
(defn square [x]
(* x x))
(defn factorial [n]
(if (= n 0)
1
(* n (factorial (- n 1)))))
(let [a 5]
(println (square a))
(println (factorial a)))
$ ./cljnim run examples/math.clj
25
120
AI-First REPL
Clojure/Nim is built for AI agents. The JSON REPL provides structured I/O perfect for programmatic interaction.
$ ./cljnim repl --json
{"status":"ready","ns":"user","mode":"json"}
> {"op":"eval","form":"(+ 1 2 3)"}
{"status":"ok","result":{"printed":"6"},"meta":{"ms":861}}
> {"op":"eval","form":"(defn square [x] (* x x))"}
{"status":"ok","result":{"type":"var","name":"square"}}
> {"op":"eval","form":"(square 5)"}
{"status":"ok","result":{"printed":"25"}}
> {"op":"quit"}
{"status":"ok","bye":true}
Supported REPL Operations
| Operation | Description |
|---|---|
eval |
Evaluate a single Clojure form |
eval-batch |
Evaluate multiple forms at once |
get-defs |
List all defined vars in current session |
clear |
Clear all session definitions |
quit |
Exit the REPL |
See docs/AI_FIRST.md for the full AI integration design.
Architecture
Clojure Source (.clj)
↓
Reader (EDN parser)
↓
Macro Expansion (Clojure macros)
↓
Analyzer (special forms, locals)
↓
Emitter (Clojure AST → Nim AST)
↓
Nim Compiler → C Code
↓
C Compiler → Native Binary
See docs/ARCHITECTURE.md for details.
Project Structure
├── src/
│ ├── cljnim.nim # CLI entry point
│ ├── reader.nim # Clojure reader / EDN parser
│ ├── emitter.nim # Nim code generator
│ ├── repl.nim # Human & AI REPL
│ ├── types.nim # Clojure value types
│ ├── macros.nim # Macro expansion engine
│ └── runtime.nim # Runtime implementation
├── lib/
│ └── cljnim_runtime.nim # Clojure runtime in Nim
├── examples/
│ ├── hello.clj
│ └── math.clj
├── docs/ # Documentation (EN + BG)
├── tests/
├── Makefile
└── cljnim.nimble
Supported Features
Working Now ✅
- Reader: numbers, strings, symbols, keywords, lists
(), vectors[] - Special forms:
def,defn,fn,let,if,do,quote - Arithmetic:
+,-,*,/,=,<,> - Functions:
println - Human REPL and JSON REPL
- AOT compilation to native binaries
In Progress 🔄
- Persistent data structures (Vector, Map, Set)
defmacrosystem- Nim/C interop
- File operations from REPL
- Git operations from REPL
See docs/ROADMAP.md for the full roadmap.
Requirements
- Nim >= 2.0
- GCC or Clang
- make
Documentation
| Document | Description |
|---|---|
docs/README.bg.md |
Българско README |
docs/GUIDE.md |
User guide (English) |
docs/GUIDE.bg.md |
Ръководство за потребителя |
docs/ARCHITECTURE.md |
Architecture & design |
docs/ARCHITECTURE.bg.md |
Архитектура и дизайн |
docs/AI_FIRST.md |
AI-first design philosophy |
docs/AI_FIRST.bg.md |
AI-first философия |
docs/API.md |
REPL API reference |
docs/API.bg.md |
REPL API референция |
docs/ROADMAP.md |
Development roadmap |
docs/ROADMAP.bg.md |
Пътна карта |
License
MIT License — see LICENSE.