SESI IS NOT AN AI WRAPPER LANGUAGE. IT IS NOT AN AI-NATIVE PROGRAMMING LANGUAGE. IT IS A GENERAL-PURPOSE PROGRAMMING LANGUAGE WITH OPTIONAL AI CAPABILITIES BUILT-IN. STRONG EMPHASIS ON OPTIONAL.

Pronounced "say-see" — What you say, you'll see.

Sesi is a clean, minimal, and highly legible programming language. Built from the ground up to be concise and buildable, Sesi removes unnecessary boilerplate. It is a language built for clarity.

Homepage

✨ New: Sesi Studio IDE

We are excited to announce the release of Sesi Studio, a high-performance, browser-based IDE built specifically for Sesi developers. It combines the power of VS Code's editor with deep native integration for the Sesi toolchain.

• Pro Editor Features: Bracket pair colorization, document symbols, and go-to-definition.
• Integrated Terminal: Run Sesi scripts and manage your system directly from the IDE.
• Sesira Assistant: Context-aware chat assistant that understands your codebase.
• Local Timeline: Never lose code with built-in edit history.
• Command Palette: Access all workspace operations, extension actions, zoom controls, and theme settings with a single keystroke (Cmd/Ctrl+P).
• Extension & Theme Packagers & Installers: Pack CSS themes into portable .sesitheme bundles and JS extensions into .sesiext bundles. Validate, distribute, and install themes/extensions dynamically via the Settings Hub or Command Palette.

To launch Sesi Studio, you can:

• Open Sesi Studio.app (macOS) / Sesi Studio.exe / (Windows)
• Use the CLI: sesi -s from any project directory after installing Sesi. The installer includes the Studio runtime and opens that directory as the initial workspace.

Installation

You can install Sesi in three ways:

1. Global Installation via npm (Recommended)

If you have Node.js installed, download Sesi directly from the npm registry:

npm install -g sesi

2. Standalone Executables

Don't want to install Node.js? Download the standalone executables bundled for Windows, Mac, and Linux directly from our Downloads page. Drop the executable in your system PATH and you're good to go!

For macOS users, Sesi also supports a native PKG installer flow when building from source:

npm run build:mac:installer

This generates installer packages in releases/ (for available architectures) that install sesi to /usr/local/bin.

3. Build from Source (For contributors)

git clone https://github.com/Misterscan/Sesi.git
cd Sesi
npm install
npm run build
npm install -g .  # Unlock the `sesi` command locally

Quick Start

Provider-backed reasoning needs an API key. Local reasoning with

model("local") needs no API key. To use Gemini, create

a .env file referencing your key where you run your scripts:

GEMINI_API_KEY="AIzaSy..."
OPENAI_API_KEY="sk-......"

Then run any program directly:

# Standard script execution
sesi examples/main/01_hello.sesi

# Run script with arguments
sesi main/tests/test_args.sesi arg1 arg2

# Reasoning script example
sesi examples/optional/08_model_call.sesi

# Python-free local model (downloads weights on first use)
sesi local_ai.sesi "Say hello."

# Run all examples
sesi examples.sesi

Useful CLI shortcuts:

# Evaluate a quick snippet
sesi -e "show 'hello'"

# Ask the built-in Sesira assistant a question
sesi -h "how do I use memory?"

# Ask Sesira for help about a specific file
sesi chatbot/sesira.sesi examples/main/01_hello.sesi "what is this script doing?"

# Start a new chat
sesi chatbot/sesira.sesi new "how do I create an HTML?"

# Encrypt or decrypt a script file manually
sesi -enc my_script.sesi -p "my-password"
sesi -dec my_script.sesi -p "my-password"

To avoid exposing passwords in your shell's history, you can set the SESI_PASSWORD environment variable in your .env file (or your system's shell environment).

export SESI_PASSWORD="my-password"
# Encrypt or decrypt automatically using SESI_PASSWORD environment variable
sesi -enc my_script.sesi
sesi -dec my_script.sesi

# Install third-party package dependency
sesi install owner/repo#ref

# Install all dependencies declared in sesi.json
sesi install

# Run with sandbox restrictions disabled
sesi examples/main/01_hello.sesi -l

Local Execution (Development)

If you are developing inside the repository or haven't installed sesi globally, use the npm scripts:

# Run a Sesi script
npm run sesi examples/main/01_hello.sesi

# Evaluate an inline snippet
npm run sesi:eval "show 'Sesi running!'"

# Ask Sesi's Sesira assistant
npm run sesira "how to make a directory?"

# Encrypt / Decrypt scripts (uses SESI_PASSWORD from your .env automatically)
npm run sesi:encrypt "secret.sesi"
npm run sesi:decrypt "secret.sesi"

# Sesi Studio Theme Packager
npm run studio:css:pack <css-file-path> [output-dir]
npm run studio:css:unpack <sesitheme-file-path> [output-dir]
npm run studio:css:validate <css-file-path>

# Sesi Studio Extension Packager
npm run studio:ext:pack <js-file-path> [output-dir]
npm run studio:ext:unpack <sesiext-file-path> [output-dir]
npm run studio:ext:validate <js-file-path>

# Run classic examples
npm run example examples/main/01_hello.sesi
npm run example:ai examples/optional/08_model_call.sesi
npm run examples

📦 Package Management

Sesi has a native, git-centric package manager. You can install third-party libraries directly from GitHub into a local sesi_modules/ folder and import them cleanly.

• Install a library: sesi install owner/repo (adds it to your local sesi.json and downloads it).
• Restore dependencies: sesi install (installs all dependencies declared in your local sesi.json).

Language Overview

Sesi is designed for developers who want to:

• Write normal code (variables, functions, loops, etc.)
• Call Reasoning directly within code using prompt and model blocks
• Get structured outputs from Reasoning with type guarantees
• Build Reasoning agents with memory and multi-step reasoning
• Maintain full control and transparency

Example

// Basic computation
let x = 10
let y = 20
let result = x + y
show result // 30

// Reasoning-powered code generation
prompt generateCode {"Write a TypeScript function that reverses a string"}
let code = model("gemini-3.1-pro-preview") {generateCode}
show code

Security & Sandboxing

Sesi incorporates a safe-by-default, zero-trust sandboxing engine.

🛡️ Core Security Features

1. Safe-by-Default Execution:

- Sesi's sandbox is enabled by default. Any standard Sesi interpreter execution blocks system command lines (exec, spawn) and locks down imports and paths.

- Overriding Safety: Developers can explicitly bypass safe mode programmatically by initializing the interpreter with options, using the -l flag when running the sesi executable, or in the .env file by setting SESI_SAFE_MODE=false.

1. Absolute Prototype Pollution Immunity:

- Sesi uses prototype-free objects (Object.create(null)) for all object literals, JSON parses (from_json), and structured model responses inside the interpreter.

- Because these objects do not inherit from standard JavaScript prototypes and possess no <em></em>proto<em></em> or prototype chain, prototype pollution is physically and architecturally impossible.

1. Strict Path Whitelisting:

- Sesi validates all filesystem and subprocess paths against a strict directory whitelist (by default, only the Current Working Directory and the Script's base directory are allowed).

- Any path traversal resolving outside the whitelist is instantly rejected with a Security Violation exception.

1. Automated LLM Tool Call Sanitization:

- Even if safe mode is explicitly turned off for developer automation, Sesi strictly blocks automated tool execution of sensitive commands (like exec and spawn) when requested dynamically by the model via tool_call. This completely isolates the host from prompt-injection RCE.

1. Deep isolation & Map Cloning:

- Sub-interpreters loaded via concurrent workflows (multi_req) are fully isolated. Sesi deep-clones prompts and memories, preventing concurrent agent tasks from leaking state or polluting each other.

⚙️ Programmatic Embedding Configurations

When embedding Sesi inside a host application, you can statically configure safety settings directly in code:

const interpreter = new Interpreter(scriptDir, {
  safeMode: true, // Enable full sandbox limits (on by default)
  allowLocalFs: false, // Block directory escapes (on by default)
  allowedPaths: ["/var/tmp/sandbox"], // Custom strict whitelist directories
});

Documentation

• Getting Started
• Examples
• Tutorial: Writing Scripts
• CLI Reference
• Language Specification
• Language Comparison Showcase
• Built-in Functions
• Reasoning
• Runtime Architecture

Agent Context

The root-level SKILLS.md file is a workspace context file for AI agents.

Project Structure

Sesi/
├── SKILLS.md                        # Workspace context and repo guardrails
├── eslint.config.mjs                # ESLint configuration
├── example.js                       # Helper script to run basic examples
├── example-ai.js                    # Helper script to run reasoning examples
├── examples.sesi                    # Central execution suite for examples
├── README.md                        # Project overview
├── QUICKSTART.md                    # Getting started guide
├── package.json                     # Dependencies & scripts
├── tsconfig.json                    # TypeScript configuration
├── dist/                            # Compiled TypeScript output
│
├── src/                             # Source code
│   ├── types.ts                     # Type definitions & AST nodes (400+ lines)
│   ├── lexer.ts                     # Tokenization (350+ lines)
│   ├── parser.ts                    # Recursive descent parser (700+ lines)
│   ├── compiler.ts                  # AST → Bytecode compiler
│   ├── chunk.ts                     # Bytecode Chunk & OpCode definitions
│   ├── vm.ts                        # Bytecode virtual machine
│   ├── interpreter.ts               # Tree-walking interpreter (fallback, 600+ lines)
│   ├── builtins.ts                  # Built-in functions (250+ lines)
│   ├── ai-runtime.ts                # Integrated reasoning integration (120+ lines)
│   └── index.ts                     # Entry point (30+ lines)
│
├── bin/
│   └── sesi.js                      # CLI executable
│
├── main/                            # Playgrounds & debugging
│   └── tests/                       # Additional syntax validation scripts
│
├── docs/
│   ├── CLI.md                       # Comprehensive CLI & Parametric Eval guide
│   ├── SPECIFICATION.md             # Complete language spec (600+ lines)
│   ├── ARCHITECTURE.md              # Runtime & system design (400+ lines)
│   ├── BUILTINS.md                  # Built-in functions reference (450+ lines)
│   ├── COMPARISON.md                # Language comparison showcase
│   ├── IMAGE_GENERATION.md          # Image generation guide (>100 lines)
│   ├── REASONING.md                 # Reasoning and simple logic guide (>500 lines)
│   └── ROADMAP.md                   # V2-V4+ development plan (400+ lines)
│
│
├── examples/
│   ├── main/                        # Core language & systems feature examples
│   │   ├── 01_hello.sesi            # Hello World
│   │   ├── 02_variables.sesi        # Variables & operations
│   │   ├── 03_functions.sesi        # Functions with parameters
│   │   ├── 04_conditionals.sesi     # If/else control flow
│   │   ├── 05_loops.sesi            # While, for, for-in loops
│   │   ├── 06_arrays_objects.sesi   # Collections
│   │   ├── 07_prompts.sesi          # Prompt blocks composition
│   │   ├── 09_structured_output.sesi # Type-safe reasoning responses
│   │   ├── 11_memory_storage.sesi   # Multi-turn stateful reasoning
│   │   ├── 12_classification.sesi   # Systems classification loop
│   │   ├── 13_data_pipeline.sesi    # Complete systems pipeline with lazy summaries
│   │   ├── 16_modules.sesi          # Modules & standard library imports
│   │   ├── 17_http_client.sesi      # Native HTTP client (web_get/web_send)
│   │   ├── 18_parallel_requests.sesi # Parallel request concurrency with profiling
│   │   ├── 19_search_web.sesi       # Built-in search_web integration
│   │   ├── 21_custom_tools.sesi     # Declaring and using custom tools
│   │   ├── 23_file_conversion.sesi  # File and format conversions
│   │   ├── 24_http_handler.sesi     # Native HTTP server request routing
│   │   ├── 24_http_server.sesi      # Non-blocking native HTTP server
│   │   ├── 25_webpage_server.sesi   # Native webpage hosting
│   │   ├── 26_database.sesi         # Embedded document database operations
│   │   ├── 27_robust_web_db.sesi    # Dynamic database-backed web analytics
│   │   ├── 29_tool_piping.sesi      # Functional piping operator (|)
│   │   ├── 30_error_recovery.sesi   # Error retry, backoff, and timeout handling
│   │   ├── 31_synthesizer.sesi      # Sound/music synthesis & SVG drawing
│   │   ├── 32_browser_automation.sesi # Headless browser automation with Playwright
│   │   ├── 33_base64.sesi           # Base64 encoding and string encryption
│   │   ├── 34_sesi_api.sesi         # SwaggerUI API setup
│   │   ├── 35_speech_language.sesi  # Speech and language helpers
│   │   └── 36_regex_media.sesi     # Regex and media processing
│   │
│   └── optional/                    # Optional reasoning & advanced AI examples
│       ├── 08_model_call.sesi       # Basic reasoning model calls
│       ├── 10_code_generation.sesi  # Code generation logic
│       ├── 14_folder_explainer.sesi # Workspace directory analyzer
│       ├── 15_image_generation.sesi # Image generation API
│       ├── 20_model_aliases.sesi    # Custom model naming aliases
│       ├── 22_reasoning_plus_custom_tools.sesi # Reasoning composed with custom tools
│       ├── 28_streaming.sesi        # Real-time response streaming
│       └── 37_ai_video_generation.sesi # AI video generation workflow
│
└── tests/                           # Engine test suite
    ├── basic.test.ts                # Core parsing & evaluation tests
    ├── cache.test.ts                # Execution caching tests
    ├── http.test.ts                 # Web request builtins testing
    ├── module.test.ts               # Imports & module loading tests
    ├── parallel.test.ts             # Concurrent execution tests
    ├── security.test.ts             # Sandbox & guardrail tests
    ├── test-gemini.ts               # Base model integration test
    ├── test-gemini2.ts              # Extended model integration test
    └── workflow.test.ts             # Complex sequence workflows tests

Features

Core Language ✅

• Variables & Bindings: let for all bindings; const is not supported.
• Functions: Side-effect driven functions with typed parameters.
• Control Flow: if/else, while, for, and try/catch.
• Collections: Robust Arrays and Objects.
• Error Handling: Structured try/catch for both runtime and Reasoning-level errors.
• Local Module Imports/Exports: Import custom local .sesi modules cleanly using relative import/export syntax!
• Standard Library Modules: Native support for imported standard libraries, including:

- std/math (the complete stable JavaScript Math surface supported by Node.js 20+); floor(value) is also globally available

- std/time (providing sleep and now)

- std/game (optional left-handed Babylon.js/Electron 3D desktop engine; +X right, +Z forward; install @misterscan/sesi-game)

- JSON serialization/deserialization through the built-in to_json and from_json functions

Build live 3D scenes with mutable Sesi-native handles, fixed-step callbacks, input, Havok physics, GUI, audio, and source-free desktop packaging. See getting-started/GAME.md.

Reasoning-Native Features ✅

• model() calls with Reasoning provider configuration
• Native model("local") inference through a cached, quantized ONNX model
• image() calls with specific ratio/size generation capabilities
• Async Polling: Native looping to auto-resume generation when hitting MAX_TOKENS limit

System Features ✅

• Memory: Basic memory for multi-turn reasoning
• Filesystem I/O: read_file(), write_file(), to_json(), write_image(), list_dir(), and convert() for local file I/O and format transformations
• Native Concurrency: spawn() and exec() for concurrent process management, and multi_req(array<function>) for physical parallel request execution.
• In-Process Script Execution: sesi(path, local?, checkOnly?) executes or compile-checks a Sesi file synchronously without launching a child process.
• Inline Runtime Helpers: python(code, args) and js(code, args) for host-language scripting, plus html(body, options) for generating complete webpages.
• Logic Caching: High-efficiency Sesi Logic Caching (.sesi_cache.json) for local call caching.
• HTTP Client: Built-in, native HTTP client support using web_get(url) and web_send(url, body, headers) with zero external dependencies.
• Utility Builtins: time() and random() for robust coordination
• Structured Output: structured_output() for typed JSON Schema
• Function Calling: tool_call() for function calling
• Prompt Blocks: prompt blocks for cleaner and more concise script composition

See Local Models for the context limit, the public

2,048-token CPU warning threshold, configuration, and reference performance.

Type System

• Static types: number, string, bool, array<T>, object<T>
• Type inference
• Union types for Reasoning response handling

Roadmap

V3: Agents & Orchestration

• Agent definitions with state
• Tool composition and chaining
• Multi-agent collaboration
• Persistent knowledge bases

License

MIT