Why Hara?

Start with the system, not the theory. This page is connected to a browser-hosted Hara kernel. Put the cursor in the form below and press Ctrl-Enter (or ⌘-Enter). The result appears inline.

(+ 1 2 3)
; => 6

You wrote one form, evaluated it in a live runtime, and inspected the value it returned. That small loop is the foundation of the manual:

write a form → evaluate it → inspect the value

Why that is useful

Modern web development is remarkably capable: React, TypeScript, browser APIs, state libraries, build tools, and cloud platforms can produce sophisticated applications quickly. As a project grows, though, the experience can become increasingly indirect: edit source, wait for an update, reproduce an interaction, inspect several tools, and infer what happened inside the running system.

Hara offers another approach. It is not another framework intended to replace the browser, React, or an existing frontend stack. It is a small, embeddable kernel that can sit inside a browser, editor, application, or development environment. The kernel gives a person—and an AI agent—a structured way to inspect application state, evaluate a bounded change, and observe the result while the system is running.

HAL (Hara Lisp) is an EDN-compatible, host-neutral notation and data format for communicating with that kernel. HAL forms provide a compact, inspectable way to ask the system questions and make bounded changes.

HAL is how you talk to the kernel

The kernel reads HAL forms that describe computations, inspect values, and change the running system. The notation stays portable while the kernel and its host interfaces determine what can execute and which effects are allowed.

For now, only four rules are needed:

(+ 1 2)FormParentheses hold one computation.

+ 1 2Operation firstThe first item usually says what to do.

[1 2 3]VectorSquare brackets hold an ordered collection.

{:name "Ada"}MapBraces connect named facts to values.

(def user {:name "Ada"
           :status :active})

(get user :name)

Later chapters go deeper into reading HAL forms, evaluation, macroexpansion, and the relationship to Clojure and other Lisp traditions. For this manual, keep the positioning simple:

Hara is a programmable kernel. HAL forms are how you talk to it.

Work with the running system

Files first

1. EditChange the durable source file.
2. RebuildTurn source into a runnable version.
3. ReloadReplace what the running system knows.
4. ReproduceReturn to the state that proves the issue.
5. InferWork backwards to explain the result.

Live system first

1. InspectSee the state that exists right now.
2. EvaluateMake one bounded change or query.
3. ObserveRead the returned value or visible output.
4. TraceFollow the calls and effects behind it.
5. KeepPut the verified insight into source.

This is runtime-driven development. Instead of changing a representation of a system and waiting to discover the result, you interact with the system while it is alive. A successful experiment can then be kept in source deliberately.

The kernel is the stable part of that workflow. The host changes according to where the interesting live state is:

Browser
workspace Chrome
panel VS Code CLI / REPL

Hara kernel running system

The browser is a useful first host because it makes the loop immediate: there is nothing to install, values can be rendered beside their forms, and visual or browser-native effects can be observed where they occur.

Web native from the start

Hara is designed to run on the web and through WebAssembly. A browser-hosted kernel can be opened, queried, and observed without first assembling a large local toolchain. The first form on this page demonstrates the point: what matters is not that (+ 1 2 3) is small, but that it ran in the same environment whose result you could immediately inspect.

Hara form→Browser-hosted kernel→WebAssembly runtime→Inspectable value

The same kernel model can later be reached from a browser workspace, Chrome DevTools, VS Code, a command-line REPL, an embedded application, or an AI development tool. The editor or console is a surface; the kernel is the running environment behind it.

Keep important application state visible

React is excellent at turning state into an interface. Hara gives you the option to keep important application information inspectable independently of the component that currently renders it.

(def app-state
  (atom {:user nil
         :route :home
         :documents {}
         :connection :online}))

(deref app-state)

◇Application state and behaviourNamed information and operations you can inspect.atom · defn · deref

⚛UI adapterReact renders the information for this view.state → interface

React can still render this information. It simply does not have to be the final owner of it. The deeper application architecture is documented in Substrate application architecture, outside the Start sequence.

Isn't this just a console?

A JavaScript developer should ask this. The browser console already evaluates code, inspects values, and can change a page. Hara does not replace DevTools; DevTools lets you inspect the browser, while Hara lets you design an application to be inspectable.

A console is an interface. A kernel is the running environment behind the interface.

Chrome DevTools connects its console to a page's JavaScript runtime. Hara aims to provide a deliberately structured kernel that can be embedded in a system and reached through more than one surface, including browser workspaces, Chrome panels, VS Code, the CLI / REPL, and AI agents.

The distinction matters only if the kernel provides more than arbitrary evaluation. A Hara kernel is intended to provide:

◷Named sessionPersistent runtime state.

◇Structured valuesState you can inspect.

▦Workspace modelProjects have explicit shape.

⌁CapabilitiesHost access is controlled.

⌘EvidenceTraces explain evaluations.

↔ProtocolTools and agents connect reliably.

◎Shared clientsSeveral surfaces see one system.

◫Connected outputSource, state, nodes, visuals.

The browser console is a powerful developer tool attached to one browser execution context. It does not normally define an application-level inspection contract shared by people, editors, visual tools, and agents.

The console is one possible front end to Hara. The kernel is the persistent, inspectable runtime that the console connects to.

There is an important caveat. If Hara only evaluates HAL forms and prints results, then the JavaScript developer is right: it is effectively another console. The documentation must demonstrate the difference early—by showing the same kernel from multiple surfaces, named state, bounded changes, visible output, traces, and structured agent access—not merely assert it.

What the kernel makes inspectable

Inspectability is not a debugging feature added after an application exists. It is a property to design for from the beginning. A Hara system should make these relationships legible:

Source
formsEvaluated
valuesApplication
state

Messages
and eventsFunctionsTraces

Host
capabilitiesPermitted
effectsVisual
output

Developer or agent change → observable evidence → source kept deliberately

That makes practical questions answerable: What state exists now? Which form changed it? What depends on it? Which event reached this function? What can be changed safely, and what result proves the change?

A shared interface for people and agents

An agent using Hara should not have to edit files blindly and infer outcomes from build logs. The same live kernel can provide a structured loop:

◉InspectState and capabilities.

λEvaluateOne controlled form.

◫ExamineValue, output, or error.

⌘TraceCalls and effects.

▣KeepEvidence becomes source.

Safety boundary

This does not make changes automatically safe. It makes their scope and their evidence visible to both collaborators.

Source, state, and effects are different things

A source form is durable text. Evaluation gives it a value in a running session. That value may update state, and a host capability may turn state into an effect such as a canvas draw, file operation, DOM update, or message.

Keeping those layers distinct makes a live system easier to reason about:

Source
form Evaluate → Runtime value
or state Host
capability Observable
effect

The kernel lets you work across those layers without pretending they are the same thing.

Take the next step: persistent state

Now create a small piece of persistent runtime state, change it once, and inspect it again. Evaluate each form in order.

(def orientation-state
  (atom {:status :ready
         :count 0}))

(swap! orientation-state update :count inc)

(deref orientation-state)
; => {:status :ready :count 1}

You have just made one bounded change to a live session and inspected the result. The important lesson is not the syntax: it is that you can observe the system between each step.

What to expect today

The documentation and browser examples provide a shared live kernel for evaluation, inline results, syntax-aware editing, and small inspectable experiments. Different hosts expose different capabilities; a browser kernel does not silently become access to local files, network services, or browser extension APIs. Those boundaries are explicit parts of the host relationship.

The following chapters place the same kernel closer to the systems you are building: first by choosing a host and installing a runtime, then by working with definitions, state, projects, and visual systems in more depth.

Continue

Next, choose where the kernel will run and verify that it is available:

02InstallPut a kernel where you work. ▶Browser PlaygroundTry the live kernel now. →Learn HaraContinue with forms and state.