azul

azul is a Go implementation of the Lox programming language. The current implementation is a complete tree-walk interpreter for Lox: scanning, recursive-descent parsing, lexical resolution, closures, classes, inheritance, and runtime execution are wired through the CLI.

The experiment in this repo is an interpreter feedback loop:

azul run file.lox --fix
       |
       v
   scan + parse + interpret
       |
       v
   errors? -- no --> print output, exit clean
       |
      yes
       |
       v
   build error payload
   (source + error type + line + message + stack trace)
       |
       v
   send to fantasy agent
   with tools: read_source, apply_patch
       |
       v
   agent reasons over the error
   calls read_source to see surrounding context
   calls apply_patch with the corrected source
       |
       v
   azul writes patched source back to file.lox
   reruns the file
       |
       v
   still errors? -- yes --> retry up to N times or give up
       |
      no
       v
   print output, exit clean

Context

Refer context.md

Requirements

• Go 1.26.4 or newer.
• Task for the task ... shortcuts.
• A Groq API key for the agent fix loop.

The CLI reads model settings from the root config.yaml:

provider: groq
base_url: https://api.groq.com/openai/v1
model: llama-3.3-70b-versatile

It loads .env automatically for secrets, so this works:

GROQ_API_KEY=your_key_here

Agent prompts live in prompts/system.md and prompts/fix_user.md.

Run Lox

Run a working Lox program:

task run -- examples/complete.lox

Expected output:

41
42
azul-lox
0
1
2

Run the same program through the Part II bytecode compiler and VM:

go run ./cmd/azul run examples/complete.lox --vm

Print structured diagnostics for the deliberately broken sample:

task lox:sample

Expected behavior: examples/broken.lox reports colored source-frame parse errors. The sample is intentionally invalid Lox and is used to exercise the agent fix loop.

Check the normal run path without the agent:

task lox:smoke

This task is expected to pass only when azul run examples/broken.lox fails with diagnostics. It is a smoke check for the error-reporting pathway, not a successful Lox execution.

Run another Lox file directly:

task run -- path/to/program.lox

Run the fix loop on another Lox file in place:

task run:fix -- path/to/program.lox

Print debug output for another file:

task debug -- path/to/program.lox --tokens --ast

Inspect bytecode emitted by the compiler:

go run ./cmd/azul debug path/to/program.lox --bytecode --errors=false

Check The Agent Loop

Run the Groq-backed Fantasy agent against a temporary copy of the broken sample:

task agent:check

The task copies examples/broken.lox to /tmp/azul-agent-check.lox, runs:

go run ./cmd/azul run /tmp/azul-agent-check.lox --fix --max-retries 1

and then lets the CLI re-scan the patched temp file. The repo sample is not modified by this task.

If the agent call succeeds, the command prints the agent explanation and either:

• exits cleanly after the patched temp file has no scanner errors, or
• reports the remaining scanner errors after the configured retry limit.

If it fails before a patch is applied, check the returned provider error. Common causes are a missing GROQ_API_KEY, invalid config.yaml, Groq rate limits, model permissions, or an unstable tool-call response from the selected model.

You can increase attempts without editing code:

task agent:check MAX_RETRIES=3

Development Commands

Build the CLI:

task build

Run all tests:

task test

Run format, vet, and tests:

task check

Start the REPL:

task repl

Output