Closing or crashing the app while an agent is working
It is safe to close Castforge while an agent is in the middle of a task, and it is safe if the app or your machine crashes. Your work is not lost.
Castforge continuously saves the things that matter: your conversation transcript, your project and role configuration, and the agent's session identifiers. The only thing that cannot survive a close or crash is the live agent process itself, because that process stops when the app stops. Everything else is on disk and comes back when you reopen.
Resuming is manual, never automatic
When you reopen the app, Castforge does NOT restart any agents on its own. A run that was in flight comes back paused, and nothing runs until you say so. This is deliberate: an unattended agent should never wake up and start working while you were away.
The Interrupted card on the board
If a card was mid-task when the app closed or crashed, it comes back marked Interrupted on the board instead of looking like it is still working. An Interrupted card has a coral marker, does not pulse (nothing is running), and shows a Resume control. This is your signal that the card was stranded by a restart and is waiting for you.
Click Resume on the Interrupted card to continue. Castforge rebuilds the run from the saved snapshot: the interrupted task plus the rest of the handoff chain that was queued behind it, and drives the whole chain through to completion. Resuming does not re-send your last chat message; it restarts the work that was in flight.
The fallback if a session cannot be restored
The live agent process is always gone after a close or crash, so the agent's tool usually reports its old session as stale. When that happens, Castforge does not fail or hang. It quietly starts a fresh turn from the saved context (your task, the board, and the run's progress) and records a short note in the project ledger that it resumed without the old session.
Your work and the run's progress are carried forward, so you keep going without retyping anything. This fallback is normal and non-destructive; the only thing lost is the agent's in-memory conversation from before the close, which it rebuilds as it continues.
Why some buttons look "stale" after a restart
After a restart, you might see an old permission prompt or an Apply button from a previous session that no longer responds when clicked. These are stale controls: they belong to an agent process that no longer exists, so there is nothing for the click to talk to.
This is expected. A permission prompt or Apply button is a live request from a running agent. Once that agent process has stopped (because you closed the app or it crashed), the request has no one to answer it, so the button can no longer act. Castforge renders these leftover prompts as inactive rather than pretending they still work.
What to do: ignore the stale control and continue in your current, live session. Send your next message, or use the Resume button if one is offered, and the agent will reissue any permission request it still needs. You will get a fresh, clickable prompt tied to the live session.
If you ever click a live permission button and nothing visible happens, that is a bug worth reporting rather than expected behavior. Castforge is designed to either act on your choice or show you a clear error, never to silently do nothing.
Undoing a change with /undo
If an agent edits a file and you want that edit reversed, use the /undo command in the message box.
- In the composer, type
/undoand run it. - Castforge takes the most recent file change the agent applied in this conversation and writes the file back to exactly how it was before that change.
- The change is marked as reverted in the conversation, so you can see it was rolled back.
A few things to know:
/undoreverses one change per use, starting with the most recent and working backwards.- It applies to file edits (the diffs the agent applied), not to every possible action.
- Castforge keeps a limited history of recent edits per conversation for undo, so very old changes may no longer be reversible.
/undo restores the file from a saved copy of its previous contents, so it is a reliable way to step back from an edit you did not want.
Rolling back further: restore in place and cascade undo
/undo steps back one file edit at a time. For bigger rollbacks Castforge has two heavier, destructive options. Both are guarded: they ask you to confirm every single time, in every mode, including autonomous, because they change your working tree or your git history in ways that are not a one-click "redo".
Restore in place
Restore in place resets your project's working files back to a saved point in time (a keyframe the time machine captured). Before it touches anything, it stashes your current uncommitted work with git first, so nothing you had in progress is thrown away: your changes are set aside and are recoverable, and the branch you were on stays where it was. Then it resets the working tree to the chosen point. Because your prior work is stashed and your branch is untouched, the reset is reversible, but it does replace what is currently in your files, so Castforge always prompts before doing it.
Dependency-aware cascade undo
Cascade undo takes back a task's committed work and, because tasks can build on each other, also takes back the work of every task that depended on it, while leaving unrelated tasks alone. It walks the dependency graph from the card you chose, gathers that card plus everything downstream of it, and reverts their commits (it adds reverting commits rather than erasing history, so the record stays honest). Before it runs, it shows you a preview: exactly which cards, which commits, and which files it will touch, so there are no surprises. A card it cannot map cleanly to a commit is skipped and flagged in that preview rather than guessed at. If a revert hits a conflict it is stopped and surfaced to you, never force-resolved. Like restore in place, cascade undo prompts for confirmation every time.
General troubleshooting
The app will not launch, or shows a blank white screen
A blank window on launch is almost always a stale or development build issue rather than a problem with your account or data.
- Fully quit Castforge, including any background instance, and reopen it.
- Make sure you are running the installed Castforge app, not a leftover development process.
- If it persists after a clean relaunch, reinstall the latest version from castforge.ai. Your projects and sign-in are stored separately and survive a reinstall.
Sign-in problems
If the app shows you as signed out even though you signed in, or the sign-in does not seem to stick:
- Sign in again with the magic link. The link opens in your browser; complete it there and return to the app.
- If you closed the browser before the sign-in finished, it will not register; start the sign-in again and complete the browser step.
- After a successful sign-in, Castforge stores your session in your operating system's keychain so it survives restarts. If it still does not stick after a clean relaunch, sign out fully and sign in once more.
An agent is not responding
If you send a message and the agent does nothing:
- Check that the agent is actually connected. Open the Connections page and use "Verify connection" on the agent's card.
- Confirm the agent's command-line tool is installed and on your system path. If it is missing, Castforge shows install help on the card. After installing, restart Castforge so it picks up the new tool.
- If a turn seems stuck from a previous session, look for a Resume button, or send a fresh message to start a new turn.
- If you are mid-task and waiting on a permission prompt that will not respond, it may be a stale prompt from a previous session (see above). Continue in the live session and the agent will reissue the prompt.
A run that ends with a question no longer goes quiet
Sometimes an agent finishes a turn by asking you something ("Should I use Postgres or SQLite?") or telling you it is blocked, without there being a next task ready to run. Castforge now watches for this: when a turn ends on an unanswered question or a stated blocker and the board has nothing queued to continue, it raises a "Needs you" prompt on the card instead of letting the run settle silently. You will see the card flip to the coral "Needs you" state carrying the question, so you can answer and let the run continue rather than wondering why it went idle.
This is deliberately cautious. It only speaks up when the last thing the agent did was ask or report a blocker (not while it is still using tools), and it stays quiet on a normal, finished turn, so it will not nag you after work that actually completed. If it ever does surface a prompt on a turn that was really done, you can just dismiss it.
Finding stuck or interrupted work in one place
If you are not sure what is stuck, open the project's Health tab (next to Chat, Course, Preview, and Memory). It gathers the cards paused because a provider usage limit was hit (each with a Resume, and the reset time when the provider reports one), the cards the board reads as stalled (each with a Nudge to re-dispatch), the cards left Interrupted by a restart (each with a Resume), and a recent history of stalls, wedges, surfaced idle prompts, and automatic resumes. It is read-only apart from those Resume and Nudge buttons, and it mirrors the board's own markers, so it never disagrees with the cards. If nothing needs you, it says "Nothing needs you".
When you hit a provider usage limit
AI providers cap how much you can run in a window (for example, GitHub Copilot Free gives a set number of premium requests per month, and the paid plans have their own limits). If a run hits that cap mid-task, Castforge does not lose your place. The active card is parked as Paused on a usage limit rather than looking like a generic stall, and the work done so far is saved.
You will find the paused card at the top of the project's Health tab. When the provider tells Castforge when the limit resets (Claude does today), the card names the provider and the reset time, for example "Claude usage limit was reached. It should reset around 3:00 PM, then you can resume." When the provider does not report a reset time, it simply tells you to resume once your limit refreshes.
Click Resume on that card once your limit is back, and the run continues from where it stopped. Castforge does not relaunch on its own; you decide when to pick it back up.
When in doubt, restart cleanly
Many transient issues clear with a clean restart: fully quit the app and reopen it. Your transcript, projects, and connections are all stored on disk, so a restart costs you nothing but reconnects the live pieces.
Storage stays healthy on its own
Castforge keeps its local database tidy for you. In the background it trims very old conversation messages (roughly two weeks and older) and caps how many messages any single conversation keeps, so the on-disk store cannot grow without bound and slow down launch. This runs automatically at startup and once an hour, and it never removes a conversation itself, only the oldest messages inside it. It also keeps just the few most recent daily backups rather than one for every day forever. You do not need to do anything, and it never interrupts an active run.
Message search is off by default on a fresh install so nothing is indexed until you want it, which keeps first-run storage small. If you turn search on later, Castforge builds the index on demand.
Reporting a bug from inside the app
Use Send feedback (in the app menu) and choose the Bug tab. Describe what happened, optionally what you expected and the steps to reproduce, then send.
Before you send, the "What we'll include" panel shows exactly what rides along: a few small diagnostics (app version, operating system, current screen, active agent), and for Bug reports a recent excerpt of your application log. The log excerpt is what lets the team see what the app was doing when things went wrong, without asking you to find log files on disk.
You can also attach a screenshot: click "Attach or paste an image", or just paste an image straight from your clipboard (for example, after a Win+Shift+S snip). A small preview appears that you can remove before sending. Screenshots are stored privately and are only visible to the Castforge team.
Everything attached is reviewable and removable: expand any item to read it, or remove it before sending. Secrets are scrubbed automatically, so API keys and tokens never leave your machine. The log excerpt is a bounded recent slice, not your whole log.
Common questions
Will I lose my work if Castforge crashes? No. Your transcript, projects, configuration, and the state of any in-flight run are saved continuously. Only the live agent process stops. When you reopen, an interrupted card comes back marked Interrupted and waits for you to click Resume; nothing restarts on its own.
The app started a "fresh session," did I lose anything? Only the agent's in-memory context from before the close. Your conversation history is intact, and your last message is carried into the fresh session for you.
A permission button does not do anything. What is wrong? If it is left over from a previous session it is stale and inactive by design; continue in your live session. If it is a live prompt and clicking truly does nothing, that is a bug worth reporting.
How do I take back an edit the agent made?
Run /undo in the composer to revert the most recent applied file change. Run it again to step back further. For larger rollbacks, restore in place resets your working files to a saved point (stashing your current work first), and cascade undo takes back a task plus everything that depended on it; both show up as confirm-every-time actions because they are destructive.
A run went quiet and I cannot tell what is stuck. Open the project's Health tab. It lists cards paused because a provider usage limit was hit (with the reset time and a Resume), stuck cards with a Nudge to re-dispatch, cards left Interrupted by a restart with a Resume, and a recent history of stalls, wedges, and automatic resumes. If nothing needs you, it says so.
Will Castforge's storage grow forever and slow things down? No. Castforge automatically trims old conversation messages and caps per-conversation history in the background, so its local database stays bounded. It also keeps only the few most recent daily backups. This happens on its own and never removes a whole conversation or interrupts an active run.
I see a white screen on launch. Fully quit and relaunch the installed app. If it persists, reinstall the latest build from castforge.ai; your data survives the reinstall.
The app says I am signed out after I signed in. Re-run the magic-link sign-in and complete it in your browser. After a clean relaunch the session is stored in your OS keychain and should persist.