bara-lang/README.md

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.

AI-Powered Assistance

Clojure/Nim can use paid AI APIs (DeepSeek, OpenAI, Xiaomi MiMo) to help you write and debug code.

Setup

Set one of these environment variables:

# DeepSeek (recommended, fast & cheap)
export DEEPSEEK_API_KEY="sk-..."

# OpenAI / OpenRouter
export OPENAI_API_KEY="sk-..."

# Xiaomi MiMo
export MIMO_API_KEY="..."

Features

Auto-error explanation — When compilation fails, the compiler automatically asks AI for a fix:

$ ./cljnim run broken.clj
Compilation failed
Error: type mismatch: got <int> but expected <string>
💡 AI Suggestion:
   The function `greet` expects a string but you passed an integer.
   Fix: (defn greet [name] (str "Hello " name))

REPL AI command — Generate code interactively:

$ ./cljnim repl
user> :ai function that calculates fibonacci using loop/recur
🤖 Thinking...
💡 AI Suggestion:
   (defn fib [n]
     (loop [a 0 b 1 i n]
       (if (= i 0)
         a
         (recur b (+ a b) (dec i)))))

CLI code generation — Generate code from terminal:

$ ./cljnim ai "function that reads a file line by line"
(defn read-lines [filename]
  (let [content (slurp filename)]
    (clojure.string/split-lines content)))

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
│   ├── eval.nim         # Tree-walking interpreter
│   ├── deps.nim         # Dependency resolution
│   ├── core.nim         # Core runtime functions
│   ├── types.nim        # Clojure value types
│   ├── macros.nim       # Macro expansion engine
│   └── runtime.nim      # Runtime implementation
├── lib/
│   ├── cljnim_runtime.nim   # Clojure runtime in Nim
│   ├── cljnim_pvec.nim      # Persistent Vector (HAMT)
│   ├── cljnim_pmap.nim      # Persistent Map (HAMT)
│   └── cljnim_async.nim     # core.async channels
├── examples/
│   ├── hello.clj
│   ├── math.clj
│   ├── core.clj
│   ├── macros.clj
│   ├── ffi.clj
│   ├── interop.clj
│   └── ai_tools.clj
├── docs/                    # Documentation (EN + BG)
├── tests/
├── Makefile
└── cljnim.nimble

Supported Features

Working Now ✅

• Reader: numbers, strings, symbols, keywords, lists (), vectors [], maps {}
• Special forms: def, defn, fn, let, if, do, quote
• Arithmetic: +, -, *, /, =, <, >
• Functions: println, map, filter, reduce
• Human REPL and JSON REPL
• AOT compilation to native binaries
• Persistent data structures (Vector, Map, Set) via HAMT
• Macro system (defmacro, ->, ->>, and, or, when, cond)
• Nim/C interop
• File and Git operations from REPL
• Tree-walking interpreter for fast REPL eval
• Atoms, Agents, and core.async channels

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.

Acknowledgments

• Clojure — Rich Hickey and team
• Nim — Andreas Rumpf and community
• Inspired by ClojureScript, Babashka, Ferret, and Pixie