Basics
Guides
API Reference
Basics
Guides
API Reference
AGR is the Aussom Graphical REPL: a desktop app for writing and running Aussom code interactively. A REPL (read-eval-print loop) lets you type a bit of code, run it, and see the result right away, without creating a file and running it from the command line. AGR adds a graphics area, so code that draws a window or a chart shows its output in the same app.
This page is a tour of the AGR window and its main features.
AGR installs with the Aussom CLI. After you install Aussom, open a terminal, go to the folder you want to work in, and run:
cd ~/projects/my-app
agr
The folder you start AGR in is the one it works on. AGR calls that the
workspace. It keeps your code, history, output, and appearance settings in an
.agr folder inside it, so the work stays with the project. Start AGR in a
different folder and you get a different workspace, with its own everything.
You can open several at once, one per folder. See Workspaces below.
AGR also creates ~/.agr for the few things that belong to you rather than to
any one project: your key bindings, downloaded AI models, and installed
themes.
The AGR window has a menu bar and a slim top bar across the top, then a large work area split into three parts:
You can drag the divider between the left pane and the right side, and the divider between the code area and the log, to give each part more room.
The top bar holds the controls you reach for most:
The Code tab is where you type Aussom code. It works like a small code editor:
To run what you have typed, press the run key (Ctrl+Enter, or Cmd+Enter on macOS) or click Run. AGR evaluates the code and shows the result in the Log tab. When the code runs without an error, the Code tab clears so you can type the next submission; when it fails, your code stays put so you can fix it in place.
The Log tab is a read-only transcript of everything that happens. Each kind of output is styled so you can tell them apart:
The transcript scrolls as new output arrives. To empty it, use the clear-output key (Ctrl+L by default).
The History tab is a running list of every submission you have run in the this workspace, newest activity at hand. It is your executed-code log: a record you can scroll back through and reuse.
To bring a past submission back into the Code tab, double-click it (or select it and press Enter). If the Code tab already has text in it, AGR asks first, so a recall never quietly replaces work in progress.
Right-click a row - or pick several with Ctrl or Shift and then right-click - for two more actions. Copy puts the full source of the selected rows on the clipboard. Append to Scratchpad sends them to the Scratchpad tab, so you can build a file out of the runs that worked.
The Scratchpad tab is a place to collect and shape code you want to keep. Testing in the REPL leaves your good snippets scattered through History, mixed in with throwaway tries. The Scratchpad is where you gather the ones that worked and assemble them into a real Aussom file - adding imports and glue as you go - without leaving AGR for a separate text editor.
It is an editable text area with the same Aussom syntax coloring as the Code tab, but it does not run code. Think of it as a built-in notepad for Aussom files.
Filling it. Type or paste directly, or send runs to it from History: right-click one or more History rows and choose Append to Scratchpad. Each appended entry is separated from the one before it by a blank line.
The toolbar. Four icon buttons sit above the text:
Open and Clear ask first when there are unsaved changes, so you never lose a draft by accident. An asterisk in the tab name (**Scratchpad ***) marks unsaved changes. You can also save from File > Save Scratchpad.
It is remembered. The Scratchpad belongs to the workspace and is saved with it. An unfinished draft is still there the next time you open AGR in that folder, whether or not you have saved it to a file.
Standard editing keys - copy, paste, undo, redo, and caret movement - and the font-size keys work in the Scratchpad just as they do in the Code tab. The run key does nothing here, since the Scratchpad does not execute code.
The pane on the left is where graphical output appears. When your code opens a window or draws with Aussom's UI libraries, it renders here inside AGR rather than in a separate window. This makes AGR handy for trying out UI and graphics code and seeing the result immediately beside your code.
AGR ships with the full Aussom documentation and its own browser to read it. Open it from Help > Documentation or press F1.
The doc browser is a small, themed window with a toolbar:
fx.Button, or a term like setOnAction - and a
ranked list of matching pages appears; press Enter or click a result to open
it. More results load as you scroll, so you are never limited to the first
handful.The doc browser follows your AGR theme, so switching to a dark or light theme re-colors the docs to match.
A workspace is simply the folder you started AGR in. There is no list to manage
and nothing to switch between - to work on something else, open a terminal
there and run agr again.
Each folder keeps its own:
All of it lives in an .agr folder inside your project, next to the
.aussom/modules folder that holds any packages the project uses. That is why
include works the same in AGR as it does when you run the file with the
aussom command - both look in the same place.
A few things belong to you rather than to a project, and live in ~/.agr:
Open as many as you like, one per folder. They are independent: changing the theme in one does not change the other, which is handy - the colors tell you which window is which.
The shared settings work slightly differently. If you change your key bindings or pick a different AI model, the window you changed it in updates, but a window that is already open keeps what it had until you restart it.
The first time you run AGR in a folder, it copies your current appearance settings so the new workspace looks the way you like instead of resetting to the defaults. After that the folder is on its own - changing its theme changes only that workspace.
To clear out everything you have run without leaving the folder, use Reset Engine on the Inspector tab. It empties every variable and class and restarts the graphics, and keeps your code, Scratchpad, history, and Log.
The .agr folder is ordinary files, so you can commit it. AGR adds a
.gitignore when it creates the folder that keeps buffer.aus and
scratchpad.aus - your code - and ignores transcript.log and history.jsonl,
which are a record of what you typed and are usually noise to everyone else.
Change those two lines to commit everything, or add .agr/ to your project's
own ignore file to commit none of it.
Aussom
Write once. Embed everywhere.
Copyright 2026 Austin Lehman. All rights reserved.