Preview and iterate

Overview

Castforge can run your project's development server and show the running app in a live Preview panel, right next to the conversation with your agents. The dev server starts as soon as the project becomes active, so the Preview is already warm by the time you open it. As your agents change code, the dev server hot-reloads and the Preview updates, and Castforge also nudges a refresh as agents finish cards, so you can see your app take shape without leaving the app.

This page covers:

• The live Preview panel and how the embedded view works
• Auto-starting the preview (on by default), and the per-project Auto-start switch
• The URL bar and reload
• Device frames (Web, Phone, Tablet, Desktop)
• Empty and error states (what "run npm run dev" means)
• The Inspect toggle and visual editor (note: partial, see below)
• The Time Machine: snapshots, peeking at a past state, and resuming to live

The live Preview panel

Open the Preview view for a project to see a split layout: your conversation on the left and the live Preview on the right. Because the dev server starts when the project becomes active (not when you click the Preview tab), the app is usually already loaded the moment you open Preview. The Preview area shows your running development server inside an embedded view (an iframe) pointed at localhost on the port your dev server picked.

The Preview is read-from-your-machine: Castforge does not host anything here. It simply runs the same dev server you would run in a terminal (npm run dev, or the equivalent for your package manager) and frames the result so you can watch it update.

A small status dot in the URL bar tells you what the preview is doing:

• Green (glowing): the preview is running
• Amber (pulsing): the preview is starting, or restarting after a crash
• Red: the preview stopped unexpectedly (the dev server crashed)
• Dim: the preview is not running

Starting the preview

Auto-start (the default)

When a project becomes active (you open the project and its workspace), Castforge starts the preview for you automatically, before you ever click the Preview tab. You see the amber "starting" dot, then the green "running" dot once the port is ready. Because the server is already warm, opening the Preview view shows an already-loaded app. This happens on the very first open too, so for most projects you never click anything to get a live preview.

Castforge runs your project's dev script. It detects your framework (Next.js when your package.json lists next, otherwise Vite) and uses the right adapter. The package manager (npm, pnpm, or yarn) is resolved from your lockfile, so the underlying npm run dev runs correctly even if you use pnpm or yarn.

The Auto-start toggle

A small Auto-start switch sits in the Preview header. It is on by default and controls the per-project setting:

1. When Auto-start is on, the preview starts when the project becomes active.
2. When Auto-start is off, the preview waits for you to start it by hand, and you see a Start preview button instead.

Turn Auto-start off for a project if you would rather control the server yourself. Castforge never starts a preview on app launch; it starts when you open a project (and only then if Auto-start is on). When you switch to another project or leave the workspace, Castforge stops the server it started for you, so exactly one preview server runs at a time.

Brand-new projects: waiting for setup

Castforge only starts the preview once the project is actually ready to run one. A brand-new project (its package.json was just written, but its dependencies are not installed yet) or a project still being scaffolded has nothing to serve, so starting a dev server would only fail. In that case the Preview shows a calm "Waiting for project setup" message instead of a crash. As soon as the setup finishes (dependencies install, the framework files land), Castforge notices and starts the preview on its own, then keeps it running. You do not need to click anything.

If the preview crashes

If a running preview crashes, Castforge tries to restart it automatically a couple of times (with a short back-off) before giving up. If it still cannot start, you see the stopped state with the last error and a Try again button (see Empty and error states below).

When a preview stops for any reason, whether it crashed or you switched projects, Castforge shuts down the whole process tree it started. That matters on Windows, where a child process is not killed just because its parent died: without that cleanup a leftover process can keep holding the port, and the next start would collide with it. So a crashed preview does not leave anything behind holding your port.

Your agents can check the dev server

Your agents can ask Castforge about the dev server directly, instead of poking around your machine for it. The tool is read-only: it reports whether Castforge is running a dev server for the project and whether that port is actually responding. It cannot start, stop, or restart anything, so it never asks you to confirm.

This is what stops an agent from burning time on guesswork when a preview will not load. Two answers are worth knowing:

• Not running. Castforge has no dev server for this project. If something is holding the port anyway, it is not a process Castforge manages, so it came from somewhere else (a terminal you opened, another tool, an older session).
• Running, but the port is not responding. Castforge started a server and it has not begun accepting connections yet, or it has since died.

You do not need to do anything to enable this. If you ask an agent why the preview is broken, it can check for itself.

The URL bar and reload

The URL bar in the Preview header shows:

• The status dot (see colors above)
• The current address, shown as localhost:{port}/ once the server is running
• A reload button (the circular arrows icon)

Click reload, or press Ctrl+R while focused in Preview, to refresh the embedded view. A brief flash confirms the reload. The reload button is disabled when the dev server is not started or has crashed (there is nothing to reload yet).

Device frames

Use the device-frame toggle at the left of the Preview header to wrap your app in a device chrome. Four options are available, in order:

1. Web (globe icon): no device frame. Your app fills the available width.
2. Phone (smartphone icon): a 375 by 812 phone canvas.
3. Tablet (tablet icon): a 768 by 1024 tablet canvas.
4. Desktop (monitor icon): a 1280 by 800 desktop canvas.

Switching frames scales the canvas to fit the available space and does not reload your app, so you can flip between sizes quickly to check responsive layouts. Your chosen frame is saved per project.

Empty and error states

The Preview area shows a clear message instead of your app in these cases:

• Work is in progress in agent lanes. While parallel lanes are building and nothing has landed on your branch yet, Preview explains that your agents are working in isolated lanes instead of showing a bare empty state. Each card's work lands on your branch after it passes review, and Preview starts serving then; track progress on the Course board.
• Waiting for project setup. For a brand-new project whose dependencies are not installed yet, or one that is still being scaffolded, you see a calm "Waiting for project setup" message. Castforge starts the preview by itself once setup finishes, so there is nothing to click here.
• Preview not running. When Auto-start is off (or the server is stopped) on a project that is ready to run, you see a "Start preview" panel with a Start preview button. Click it to start the preview.
• Preview stopped unexpectedly. If the server crashed and the automatic retries did not recover it, you see "Preview stopped unexpectedly" with the last few lines of the error output and a Try again button. Fix the underlying error (the same one you would see in a terminal), then click Try again.

If the embedded view is blank but the status dot is green, try the reload button. If it stays blank, confirm the app actually serves a page at the shown localhost address.

Inspect and the visual editor (partial)

The Preview header includes an Inspect toggle (the eye icon). It is enabled only while the dev server is running.

In the current build, the Inspect toggle stores the on/off state, but the on-canvas inspect overlay and the click-to-edit visual editor popover are not yet active in the Preview. The design intent is to let you hover and click an element to outline it, see its size, edit text and color inline, and send a request about that exact element to your agent. Treat Inspect and the visual editor as a work in progress for now: the toggle is present, but the full inspect-and-edit flow is not yet wired into the live Preview.

The Time Machine

The Time Machine drawer lives in the Preview view, pinned to the bottom of the preview column. It opens automatically when you enter Preview, and you can collapse it any time with the chevron (the next time you open Preview it opens again by default). It captures a snapshot, called a keyframe, each time an agent finishes a card, so you can scroll back through your project's recent visual history and peek at any past state.

Reading the drawer

• Collapsed, the drawer is a thin bar showing "Time machine", a count of changes today, and how long ago the last edit was. Click it (or the chevron) to expand. Click the chevron again to collapse it.
• Expanded, keyframes are laid out left to right, oldest on the left and newest on the right. The newest keyframe is your current, live state.
• When there are no keyframes yet, the drawer reads "No keyframes yet, run an agent to start", and the expanded view explains that each time an agent finishes a card, Castforge saves a snapshot you can rewind to.

You can move focus across keyframes with the Left and Right arrow keys.

Peeking at a past state

Click a past keyframe to peek at it. Peeking opens that historical state in the Preview behind an amber glow and shows a banner: "Peeking keyframe {N}, agent writes continue in live state (this is view-only)."

Peeking is view-only. Your agents keep working against the live state while you look back; peeking does not pause them and does not change your files. The banner stays until you leave peek mode.

Rewinding or resuming

From the peek banner you have two actions:

• Rewind to here. This rewinds your project to the peeked keyframe on a new branch, so your current work is preserved in history. Castforge confirms the new branch name.
• Resume now. This exits peek mode and returns the Preview to your live state. Resume is the primary action and is focused when the banner appears, so you can press Enter to return to live. Pressing Escape also clears the peek (or collapses the drawer if you are not peeking).

Common questions

My Preview is blank or will not load. What should I check?

In order: is the status dot green (running)? If amber, wait for it to finish starting. If it is dim, Auto-start is off, so click Start preview. If it is red, Castforge has already tried to restart it automatically; read the error tail in the stopped state, fix it the way you would in a terminal, then click Try again. If the dot is green but the view is blank, click reload, and confirm your app serves a page at the localhost address shown in the URL bar.

Which dev servers does Preview support?

Castforge runs your project's package.json dev script. It has first-class detection for Next.js (when next is a dependency) and Vite, and falls back to running the generic dev script otherwise. Your package manager (npm, pnpm, or yarn) is detected from your lockfile.

Why did the preview not start?

By default Castforge auto-starts the preview when the project becomes active, so it is usually already warm before you open the Preview view. If you see "Waiting for project setup", the project is brand-new or still being scaffolded and its dependencies are not installed yet; Castforge starts the preview on its own the moment setup finishes, so you can leave it. Otherwise, check that the Auto-start switch in the Preview header is on, and that the project is a web project Castforge can serve (it runs your package.json dev script). If the preview started and then crashed, Castforge retries a couple of times before showing the stopped state with a Try again button.

Does Castforge host my running app?

No. The Preview runs your dev server locally on your own machine and frames localhost. Hosting and public links are part of publishing, covered in the publishing and deploying guide.

Can I edit elements visually by clicking them in the Preview?

Not yet in the current build. The Inspect toggle is present (and only active while the dev server runs), but the click-to-edit overlay and visual editor are still being wired into the live Preview.

Are Time Machine snapshots automatic?

The Time Machine captures a keyframe each time an agent finishes a card. If your drawer shows "No keyframes yet", run an agent through a card to begin building history. Peeking is always view-only and never interrupts your agents.

Does peeking at an old keyframe stop my agents or change my files?

No. Peeking is view-only. Agents continue writing to the live state while you look back, and your files are untouched until you explicitly choose Rewind to here, which creates a new branch.