How the Editor Helps You Learn

Circuitry's code editor is a full editor: a file browser, version control, tabs, completions, breakpoints, terminals and an AI agent. This page covers the parts a learner uses in the first weeks, and ends with a short list for anyone who already knows VS Code.

A program to follow along with

Make a Python file ( → Code → Python), paste this, and press Run in the footer:

name = "Ada"
total = 0

for n in range(1, 6):
    total += n
    print(n, "squared is", n * n)

print("Hello,", name)
print("The numbers add up to", total)

Tap to enlarge

Run

Run is in the footer of every file that can run. There is nothing to set up first.

• A plain program, like the one above, runs to the end and prints into the output panel.
• A file that draws (turtle, Pyctures, Pymations, a chart) runs in the preview beside the code. While it runs, the same button is Stop.
• A Flask web app is started, and serves until you press Stop.

Each run of a file starts fresh, from the first line.

The first run in a session loads Python, which can take a few seconds. After that, runs start straight away.

The preview and the three views

Two buttons in the footer choose what you see:

A new, empty Python file opens split, and so does a file that draws. A plain program opens as code only. Once you pick a view yourself, it is remembered for that file on this device.

You do not have to turn the preview on. If you press Run with the preview off and the file draws, the editor switches to split and runs it there.

The output

For a plain program, the Output panel opens under the code when you press Run. It has up to four parts, in this order:

• Python runtime: what Circuitry did to get Python ready for this run, such as loading or installing a library. These lines are dimmer than your program's own, and they are not printed by your program.
• What your program printed, line by line.
• An error, in red, with the line it happened on. Read the last line of it first: it names what went wrong.
• Result: the variables your program ended with, and their values. Above, name is "Ada", total is 15 and n is 5.

For a file with a preview, what the program prints appears under the preview, with any errors. Tap or click an error and the editor goes to that line. LOG in the footer hides the output and shows it again.

Breakpoints and stepping

A breakpoint stops a program just before a line runs, so that you can look at every variable at that moment and then go on one line at a time.

1. Tap or click just left of a line number. A red dot appears. F9 does the same for the line the cursor is on.
2. The Debugging button in the footer lights up. Press Run.
3. The program stops at the line. A bar above the code has Continue, Over, Into and Out, and the Debug tab in the sidebar lists the variables.

Python, JavaScript and TypeScript files have breakpoints. Two cases depend on the device: a Python file that draws in its preview, and a Python web app, stop at breakpoints only on iPhone and iPad, when the app's own Python is running them. Elsewhere they run straight through and the output says so. print() works everywhere. See Debugging and Debugging Python graphics.

Where your files are

A new file is not written anywhere until you save it. Your work is kept on the device as you type, and the footer shows an amber dot while you edit and a check once it is kept.

The first time you press Save (⌘S), Circuitry asks where the file should go:

After that, Save writes to that file. To open a file that already exists, use File → Open File (⌘O); to work in a whole folder, File → Open Project (⌘⇧O). See Code IDE Tour.

On an iPad or a phone

The same files run on a tablet and a phone, with the same Run button.

• A tablet has room for the code and the preview side by side, as a computer does.
• A phone shows one at a time. A file that draws opens on its preview, and a Code / Preview switcher moves between the two. Run shows the preview, and tapping an error takes you to its line in the code.
• A finger on the preview is the mouse: a tap is a click, and a drag moves it.
• A program that reads the arrow keys needs a keyboard. On a device without one, write the program to use taps.
• The phone key row puts the keys a phone's keyboard lacks above it.

Terminals, project folders and building compiled languages need a computer: the desktop app, or your own computer paired through Circuit. See What you can do on each device.

An AI agent beside you

Press in the header to open the chat beside your work. The agent can see the file you have open and what you have selected in it, so you can select a line and ask about "this".

Things worth asking while you learn:

• "Explain what this loop does, one line at a time."
• "Why does this give an error?" with the error selected.
• "Give me a hint, not the answer."
• "Change this so the ball bounces off the edges."

When the agent changes your code, each change arrives marked in the editor with Accept and Reject. Nothing is applied until you decide, so you can read what it did before you keep it.

While you type, faint text may suggest the next few lines: ⇥ accepts it, and typing on ignores it. The toggle in the footer turns it off, which is worth doing when the point of the exercise is to write the line yourself. See Inline AI and Coding Agent. Circuitry's AI needs a plan that includes it: see Plans and subscriptions.

If you know VS Code

The same:

• A file browser, tabs and split views, and a source-control panel for git.
• Syntax highlighting, completions, find and replace, and Rename Symbol (F2).
• Several cursors: ⌘D adds the next occurrence and ⌘⇧L selects them all. ⌘/ comments a line.
• Breakpoints in the gutter with F9, and Continue, step Over, Into and Out.
• Terminals, in the desktop app or on a computer paired through Circuit.
• Vim keys, if you use them: Vim Mode.

Different:

• Run is one button in the footer. There is no run configuration to write, and no interpreter to choose before the first run.
• The preview is part of the file's editor. A file that draws, an HTML file and a Markdown file each open beside their result.
• Python does not have to be installed. In a browser and on a phone or tablet it runs on the device; the desktop app brings its own.
• A package is installed by a line in the file, !pip install and its name at the top, not from a terminal. See Installing Python Packages.
• It runs on an iPad and a phone, with the same Run button and the same preview.
• The agent works in the same window as the code, and on your other documents too: diagrams, designs and sheets. See Circuitry as an Agentic IDE.

Keys are written with Cmd; that is Ctrl on Windows and Linux.

Related

• Code IDE Tour: every control, with its icon.
• Full IDE: Code Editor
• Languages, and where they run
• Learning to Code: the paths.