Working in a project

The workspace at a glance

When you open a project, Castforge puts you in the workspace. This is where you talk to your agent, watch it work, and review the changes it proposes. The workspace has three main regions:

• The files tree on the left, showing every file in your project.
• The conversation in the center, where you and the agent exchange messages and where proposed changes appear.
• The composer at the bottom, where you type what you want.

Across the top of the conversation you will find the workspace view toggle (Chat, Course, Preview, Pieces, Memory, Health) and, depending on your build, controls for the conversation style and permission level. Chat is the view this page covers. The others are documented separately. Note: Pieces is not shown in the current beta build, so you may see the toggle without it.

The Preview tab shows a live embedded view of your dev server. See "Preview and iterate" for how Preview works in detail.

Pinning a project to the top of your home list

On the home screen, Castforge orders your project tiles by activity, so the projects that need you (or are running) rise to the top. If you want to keep a specific project near the top no matter what, click the pin icon on its tile. Pinned projects group above everything else, most recently active first, and stay there even when they are idle or done. The pin icon fills in to show a project is pinned. Click it again to unpin and let the project settle back into the normal order.

The home status line

Under the greeting, the home screen summarizes every open project: how many there are, how many need you, and how many are running.

The running figure is checked against your projects directly, not just inferred from the activity Castforge has happened to see. That matters right after you reopen the app, and during a long quiet step where a project is working but producing no visible output for minutes at a time: those runs are still counted.

If Castforge cannot establish how many projects are running, the figure reads ? instead of 0. A question mark means "not known yet", so it is never mistaken for a confirmed "nothing is running". Hover it for an explanation. It normally resolves to a real number within a moment of opening the home screen.

Talking to your agent

The composer

The composer is the box at the bottom of the workspace. Type a request in plain language ("add a dark mode toggle to the settings page") and press Enter to send. The placeholder reminds you of two shortcuts: "Use @ for files, / for commands."

Keyboard shortcuts in the composer:

• Enter sends your message.
• Shift+Enter inserts a newline without sending.
• Ctrl+K opens the command palette.
• Esc cancels the agent's current turn while it is responding.

Your in-progress text is saved per project, so if you switch to another project and come back, the draft you were typing is still there.

Mentioning project files with @

To point the agent at a specific file, type @ and start typing the file name. A popover lists matching files from your project. Pick one and Castforge inserts the path into your message and adds it as a context chip above the composer. You can attach several files this way. Remove a chip by clicking it.

This is the reliable way to say "look at this file" without pasting its whole contents.

Attaching images

Some agents accept images (for example, sending a screenshot of a bug or a design). When the active agent supports images, the paperclip "Attach image" button is enabled. You can add images three ways:

1. Click the paperclip and pick files.
2. Drag image files onto the composer (it shows a "Drop image to attach" prompt).
3. Paste an image straight from your clipboard (a Win+Shift+S screenshot works).

Limits: up to 5 images per message, 5 MB per image, in PNG, JPEG, WebP, or GIF format. Castforge tells you with a small notice if a file is too big, the wrong format, or over the count.

If the active agent does not accept images, the paperclip is greyed out and its tooltip says so. Switch to an agent that supports images to attach one.

The per-message agent picker

Next to the send button is the agent picker chip. It shows which agent (any one you have connected, such as GitHub Copilot, Claude, Codex, Gemini, Cursor, or a local model) will handle your next message. Click it to switch. This is handy when you want one agent for quick edits and another for heavier reasoning. The composer's underline glow and the send button take on the active agent's color so you always know who you are talking to.

If no agent is connected, the composer shows a "No agent connected. Connect an agent to start." notice with a Connect button, and the send button stays disabled until you connect one.

What happens when you send: adaptive intent routing

You do not have to tell Castforge how much process a request deserves. When you send a message, Castforge reads it for intent and handles it at the right depth automatically. Once your project has a plan on the board, a one-line typo fix is done on the spot; a "rebuild the billing flow" request gets a full plan and the whole team. Before there is a plan, the small end of that range works a little differently, and the section below spells out how. This is adaptive intent routing, and it runs at the send seam so you can just type what you want in plain language.

It tells you what it is doing

Every time it routes a message, Castforge announces the choice in the conversation as a short line, so you are never guessing what is about to happen. You will see lines like:

• "Fast edit: doing it now."
• "This is pipeline work: planning it."
• "Here is where things stand."
• "Noted. Saved to memory."

The announcement reads as a native part of the chat stream, right where the work starts.

The lanes, in plain language

Castforge routes each message into one of these lanes. You do not pick a lane by hand; the announcement tells you which one it chose, and the descriptions here help you recognize each:

• Answer now: reply from what the agent already knows, start no work.
• Fast edit: make a small edit and commit it, no board.
• Quick task: one board card with a Coder and a Reviewer.
• Full plan with the team: the whole team plans and builds it (pipeline work).
• Investigate a bug: dig into the problem first before proposing a fix.
• Milestone change: update the milestone plan.
• Save to memory: keep a note in project memory for later.
• Show status: show where the project stands.

A project that has no plan yet leans toward planning, and asks before anything else

A request that reads like building something still gets the full plan. On a project with no plan on the board, an ask that sounds like building routes straight to Full plan with the team, with no question and no delay, however briefly you phrased it. A one-line kickoff like "Build a task manager, organise it into milestones" gets the Lead, a plan, and milestones, the same as a long detailed brief would.

When that happens, the announcement says why it is planning the whole thing and names the smaller path: "No plan on the board yet, so I am planning the whole thing. The alternative is a smaller edit done right now." The Just do it chip sitting beside that line is the one click that takes the smaller path.

A request that is clearly not building anything asks you first. On the same unplanned project, an ask like a git operation, a one-off command, a small file edit or an environment chore gets a one-tap question instead of a silent full plan. The safer full-plan option is the one already picked for you, and taking the quick option is a single click. See "When it is unsure, it asks" below for what that question looks like on screen.

This holds for your second and third messages too, not only the first. Sending a request puts a card on the board, but a card holding your own unrouted request is not a plan, so the project still counts as unplanned and your next message is judged by the same two-way rule. Once there is real planned work on the board, normal routing resumes and short requests go to the lighter lanes again.

This is deliberate. Message length is a useful hint about how big a change is only once there is an existing board to measure the change against. On a project with no plan there is nothing to compare to, and a short sentence is just as likely to be a tersely worded kickoff as a small job. So the length is still ignored here. What decides the lane on an unplanned project is whether the request reads like building something, not how much of it you typed.

If you would rather it just start building, the one-click override below still applies: pick a lighter lane from the announcement and it re-runs your request at that depth.

The proposed brief on a brand-new project

The first message into a brand-new project is the one that decides what gets built, and a one-liner like "a todo app" does not say much. So when your first message is short, Castforge usually holds it and shows you a Proposed brief card in the conversation before anything starts.

Which first message gets this card. The brief card belongs to the building case above: a first message that reads like building something is the one held for a brief. A first message that is clearly not building anything, such as a git operation or a one-off command, gets the one-tap lane question instead, so the two are alternatives rather than two answers to the same send.

Writing that brief takes a few seconds, so the conversation shows a short moving line while it happens. If things go quiet right after you press send, that is the brief being prepared, not a message that went nowhere. There is nothing to do but wait for the card.

This applies to a project that has a team. The brief card belongs to the part of Castforge that hands your message to the right team member, so a project running a single agent on its own never sees it: that project starts straight away, whatever the length of your first message.

The card contains a short brief written from your message, covering three things:

• the look and feel it is aiming for,
• what the first version actually includes,
• one or two questions only you can answer.

Nothing runs until you confirm. The work is held, not started and then corrected, so you are looking at a proposal rather than at something already half built.

The brief is editable, and that is the point. It is a text box, not a read-only summary. Change anything that is wrong, add what is missing, then press Start with this brief, and the run uses exactly what you left in the box. Your original message is shown underneath the box and is never thrown away: if you clear the box entirely and start anyway, Castforge falls back to what you typed in the first place.

You can also turn it down. Press Not now and the card goes away, and nothing is sent. What you typed is still sitting in the conversation, so you can send it again whenever you like: it is a fresh message, not something Castforge queued up and will deliver later.

The brief goes to the same team member your message was going to. Confirming the card does not re-decide who the work is for. It starts the same team member your original message was aimed at, and that holds when you aimed it at one particular team member rather than at the whole team: the brief follows your message, it does not get handed to whoever would normally pick it up. If Castforge cannot tell who your message was for, it tells you so and leaves the card where it is rather than picking someone.

Sending something else does not throw the card away. If you leave the brief unconfirmed and type another message, the card stays where it is. It describes a message that was never sent, so it is the only copy of that message Castforge is holding, and it is not something a later keystroke should be able to delete. Because of that, the ways it leaves are all deliberate: you confirm it, you choose Not now, a newer brief replaces it, or you clear the conversation or close the project.

A longer first message skips the card and goes straight to work. What decides this is the length of what you sent, and it is worth being plain about the limit of that: Castforge measures how much you wrote, not how complete it was. A short message that is already a perfectly good brief can still get a card. Confirming it is one click, so the cost of that is small.

The proposal is not guaranteed. The check can be skipped, in which case your message is sent exactly as you typed it and nothing is lost.

Two confirmations on a project that approves Lead plans

If you have turned on User approves Lead plans before execution (see "The board" for that setting), a brand-new project can show you two confirmations in a row, and they are not a duplicate of each other:

• The Proposed brief card asks is this what you want built, before any planning happens.
• The plan approval asks is this the right plan for it, after the Lead has drafted one.

Castforge does not switch off a gate you turned on, so if you asked to approve Lead plans, you still approve them. If you would rather see only one of the two, turn plan approval off for that project.

On Autonomous

On a project set to Autonomous, the brief card confirms itself and the run carries on with the proposed brief. That is the Autonomous setting doing what it is configured to do: an autonomous project runs without stopping for you.

It does not matter where you are in the app. The brief can be raised while you are on the Course board, on Home, on Mission Control, or inside a different project entirely, and an autonomous project confirms it and keeps going regardless. You do not have to be watching the conversation, or even watching that project, for the run to continue.

Three cases still park an autonomous project and wait for a click, and all three are deliberate:

• the project has only just been opened and Castforge has not finished loading its settings yet. Until it has, it treats the project as Careful rather than assuming Autonomous. The card confirms itself as soon as the settings land;
• the original message could not be matched to a team member. Castforge does not guess who a message was meant for, so it leaves the card for you;
• the card has been sitting unconfirmed for a while. A brief you left alone some time ago may not be what you want built any more, so Castforge does not start it on its own just because the project was set to Autonomous later. The card is still there and one click still starts it, so nothing is lost.

This is an Autonomous behavior only. On Careful and Balanced the card waits for your click in the conversation, as described above, and it waits wherever you happen to be. A brief raised while you are on Home, on Mission Control, or inside another project is still sitting there when you come back to that project, so nothing is lost, but nothing starts either until you open that project and confirm it.

Investigations are kept on disk

When Castforge routes your message into Investigate a bug, it does not just answer and move on. It keeps a running note for that investigation under .castforge/debug/ in your project, one file per investigation. Each turn adds your question, and when the turn finishes it adds what the agent found.

Asking another investigation question continues the same note rather than starting a new one, so a hunt that takes several questions reads back as a single thread. It survives closing and reopening the app too: reopen the project, ask again, and the note picks up where it left off instead of starting over.

Running actual work ends the current investigation. A fast edit, a quick task, or a full plan closes the note that is open, and your next investigation question starts a fresh one. That is the one behavior here worth remembering: if you want a hunt kept together, ask your investigation questions before you send the team off to change something.

Your question is recorded as you wrote it. What the agent found is scanned first and anything that looks like a credential is masked, because these files sit in your project and commit with your code.

A note is capped in size. When one gets long, Castforge starts a new one rather than letting a single file grow forever.

Only investigation turns write these notes. Asking for status, or asking a plain question the agent can answer from what it already knows, creates nothing on disk.

The one-click override

The routing is a suggestion you can change in one click. Every announcement carries a smart-alternative chip with the most likely alternative already chosen for you, for example "Plan it instead" on a fast edit, or "Just do it" on pipeline work. Next to it, a More affordance opens the full lane picker so you can send the message down any lane you like.

Choosing an override re-runs your original message from scratch at the depth you picked. Nothing is converted mid-flight, so a "Plan it instead" click gives you a clean plan of the same request, not a half-done edit wrapped in a plan.

When the override goes quiet

The routing decision was made against the board as it stood at that moment, and the chip re-runs your original message against the board as it stands now. Once those two are no longer the same picture, pressing the chip would act on a premise that has expired, so Castforge turns it off instead of leaving it armed.

Two things turn it off, and each says which one it was, in a short line under the announcement:

• The board changed after this was decided, so this can no longer re-run the same way. Something moved on the board after the routing choice was made, so the smaller path the chip offered is no longer the same job.
• This run already started, so it cannot be re-routed. The work is under way, and re-routing it now would mean running your request twice.

An announcement in this state keeps its place and its text, and its chip stays where it was rather than disappearing, so nothing shifts around under your cursor. The chip and the lane picker behind More both dim and stop responding, and the reason line is always on screen, so a control that has gone quiet never leaves you guessing why.

The announcement itself is still true: it says what Castforge did with that message at the time. If you want a different depth now, send the request again as a new message and it is routed against the board as it stands today.

When a fast edit turns out bigger

Not every request shows its true size up front. A fast edit can turn out to need more than a few files, a new dependency, or an architecture change. When that happens, Castforge does not force the bigger job through the small path. It promotes the request to a planned change automatically and announces the switch right in the conversation, for example "Bigger than it looks: planning it." so the change in depth is never silent.

A promotion carries the same one-click override as the initial routing, so if you would rather keep it small you can send it back down in a click. What gets promoted is your original request, not a half-finished change: the promotion re-runs your original ask from scratch as a clean plan, so you never get a partial edit wrapped inside a plan. Castforge also instructs the fast doer not to commit partial work before it promotes, so in the normal case your history stays clean.

When your ask is planned, the conversation says where it went

Planning an ask puts cards on the board, and the board is not always the screen you are looking at. So when a turn finishes having turned your ask into one new phase, Castforge adds one quiet line to the conversation naming that phase, how many cards it holds, and what it is queued behind. For example: Planned as "Authless shared workspace", 3 cards. It is queued behind "Plan materialization reconcile".

If nothing is queued ahead of it, the line says it runs next instead. If the new phase sits outside the milestone that is running now, the line also tells you the run pauses at each milestone boundary for your review, because that is the default and it is the part people are most surprised by.

The line makes a claim about POSITION, never about time. It tells you where your work sits in the order, not when the clock will reach it, because on a project that pauses at milestone boundaries a promise about when would simply be untrue.

Want it sooner? Ask for the same thing again. Castforge now sees it on the board and answers with the offer card described below, which has a Move it to the front choice.

What this does not do

• It does not appear for every turn. Only a turn that materialized your ask into exactly one new phase says anything. A turn that planned nothing says nothing, and a turn that created several new phases at once also says nothing, because nothing distinguishes which of them is the thing you asked for and a line that hedged about where your work went would be worse than no line at all.
• The line does not survive a reload. Like every other one-line notice in the conversation, it belongs to the session. The landing itself is kept: it is written to the project's decision record, so the Memory tab and your project's decisions file still answer "where did that ask go" after a restart.

Asking again for something that is already on the board

If you ask for something the board already has planned, Castforge does not plan it a second time. It answers you in the conversation instead, naming the phase the work is planned as and what it is queued behind, for example: "Dark mode" is planned as Interface. It is queued behind "Auth revamp". Nothing new is put on the board, no team is sent off, and no duplicate phase or card is created.

You get one answer, not two. Castforge normally announces its routing choice as a short line in the conversation, and when an ask turned out to be already planned that line used to stay on screen anyway. The result was one message with two opposite claims stacked on top of each other: a line reading "This is pipeline work: planning it." directly above a card saying the work was already planned and nothing had been started. The routing line is now taken back the moment the ask is parked, so the card naming where the work already sits is the only answer you see.

The answer is not only a statement. It comes with two choices:

• Move it to the front puts that work at the front of the queue so the team picks it up next.
• Leave it where it is changes nothing. The board is untouched and nothing is re-planned.

Either way the card collapses to one short line recording what happened, so the outcome stays in the conversation. If the work was already at the front, it says so rather than claiming a move it did not make. If the board changed underneath the offer and that work is no longer there, it says that instead. If the move was refused, it says the board did not change rather than reporting a success.

Ask a second time and it recommends moving it. On the second matching ask, the answer adds a line saying how many times you have asked and marks Move it to the front as the recommended choice. It is the same card with one thing turned up: the two choices are unchanged, and Leave it where it is is still there and still does exactly nothing to the board.

The count is kept with the project, so it survives closing and reopening the app and a third ask never behaves like a first. Accepting the offer resets it, because your ask was resolved. Declining does not reset it, because declining resolved nothing.

Reporting a bug about something already built goes to the front instead. If the thing you are describing is work the board shows as finished, Castforge reads that as a defect report rather than a new feature ask, and the fix is placed at the front of the current milestone rather than behind everything queued after it. You get one quiet line in the conversation saying so. See "The board" for what that placement actually does and what happens when it is refused.

What this does not do

This corpus feeds the in-app support bot as well as this page, so the limits are worth stating plainly rather than leaving you to discover them:

• Matching is by title and by keyword. If you word the ask quite differently from the phase on your board, it may not be recognised, and Castforge simply plans it as usual. That is the safe direction to fail in: the cost is one redundant planning turn, not a request that goes nowhere.
• An ask that could plausibly mean two things matches neither. When more than one item on the board is a credible match, Castforge deliberately declines to pick, and your message routes normally. It would rather plan something twice than answer you about the wrong work.
• A pending offer does not survive closing the app. The offer lives in the conversation for that session. If you close Castforge with an unanswered offer sitting there, it is gone when you come back. Asking again brings it straight back, with the repeat count intact.
• A bug report only jumps the queue when the board says that work is already built. The same words about a feature that does not exist yet are treated as a feature ask and planned normally, because there is nothing built to be broken.

When it is unsure, it asks

If more than one lane is a real possibility, Castforge does not guess. It asks one quick multiple-choice question ("How should I handle this?") with the two or three most likely lanes as options, and the safest option preselected. You pick one and it proceeds. This is a single question, not a back-and-forth, so you stay moving.

Bounding an ask: do this, do not plan it yet

Sometimes you want one specific thing done and nothing after it. You can say so in plain language and Castforge respects the boundary. Add an explicit stop to your request, for example "create three milestones, do not plan yet" or "just create the milestones", and Castforge does exactly the asked action and stops there. It does not research, does not draft a plan, and does not expand the board with follow-on work.

When a bounded ask finishes, you see a short plain confirmation in the chat, for example "Done. Stopped here as you asked." That line is your signal that the boundary held: the thing you asked for happened, and nothing else was started.

A boundary works in every permission mode, including Autonomous. A stop you set by hand wins over the usual keep-going behavior, so even an unattended run halts where you told it to.

The boundary applies to the ask you just sent. It stops the work there; it is not a durable setting that outlives a restart. If Castforge restarts in the middle of the work, re-send the bounded request and the boundary applies again.

Typing while a run is in progress

You do not have to wait for the team to finish before you type. A message you send while a run is in progress is held in a visible queue and goes out at the next natural stopping point, so nothing you type is lost and nothing barges into work that is already running.

Your message appears in a queue right away

Messages waiting to go out are listed in a compact stack directly above the composer, under a count header that reads Queued (2). The stack is there only while something is waiting: at zero queued messages it disappears entirely rather than leaving an empty widget between the conversation and the input.

Each row is one queued message on a single line (hover it to read the whole thing) with an ✕ on the right. Clicking the ✕ removes that one message from the queue. It is not a Stop: the work that is running is untouched and the other queued rows stay where they are. If the removal fails for any reason, Castforge tells you and leaves the row in place rather than pretending it went.

Under the rows, a one-line caption tells you when the next message goes out:

• Next one runs when the current work settles. while a run is in progress.
• The run stopped, so the next one goes out with your next message. after you stop the run.
• Restored from your last session. Confirm to let them run. after a restart. See "Recovery and troubleshooting" for what a restored queue needs before anything runs.

One queued message goes out at each settle point

Each time the current work settles, Castforge takes exactly one message off the queue, not the whole queue at once. That is deliberate: you get to see how the first one lands before the next one goes, and you can still remove anything you have changed your mind about in the meantime.

A message that comes off the queue is routed exactly like a message you just typed. It gets its own routing announcement in the conversation, with the same one-click override chip and the same full lane picker, so a queued message is never dispatched at a depth you cannot see or change.

When Castforge asks what should happen with your message

On a project with a team of several roles and a board that is already planned, a new ask is not assumed to be a continuation of the work in flight. Castforge asks one quick multiple-choice question in the conversation, "What should happen with this message?", with your message shown above five options:

• Queue it for after this run is the recommended default: hold it in the queue and run it at the next settle point, disturbing nothing in flight. This is the option a bare Enter selects, so pressing Enter can never pause your run, re-plan your board, or drop your ask.
• Fix it in the card in flight folds your message into the task that is already running, creating no new card. See "The board" for what a fold does and what it tells you.
• Just save it for later writes it to project memory now. Nothing runs and nothing is queued.
• Add it to this milestone hands it to the Lead as new work inside the milestone you are running.
• Interrupt and run it now pauses the active card, runs your message as a one-off, then picks up where it left off (the same one-off as Run now on the board).

A plain "continue" or "resume" is not treated as a new ask: it re-engages the work already on the board. A single-agent project, and a project whose board has not been planned yet, send normally with no question.

Dismissing the question does not throw your message away. An unanswered or dismissed question falls back to the same recommended default, so the ask ends up in the queue rather than nowhere.

In Autonomous mode Castforge takes the recommended default on its own and shows no question at all, so an unattended run is never paused or re-planned behind your back. The queued stack is then your view of what is waiting.

The queue on the home screen

The message box on a home-screen project tile feeds the same queue. Type into a tile while that project is running and the message is queued and visible rather than sent immediately: the tile shows a Queued (n) chip, so from the home screen you can see that something is waiting on a project you are not currently inside.

The chip stays after the run stops, so a queued message never quietly disappears from the home screen, and it turns coral when the queue came back from your last session and is waiting on your confirm.

A broadcast reaches running projects too. Each running recipient's copy joins that project's queue. The summary line counts how many projects accepted the message, which is deliberately not a delivery claim: a running project accepted it into its queue rather than running it now. A project that refused the message (for example because its queue is full) gets its own error naming that project.

When an older message is no longer current

A conversation is a record, so Castforge does not delete anything from it. But a message can stop being true while it is still on screen: a seat says Done. and then starts another turn, and both statements sit in the same transcript with nothing to say which one is current.

The older message now says so on its own face. It keeps its full text and its place, its border switches from solid to dashed, its text dims, and a small chip appears on it reading No longer current, followed by the reason: the seat started another turn after this. The marker looks the same every time. It does not count, rank, or change with age, because there is nothing different to tell you.

Only the seat's own later turn marks it. Another seat starting work says nothing about whether this seat's Done. still holds, so it leaves the message alone. The newest message is never marked, because nothing has overtaken it yet.

Conversation styles: Developer, Plain, Mentor

Castforge can present the same work three different ways. The conversation style changes how much technical detail you see, not what the agent does under the hood. Pick the one that matches how you like to work.

• Developer is the default. You see raw diffs with line numbers, the exact shell commands, and full tool activity. The composer tagline reads "Auto-applying small edits, plan first for big ones."
• Plain hides the code. A file change shows up as a friendly summary like "Edited 3 files" with Looks good, Try again, and View code buttons. Click View code to expand the full diff inline when you want it. The tagline reads "Plain English mode, no code shown."
• Mentor is Plain plus a short teaching note that explains the agent's reasoning. The tagline reads "Mentor mode, I'll explain my reasoning."

You can set a default conversation style in app settings (see the settings reference), and many builds let you switch it per project from a Developer / Plain / Mentor toggle in the conversation header.

How the agent proposes and you apply changes

When the agent wants to change a file, it does not edit your disk silently. It shows the change as a diff block in the conversation, with the file path, an addition/deletion count (for example, +12 −3), and the changed lines.

In Developer style a pending diff shows two buttons:

• apply writes the change to the file on disk.
• reject discards the proposed change.

In Plain and Mentor styles the same diff appears as a summary with Looks good, Try again (regenerate the change), and View code.

Once you act on a diff, the buttons are replaced by a small status badge: a green applied, a red rejected, or ↺ reverted if you later undid it.

What "Apply" actually does

Apply does three things in order. It captures the current contents of the file first (so the change can be undone later), records the change to your project's local history, and then tells the agent it may write the file. The agent makes the edit and the diff badge flips to applied. Because the pre-change contents were saved, you can roll an applied change back with /undo.

Why some Apply buttons are greyed out or missing

You may see a diff with no apply/reject buttons and a muted line that reads "Session ended. The diff is no longer actionable." This happens when the agent session that produced the diff is no longer running, usually after you restarted Castforge. The transcript is replayed from history, but the live process that would receive your decision is gone, so the buttons are hidden rather than left as dead controls. Send a new message to start a fresh session and the agent can re-propose the change.

A diff may also already show applied with no buttons if it was auto-approved by your permission level (see below).

Slash commands

Type / at the start of a message to open the slash command popover. Castforge groups commands into tiers: built-in Castforge commands, Plugins (when a plugin publishes commands), and Agent skills (commands the agent's own CLI provides). The built-in commands always take priority.

The seven built-in commands are:

To use a command, pick it from the popover (it fills into the composer) and press Enter, or just type the whole command and send.

Agent skills come in two flavors. Operational skills (build, launch, test, and similar one-shot actions) run immediately as a single execution turn on the targeted role, so "launch the editor" just runs. Planning skills (multi-step workflow orchestrators) still go through the Lead's plan cycle so multi-step work is planned before it runs.

The files tree

The FILES panel on the left shows your project as a collapsible tree. It is resizable: drag its right edge to widen or narrow it.

Browsing and opening

• Click a folder row to expand or collapse it. By default the tree starts collapsed, automatically opening only the folders that contain changed files, so it reads like a clean editor.
• Click a file row to open it in the editor pane (see "The editor" below).
• The tree shows every file in your project, just like VS Code's explorer, including dotfiles and gitignored files. Gitignored entries appear dimmed and are never counted as changes. Heavy folders like node_modules stay collapsed and their contents are not listed. The eye button in the FILES header hides or shows ignored files. Only the .git folder is never shown.

Git status marks

Files that differ from your last commit get a colored letter badge:

• M (amber) for modified.
• A (green) for newly added.
• D (red) for deleted.

A collapsed folder that contains changes shows a small colored dot so you can spot changes without expanding it. The footer at the bottom of the tree shows your current branch and a running tally of additions, modifications, and deletions (or "No changes" when the tree is clean).

The editor

Opening a file puts it in the editor pane, a real code editor (not just a viewer) built for quick navigation:

• Go to line: press Ctrl+G (Cmd+G on macOS) to jump straight to a line number.
• Quick open: press Ctrl+P (Cmd+P on macOS) while the editor is focused to fuzzy-search every file in the project by name and jump to it. You can also open it from the Search files button in the FILES header.
• Jump from chat: click a file path on a diff in the conversation and Castforge opens that file in the editor at the edited line, so you see the change in context.
• Save and close: Ctrl+S (Cmd+S) saves the active tab; Ctrl+W (Cmd+W) closes it. A tab with unsaved edits shows a dot and asks before closing.

The editor coexists with the agent while it works. If the agent changes a file you have open and you have no unsaved edits, the editor quietly reloads to the new contents so you are always looking at what is on disk. If you do have unsaved edits when the agent (or any other tool) writes that same file, Castforge never silently overwrites your work: it raises a Conflict on {file} prompt where you choose Keep mine, Take theirs, or Show side-by-side to compare first. Your version is preserved either way so you can recover it later.

Creating, renaming, deleting, and revealing files

Right-click any file or folder for a context menu. The available actions depend on what you click:

• On a folder: New file..., New folder..., Reveal in file explorer, Open in terminal, Copy path, Copy relative path, Rename..., Delete.
• On a file: Open, Reveal in file explorer, Open in terminal, Copy path, Copy relative path, Rename..., Duplicate, Delete.

New file and New folder prompt for a name and create the item inside the selected folder. Rename prompts for a new name. Delete asks you to confirm, then moves the item to the Windows Recycle Bin (for a folder, everything inside it goes too), so it is recoverable. Reveal in file explorer opens Windows Explorer with the item selected. Copy path copies the full path; Copy relative path copies the project-relative path.

What a run commits to git

While your team works in your project's main folder, Castforge commits as it goes. When a card finishes, the work that turn produced is committed, so finished work lands in your git history instead of piling up loose in the folder.

Five things follow from that:

• One commit per turn, not one per card. Two cards that finish in the same turn share a commit. The subject names the role and how many cards finished, for example "castforge: coder completed 2 cards", and the body lists the card ids and how many entries the commit carried. No path is ever put in the message.
• A turn that finishes no card commits nothing, and its work waits for the next commit rather than being left behind. Plenty of turns end without a card finishing: a reviewer reading, a researcher, a coder part way through something. Castforge does not put a commit on your history for those, but it does note what they wrote, and the next turn that does finish a card commits that work along with its own. So a commit can carry a couple of turns' work, and the count of entries in its body is how you tell. Nothing an agent writes is stranded just because the card it belongs to took more than one turn.
• The commit is authored by the git identity this project is configured with. With GitHub connected, that is your connected account. If no identity is configured, Castforge does not commit at all rather than authoring under a name nobody chose, and it says so on the project tile. See "Connecting GitHub and other services" for where to set one.
• Entries you already had uncommitted stay exactly as they were. Castforge commits the turn's work, not the contents of your folder. Anything you had in progress before the run started is left where it is, for you to commit or discard. That holds for work an agent wrote in an earlier turn too: if you edit one of those files before it has been committed, Castforge notices the contents changed and leaves it for you rather than committing it. "Recovery and troubleshooting" explains how Castforge decides what belongs to a turn, and the one case where that decision cannot tell your work from an agent's.
• The project state Castforge keeps under .castforge is committed along with that work, which is what those files are for: they read back later as a record of what actually happened, reviewable alongside your code.

Cards that run in their own isolated workspace keep the behavior they always had: their work is committed on the card's own branch and merged into your project when it lands. What is described here is for work done directly in your project's main folder.

Project memory (the STATE digest)

The Memory tab (in the workspace view toggle across the top) is where Castforge keeps what it remembers about your project. It opens on a Project State summary, the digest, shown as the main view above a scrolling activity feed of everything that has happened in the project.

The digest is not just a display. It is the same summary every fresh card starts from, so the sub-hint under the heading reads "This is the summary every fresh card starts from. Edit it to correct what the agents remember." When you edit the digest, you are editing what your agents read at the start of the next piece of work. If the project changed direction and the agents keep acting on an old assumption, fix it here. For example, if you moved off Supabase to another database, edit the relevant section to say so and the next card will start from the corrected memory.

Memory is not the only record Castforge keeps. Each time a phase finishes it also leaves that phase's plan slice, completion summary, and verification verdict on disk under .castforge/phases/, as plain files you can read or commit alongside your code. They are committed with the work of the turn that produced them (see "What a run commits to git" above), so they are already in your history rather than waiting for you to notice them. See "Project memory and the decision ledger" for what those files hold.

The six sections

Project State is organized into six fixed sections, always in this order:

1. Stack is the languages, frameworks, and tools the project runs on.
2. Built & Wired is what already exists and is connected end to end.
3. Key Decisions / Invariants is the choices and rules that must hold across the whole project.
4. Current Focus is what the work is about right now.
5. Seeded Creds / Test Logins is throwaway dev or test logins a coder needs to run the app.
6. Open Questions is what is still undecided or needs your input.

Every section always appears, even when it has nothing in it yet. An empty section shows a short hint like "Nothing recorded yet. This fills in as the project progresses, or you can add it now," so you can either wait for the work to populate it or fill it in yourself.

Editing and pinning a section

Each section is editable in place. Click the Edit section control (the pencil), make your changes in the text box, and press Save section to keep them or Discard changes to back out. Your edit is durable: the next card reads the new text.

You can also Pin a section. A pinned section is protected: automatic memory updates never overwrite it. Pin a section when you have written something you want to stay exactly as you left it, no matter what the agents do later. A pinned section shows a filled pin icon and a small Pinned tag. Editing a section pins it automatically, on the assumption that a change you made by hand is one you want kept. You can unpin at any time to let Castforge maintain the section again.

The Seeded Creds section is for test logins only

The Seeded Creds / Test Logins section can hold throwaway dev or test logins that a coder needs to run and check the app, for example a seeded test user and its dev password. It is deliberately for that and nothing more.

Never put real secrets, provider tokens, or production passwords in this section (or anywhere in the digest). The digest is read by your agents at the start of every card, so treat it like something the agent will see. Castforge excludes real provider tokens and production credentials by construction, and its empty-state hint reminds you: "Add any throwaway dev or test logins a coder needs. Never put real secrets, provider tokens, or production passwords here."

Where a fact came from (View source)

Many digest lines are derived from the project's own history. Where a section came from a specific activity entry, it shows a View source link that jumps you to the entry in the activity feed below, so you can see the change or decision that produced it. This is the drill-in path: the digest is the summary, the feed is the full record.

Proposed memory updates at the end of a phase

When a phase of work finishes, Castforge may propose an update to your project state. It appears as a Proposed memory update banner at the top of the Memory tab, saying "The last phase suggested changes to your project state."

The banner then shows you what it is actually proposing, before you decide: a line naming how many lines are new and which sections they land in, followed by the first few new lines themselves. Only lines that genuinely changed are counted and shown, so a two-line addition to a long section reads as two lines rather than a rewrite of the whole thing. If there is more than the preview shows, the banner says how much more and points you at Review.

You then have three choices:

• Review expands the proposed changes so you can read exactly what is being added or removed before deciding.
• Apply accepts the update and folds it into the digest. You see a "Project state updated" confirmation.
• Dismiss discards the proposal. It only throws away the suggestion, not your existing digest, and confirms with "Suggestion dismissed."

If a proposal is waiting, a count appears on the Memory tab so you notice it even while you are on another tab. The number is how many sections the proposal touches. Hover it and Castforge tells you which sections and how many lines are new, so you can decide whether it is worth switching tabs without switching tabs.

In Autonomous permission mode, Castforge applies these updates for you without asking, and only to sections you have not pinned. Pinned sections are always left alone. In Careful and Balanced modes, an update waits for you to Review, Apply, or Dismiss it.

Permission modes: Careful, Balanced, Autonomous

Permission modes decide how often the agent stops to ask before acting. The control is a three-way toggle and the setting is saved per project, so one project can run hands-off while another asks about everything.

• Careful asks before commands and risky actions. Shell commands, network access, and anything reaching outside your project folder stop and ask. File edits inside your project folder are applied as the agent works, and every one is recorded so you can review it in the conversation and roll it back with /undo.
• Balanced asks only for product decisions. Routine tool actions (file edits, shell commands) are auto-approved, but the agent still asks when it needs a real decision from you.
• Autonomous shows you no permission prompts at all. Not for work inside your project, not for work outside it, not for credentials, and not for actions that spend money or cannot be undone. This changed on 2026-08-05 and it is a real change in what you are agreeing to. Read "What Autonomous does not ask about" below before you leave a run unattended.

What Autonomous means as of 2026-08-05. An agent running on Autonomous can read anything on your machine that you can read, including your SSH keys, your saved cloud credentials, and your AI CLIs' own sign-in folders, and it can send what it reads out over the network. It can deploy to production, migrate a database, publish a package, and buy a domain, with no confirmation at any point.

Castforge still checks every one of those things and still writes down what happened, so you can reconstruct an unattended run afterwards. It just does not stop.

If that is not what you want, use Balanced. Balanced auto-approves routine file edits and shell commands and still stops for everything on the sensitive list below. It is the setting most people should leave a long run on.

GitHub Copilot and Gemini seats now ask you too

If you run a Copilot seat, or a Gemini seat on its native protocol, you will see permission prompts you did not see before. This is a fix, and it is worth knowing what changed.

Most agents ask Castforge for permission before they act, and Castforge applies your permission mode to the answer. Copilot, and Gemini when it runs on its newer native protocol, talk to Castforge over a different connection. On those two, the permission question was being answered inside that connection before your project's setting was ever consulted. The practical result: a Copilot or native-protocol Gemini seat ran as though every project were set to Autonomous, no matter what you had chosen. If you set a project to Careful and watched a Copilot seat edit files without asking, that was this.

That is fixed for everything the agent asks about, and one thing it does not cover is worth knowing before you rely on Careful.

GitHub Copilot does not ask before editing files. It asks before running shell commands, and Castforge applies your permission mode to those. For a file edit it raises no permission request at all, so there is nothing for Castforge to answer. We checked this directly against the Copilot CLI rather than inferring it, and there is no Copilot setting that changes it.

This is not unique to Copilot. On every agent, a role that can write applies file edits inside your project folder without a per-edit prompt, at every level. What Careful and Balanced gate is commands, network access, and anything reaching outside your project. Edits are always recorded and always reversible with /undo.

On those seats a permission request now travels to Castforge, gets the same treatment as every other agent's, and your answer travels back.

What you will notice:

• On Careful and Balanced, these seats now stop and ask. The card looks like any other permission card and you approve or deny it in the usual place.
• On Autonomous, nothing changes at all. These seats showed no prompts before and they show none now. The difference is that they now go through Castforge's checks first and get written to the log on the way past, so an unattended Copilot run finally leaves the same record every other agent leaves.
• Denying is safe. Refusing one action ends that action, not the run. The agent is told no and carries on with the rest of its turn.
• If you never answer, the action is refused after five minutes. A card nobody clicks used to leave the agent waiting with no way out. It now gets a refusal once the five minutes are up, and the run continues. Castforge records that the time ran out rather than recording it as though you had said no, so the log still tells you whether anybody actually decided.
• Cancelling a turn releases it immediately. If you cancel while one of these cards is open, the agent is told the turn was cancelled rather than being cut off mid-question.

One rough edge, stated plainly rather than left for you to discover:

On these two seats, "Allow always" does not stop the asking yet. Castforge treats every request from them as the strictest kind, and the strictest kind deliberately ignores saved answers. The reason is that the connection does not tell Castforge the NAME of the tool being run, only a broad category the agent picks for itself. There is nothing specific enough to attach a saved answer to, and attaching one to the whole category would mean a single click standing in for every future action of that kind. So on Careful and Balanced these seats ask every time. If that is too much for a long run, Balanced does not help here and Autonomous does, with everything that means; the alternative is to run those tasks on an agent whose connection reports tool names, such as Claude or Codex.

This is a known limit and not the end state. It is written down here because a prompt you cannot silence is worth telling you about before you meet it at hour two of a run.

What Autonomous does not ask about

Short answer: nothing. On Autonomous there are no permission prompts.

That is the whole rule, and it is worth stating before the detail, because the detail used to be a list of exceptions and no longer is.

Concretely, on Autonomous an agent can, with no prompt and no pause:

• Read any file your user account can read. Your SSH private keys, your .aws and .kube credentials, your .npmrc token, your browser profile folders, your other Castforge projects, and your Claude Code, Codex, Gemini, Cursor and Copilot sign-in folders.
• Send what it read somewhere. A web fetch, a curl upload, an scp, an rsync to a remote host. Reading a credential and posting it to a URL is two ordinary steps, neither of which stops.
• Deploy to production, migrate your database, publish a package, and buy a domain. These are the actions Castforge classes as irreversible, public, or paid. On Autonomous they complete with no confirmation at any point.
• Run something with elevated privileges, delete things outside your project, and change global settings such as your git identity.

What you still get is the record. Every check that would previously have stopped the run still runs, still decides, and still writes a line to the Castforge log naming the rule that matched and the folder the action actually resolved to. So the question "what did last night's run touch?" still has an answer. The question "may it?" is one Castforge stops asking when you choose Autonomous.

On Careful and Balanced, none of the above changed. The sensitive list below still stops those two levels exactly as it always has.

Reading, and why the prompts went away in the first place

Even before this change, reading was not treated as an interruption. Web search, fetching a page, reading a file in your project, and searching your project's files all ran without a prompt on Autonomous, because none of them change anything on your machine. Research-heavy work used to stop for a click on every single page an agent wanted to read, which is not a safeguard: a run of identical prompts trains you to click Allow without reading, and then the one prompt that really matters looks exactly like the ones you just dismissed.

Documentation lookups count as reading too. Some agent tools come from connected MCP servers rather than from the agent itself, and a few of those are pure documentation lookups: you give them a library name and a question, they give you back documentation text. Castforge keeps a short, built-in list of the ones it has reviewed and considers read-only, and those run without a prompt on Autonomous, the same as fetching a web page. The context7 documentation tools are on that list today.

The list is Castforge's, not the server's. An MCP server cannot mark its own tools as safe and get a quieter prompt for it, and adding a tool to the list is a change we ship, reviewed one tool at a time. So a server you connect gets no special treatment just for saying it is harmless: on Careful and Balanced, anything Castforge has not reviewed still asks.

What can still stop an Autonomous run

"No permission prompts" is precise, and it is narrower than "Autonomous never interrupts you". A few things can still hold an unattended run, and none of them is a permission decision. Knowing the difference is what lets you tell "it is waiting on me" apart from "it is broken":

• A design question from the role that plans your work. Autonomous delegates execution, not design judgment. When the role that writes your plan asks you a genuine question ("Postgres or SQLite?"), that question waits, on purpose, in every mode. Every other role's questions are answered for you on Autonomous.
• A hand-set boundary. If you said "create three milestones, do not plan yet", the run stops there, in every mode. See "Bounding an ask" above.
• Another project is already running. If a second project holds the resource this one needs, Castforge asks what to do. That is a scheduling conflict, not an authorization, so answering it for you would start two runs over the same files rather than grant a permission.
• The first switch to Autonomous. The one-time "Switch to Autonomous?" confirmation is what establishes the level, so it cannot itself be skipped by the level. It appears once per project.
• Rollback buttons you press yourself. Restore in place and cascade undo, when you start them from the board, confirm every time in every mode. See "Recovery and troubleshooting". The agent-facing versions of those two actions do not confirm on Autonomous, which is covered in the always-ask list below.

If an Autonomous run looks idle and none of the above applies, it is not waiting on a permission card, because there are none. See "Recovery and troubleshooting" for where to look next.

The sensitive list, and what it does at each level

This changed twice, and the honest version matters more than the reassuring one.

Castforge used to stop for any action that reached outside your project folder, even on Autonomous. In practice that meant an unattended run stopped for things nobody would have wanted to be asked about: a read-only lookup against a public package registry, copying a file to a scratch folder, a --output path that lands in a folder next to the project. In one measured run it stopped four times in half an hour and left a role waiting more than two minutes for a click. None of those was a product decision. So work outside the project folder started running unattended unless it touched something on a built-in sensitive list.

Then, on 2026-08-05, the sensitive list stopped stopping Autonomous too.

The list still exists, and it is still the most useful thing on this page. It is still evaluated on every single action, at every level. What changed is only what happens when something matches:

• On Careful and Balanced, a match stops the run and asks you. Unchanged.
• On Autonomous, a match runs, and writes a log line naming the rule and the resolved folder.

So read the list below as the things Castforge writes down, and, if you are on Careful or Balanced, the things it stops for:

• Credentials and keys. SSH and GPG directories, cloud credentials for AWS, Azure, Google Cloud and Kubernetes, Docker and GitHub CLI logins, .npmrc, .netrc, .git-credentials, and private-key files anywhere by name or extension.
• Windows credential storage. The Credential Manager, the DPAPI key store, the certificate stores.
• Browser profiles. Chrome, Edge, Brave, Firefox and friends, which is where cookies and saved passwords live.
• Your AI CLIs' own config. The Claude Code, Codex, Gemini, Cursor, Copilot and similar directories. Castforge never reads their sign-in tokens and will not let an agent do it either. A write there matters just as much, because it would change what the next turn runs.
• Castforge's own data. The database that holds your board, your project memory and your saved permission answers, plus the log folder and the installed app itself.
• Your other projects. An agent working in one project does not get to write into another. Castforge knows your project folders and treats them as off limits.
• System locations. The Windows folder, Program Files, ProgramData, the Startup folder, the registry, scheduled tasks, services, and the equivalents on other systems.
• Sending your files somewhere. Reading a public URL is ordinary. Uploading a local file is not: curl with a file body or an upload flag, wget --post-file, scp, sftp, rsync to a remote host, ssh, and raw socket tools. This is the row that matters most on Autonomous, because it is the one that pairs with the credential rows above: reading a key is one step, sending it is another, and on Autonomous neither stops.
• Deleting or re-permissioning things outside the project. Cleaning your own build output is ordinary work. Removing somebody else's folder is not.
• Running as another user. sudo, runas and friends, because elevation steps over every other line on this list.
• Anything irreversible, public, or that costs money. A production deploy, linking or creating a Supabase project, a database migration, buying a domain, attaching a domain to a live deployment, publishing your design system to the cloud, creating a cloud design project, resetting your working tree to an earlier point, reverting a task and everything that depended on it, and starting a new milestone. Also any brand-new Castforge action that has not yet been given a risk level, which is deliberately treated as the riskiest kind. These stop and ask on Careful and Balanced. On Autonomous they run with no confirmation at any point, and the same is true whether the agent uses a built-in Castforge action or types the equivalent command into a shell.
• Anything Castforge could not work out. If a command mentions a real path Castforge cannot resolve, for example one built from an environment variable that is not set on your machine, or one whose folder comes from the output of another command, it treats that as leaving the project rather than guessing, and on Careful and Balanced it asks. This applies only to things that genuinely look like file paths: a search pattern, a text format and a loop variable are not paths. See "Patterns and formats are not paths" below.
• Any tool from a connected MCP server that is not on the reviewed read-only list. Deliberately the cautious default, so a newly connected server is never trusted by accident.

On Balanced, everything else outside your project folder runs, and everything on the list above stops and asks. That is a real trade and it was made on purpose: a run of identical prompts trains you to click Allow without reading, and then the one prompt that really matters looks exactly like the ones you just dismissed. On Careful you are asked before every command on this page, reads included. On Autonomous nothing on this page stops the run.

Every action that runs outside your project folder without asking is written to the Castforge log with the exact folder it resolved to, so you can always go back and see what an unattended run touched. On Autonomous that log is the only record there is, which is why it was kept rather than removed along with the prompts.

About the prisma init --output ../app/generated/prisma case specifically: Castforge reads a command the way your shell would, from your project folder, so a path starting with .. is treated as leaving the project. It cannot know that Prisma re-interprets that path from the schema folder and ends up inside your project after all. On Balanced that no longer costs you a prompt, because the folder it lands in is not on the sensitive list. On Careful you are still asked, exactly as before.

What counts as leaving your project folder

This changed for every mode, Careful and Balanced included, and it is worth a minute of your time.

Castforge reads a shell command the way your shell would, starting from your project folder. A plain name like src/app.ts is inside the project. A path that climbs out with .., or one that starts at a drive letter, is outside it. That much has always been true.

What Castforge used to miss is a path that starts at your home folder or at a Windows environment variable. ~/.ssh/id_rsa, %APPDATA%\Castforge, and $env:USERPROFILE\.ssh all point far outside your project, but none of them looks like it does until the shell expands it. Castforge read all three as ordinary in-project work and let them run without asking, in every mode.

That is fixed. Castforge now expands a leading ~ and the environment variables that name a location on your machine (your home folder, AppData, ProgramData, Program Files, the Windows folder, the temp folder and the like) before deciding, so a path rooted at any of them is recognised as leaving the project.

What this means for you:

• On Careful and Balanced you will now be asked about these where you were not before. That is the point. A file in your home folder is not in your project, and Castforge should have been asking all along.
• On Autonomous the sensitive list is still evaluated, and it no longer stops anything. Reading ~/.ssh/id_rsa runs. What you get is a log line recording that a credential-shaped path was read and which folder it resolved to. Writing ~/scratch/notes.txt runs too, as it did before. This is the sharpest example on the page and it is stated plainly on purpose: if reading your private key unattended is not acceptable to you, Autonomous is not the setting you want.
• Nothing about ordinary work inside your project changes. Relative paths, ./scripts/build.sh, plain file names and commands that name no path at all are untouched at every level.
• A variable Castforge does not recognise is left alone rather than guessed at. Loop variables and shell placeholders such as $_, $f and $p are not treated as paths, so an ordinary pipeline or a URL built from a variable does not start prompting. The trade is stated plainly: a path hidden entirely inside a variable Castforge cannot resolve is not caught. Castforge will not invent a prompt for every $ in a command line to pretend otherwise.

A file in your project counts as in your project, whichever workspace asked

When the team runs cards at the same time, each card builds in its own isolated workspace, a separate copy of your project on disk. See "The board" for how those copies are created, reviewed, and merged back onto your branch.

Castforge used to answer "is this file in my project?" by measuring the path against the copy the asking role happened to be running in. So a role working in its own copy that touched a file belonging to your project could be judged as reaching outside the project, purely because the path pointed at your project folder rather than at the copy. Two edits from one recorded session show the shape of it: a change to app/globals.css and a change to .gitignore, both plainly inside the project, were both treated as work outside it and written to the log as such.

That is fixed. Castforge now judges a path against the project it belongs to, rather than against whichever copy is asking. What this means for you:

• On Careful and Balanced, an edit to a file in your project no longer draws an outside-the-project prompt just because the role was working in its own copy. For a working role it is approved for you as ordinary in-project work, the same as the identical edit made from your main copy. On Autonomous it was already running; what changes there is the log line, which now records it as ordinary in-project work.
• The log of work outside your project stops naming things that were never outside it. That record is what you read to see what an unattended run touched, so it is only worth reading if everything in it genuinely went outside. It now is.
• A file that belongs to your project gets the same answer wherever the request came from, whether that is one card's copy, another card's copy, or your main copy: the same decision and the same log line.

What did not change:

• Genuinely external paths behave exactly as before. A path that really does leave your project is judged by the same rules described above and below: the sensitive list, the deny list, and the risk tier for that kind of action. Nothing was added to what runs unprompted.

• Autonomous is unchanged in what it stops for. The sensitive list still applies in every mode, and the always-ask actions (a production deploy, a migration, a publish, a purchase) still ask in every mode.

  Correction, 2026-08-05. That sentence was true when it was written, and it stopped being true on 2026-08-05. Autonomous now stops for nothing: the sensitive list is still evaluated and logged at every level, but the always-ask actions no longer ask on Autonomous. The rest of this section is about which project a path is measured against, and that part is unaffected at every level.

• The copies stay isolated. A role working in one card's copy still writes its own files there, and another card's copy is still outside it. This changes which project a path is measured against, not which files a role can reach.

It was measured against real recorded tool calls before it shipped. Exactly three of them changed, all three of them in-project edits that had been recorded as outside work, and nothing that previously asked you or was refused became automatic.

Patterns and formats are not paths

A $ or a % in a command usually has nothing to do with a file. Castforge used to treat any of them it could not expand as a path it had failed to resolve, and asked. On a research-heavy run that added up fast: one measured session took eight approval prompts in fifteen minutes, every one of them for something that named no file at all.

Castforge now asks the first question first, which is whether the thing is a path in the first place. These are recognised as ordinary text and no longer prompt:

• Search patterns. In grep -E "^\s*$" notes.txt the $ marks the end of a line. It is part of the pattern, not a file name.
• Output formats. In curl -w "%{http_code}" the %{...} is curl's own vocabulary for what to print.
• Encoded characters in a web address. In a query string, %22 is an encoded quotation mark, not a variable.
• Loop variables the command sets itself. In for r in api/one api/two; do gh api repos/$r; done, $r is set by the loop on the line above. Castforge reads the loop and checks the folders it actually visits, so a loop that walks into a sensitive folder is still caught.
• Positional placeholders. $1, $2 and similar stand in for arguments and are not folder names.
• A pattern that happens to start with two slashes. Something like //F in a text substitution looks like the start of a network path, but a real network path needs a computer name and a shared folder, as in \\server\share\file.txt. A lone //F names neither, so it is treated as the text it is.

Network paths themselves are unchanged in how they are judged: \\server\share\... and its variants are still treated as leaving your project, because Castforge cannot tell what is on the other end of a network share. On Careful and Balanced they stop and ask. On Autonomous, like everything else, they run and are logged.

What is still treated as real uncertainty is unchanged: a path built from an environment variable Castforge cannot resolve, and a path whose folder comes from the output of another command. Both count as leaving the project, and on Careful and Balanced both stop the run.

Your agent reading its own saved output

When a command produces more output than fits in one message, the agent CLI writes it to a file and hands the agent the path so it can read the rest. Those files live beside the CLI's own settings, which are on the sensitive list, so reading them back used to stop the run. On a research-heavy phase that meant work stalled on its own notes.

Castforge now recognises that folder for the project you are working on and lets the agent read what it just wrote. The rest of the CLI's folder, including its sign-in details and settings, stays on the sensitive list, and saved output belonging to a different project stays off limits too.

If Castforge asks, Castforge waits

A prompt only ever reaches your screen because Castforge decided this one is yours to answer. Everything it was willing to approve on your behalf is approved before a prompt is ever drawn, silently, and you never see it.

So when a permission card does appear, the app will not answer it for you. Not while the project window is open, not after any delay. It waits for you to click.

On Autonomous this now works the other way round, by design. Since 2026-08-05, Autonomous answers permission cards for you, immediately, including cards the sensitive list flagged. That is the whole point of the setting and it is not the defect described below. Below Autonomous the promise in this section holds exactly as written: a card that reaches your screen is yours to answer, and nothing else will answer it.

This closes a real gap. The card had its own rule for deciding whether it could answer itself, and that rule looked only at how risky the kind of action was. But the sensitive list checks the specific thing being asked about, and it runs first and separately. So a request the sensitive list had already stopped, whose category still looked routine, could be approved by the card itself in about a hundredth of a second. Reading a private key through a variable Castforge could not resolve was exactly that shape: stopped by the sensitive list, categorised as routine, approved without you. Because Autonomous is deliberately permissive about work outside your project folder, the sensitive list is the boundary that makes that trade safe, and a boundary the app could talk itself past was not a boundary.

Now the card is told the decision rather than re-deciding it, and if it is ever told nothing at all, it asks. A card from an older version, or one replayed from a saved conversation, renders and waits rather than answering itself.

Routine tool actions on Balanced are still approved for you without a prompt, and product decisions still wait. Ordinary work inside your project is unchanged, and this does not add prompts to a run that was not already stopping.

The sensitive list applies in every mode

The sensitive list used to be consulted only on Autonomous. That was backwards, and it is worth saying plainly why.

On Careful and Balanced, Castforge approves some routine steps for a working role on your behalf, so the run does not stop every few seconds. It checked that those steps stayed inside your project folder, but it did not check them against the sensitive list. So an action the list exists to stop, if it named no path outside your project, was approved and never shown to you at all. Publishing a package, uploading a local file to a remote host, changing your global git identity, or running something with elevated privileges are all like that: none of them names a folder outside your project, so nothing stopped them.

From now on the sensitive list is checked in every mode before Castforge approves anything for you. Careful, Balanced, and Autonomous all use the same list, described above.

What this means for you:

• Ordinary work is untouched. Running tests, building, reading and editing files in your project, and running your own scripts all behave exactly as before. This was measured against 834 real commands from recorded sessions before it shipped, and none of them changed.
• Balanced and Careful now stop for the sensitive list. A package publish or a production deploy typed as a shell command will now draw a card in these modes instead of quietly running. That is the same rule Autonomous already followed.
• Autonomous is unchanged. It already checked the list.

Correction, 2026-08-05. The heading and the last bullet were true when written. The list is still checked in every mode, which is the part that has not changed and is what makes the log worth reading. What changed is the consequence: on Autonomous a match no longer draws a card. Careful and Balanced are exactly as this section describes them.

A path Castforge cannot work out is treated as leaving the project

Commands often build a path out of a variable, like $SCRATCH/output.txt. When Castforge recognises the variable as one that names a real location on your machine, it works the path out and judges where it actually lands. When it does not recognise it, it used to assume the path was relative and therefore inside your project. That assumption was wrong, and it was the reason a private key read through an unfamiliar variable was categorised as routine.

Now a path whose starting point Castforge cannot work out counts as leaving your project folder, so it asks. This is narrow on purpose. It only applies when the very first part of the path is the unknown, which is what decides where the path lands. A variable later in the path, a search pattern, a percent sign in a date format, and every other ordinary piece of shell syntax are all left alone, because none of them can move where a path begins. Measured against the same 834 recorded commands, this changed two of them, and both were scripts copying files between two different project folders, which is exactly the case worth being asked about.

New milestones on Autonomous

When the Lead proposes a plan that would start one or more new milestones, Castforge normally shows you the proposed structure and asks you to confirm before any milestone is created. That confirmation was built to be unskippable, and until 2026-08-05 it was.

On Autonomous it no longer appears. A plan that proposes new milestones now creates them with no dialog and no human, and the run carries straight on into them. This is the one place where "Autonomous asks nothing" reaches past permissions and into the shape of your board, so it is worth knowing before you leave a planning run unattended: you may come back to a board organised into milestones you did not approve.

On Careful and Balanced the confirmation appears exactly as before, showing the proposed milestones, and declining leaves your board flat rather than creating anything.

If you are looking for this dialog and not seeing it, the permission level is the reason. Switch the project to Balanced and it comes back.

The one-time Autonomous confirmation

The first time you switch a project to Autonomous, Castforge shows a confirmation dialog titled "Switch to Autonomous?" explaining that prompts will be auto-approved in this project. Choose Turn on Autonomous to proceed or Keep current level to back out. After you confirm once, that project switches to Autonomous directly from then on, and a small Autonomous badge stays visible so you always know the project is running unattended. You can switch back to Careful or Balanced at any time.

Permission prompts

When the agent needs approval, a bordered prompt with a shield icon and a red rail appears in the conversation: "{tool} wants to {action}." For a shell command, the exact command is shown so you can read what you are approving. Three buttons:

• Deny (the default, so pressing Enter is always the safe choice).
• Allow once approves just this action.
• Allow always approves this kind of action from now on, so you are not asked again for it.

Allow always is remembered for that project and that tool, and it now holds even when the project is not the one you are looking at. Earlier builds saved your answer but never applied it, so the same question could come back minutes later in the same run. It applies from the next request onward.

Two limits worth knowing. It is per tool and per project: allowing web search always does not also allow fetching pages, and it does not carry to your other projects. And it never covers the high-risk actions, so a production deploy, a migration, a publish, or a purchase still asks you every time even if you pressed Allow always on something else.

If you are sitting on any other tab (Course, Preview, Memory, or Health) when a prompt arrives, a small dot appears on the Chat tab to tell you a decision is waiting there.

The "Waiting on you" panel

Approvals are never only in the transcript. Whenever a project has approvals outstanding, a pinned panel appears in the bottom right corner of the workspace headed Waiting on you (N), where N is how many are actually waiting. It shows every one of them, not just the newest, and each card carries the same Deny, Allow once, and Allow always buttons you get inline. It stays put on every tab, Chat included, so you never have to scroll back through a conversation to find the prompt that is holding a run.

The panel reads the count from the agent's own record of what it is blocked on, not from what happens to be on screen. That matters in one specific case: if approvals arrived while you were on the home screen or in another project, the panel still lists them when you open the project. Nothing is lost by not being there when the prompt appeared.

If you answer one of several, the panel does not disappear. It drops that card and the count goes down by one, which is your signal that the run is still blocked on the rest.

Approvals follow you around the app

Runs do not only block while you are watching them, so the approval signal is not confined to the project you have open.

Whenever anything is waiting on you, a bar reading "N approvals are waiting on you" appears at the top of the screen, with one button per project that has approvals. Click a button to jump straight to that project and answer. The bar is on every screen: the home screen, Connections, Cost, Discover, Templates, the plugin marketplace, Notifications, Shortcuts, and project settings. So if you step out of a project to fix an agent connection or check your usage and something starts waiting, you find out where you are instead of coming back later to a run that has been stuck the whole time.

The bar is not shown when nothing is waiting, so it never takes up space in normal use. Like the workspace panel, it reads from the agent's own record of what it is blocked on rather than from what happened while a particular screen was open, so approvals raised before you navigated are still counted.

You answer approvals in the project, not from the bar. The bar tells you and takes you there; the decision itself always goes through the project's own approval buttons, so there is exactly one place a decision can be made.

Live output and the cost indicator

While the agent works, its output streams into the conversation in real time. You see the reasoning, tool calls, and shell output as they happen, with a thinking indicator until the turn finishes.

To see what a conversation has cost, run /cost. The panel shows input tokens, output tokens, and total dollar cost for the current conversation, summed from the agent's own reported usage.

Common questions

How do I undo a change the agent made?

Run /undo in the composer. It restores the most recently applied file to the contents it had before you applied the change, and the diff badge flips to ↺ reverted. Undo works on changes you applied; it walks back the most recent one each time you run it.

How do I stop the agent mid-response?

Press Esc, or click the square stop button that replaces the send button while the agent is streaming. That cancels the current turn. If you are running a multi-role pipeline, a separate Stop pipeline button ends every running role at once; it asks you to click twice to confirm.

A Stop cancels the run, not what you typed. Any messages sitting in the queued stack above the composer stay there, and the caption switches to say the next one goes out with your next message. Remove a queued row with its ✕ if you no longer want it.

A Stop reads as a stop, not as a crash. When you stop a run, the conversation says Run stopped. in neutral grey, with the line "You stopped this run, so the agent did not finish. Nothing was left running." It used to report a red execution error instead, which made a deliberate stop look like something had broken. If Castforge could not fully stop everything it tried to stop, it drops the "Nothing was left running" sentence rather than claiming something it cannot confirm, and the toast beside it tells you what did not stop cleanly. A run that genuinely fails on its own still shows the red error card, so the two are easy to tell apart at a glance.

Stop pipeline stays available if you navigate away and come back. Leaving the project and returning while a run is in progress used to hide the button, because the reopened conversation is replayed from disk and looks finished. Castforge now asks the engine directly whether a run is live for that project, so the control is there for the whole run. If Castforge cannot confirm either way, it shows the button rather than hiding it, and its tooltip says it is still confirming. Clicking it when nothing is running is harmless: it reports that 0 role-turns ended and changes nothing.

Why are some Apply buttons greyed out (or missing)?

Either the change was already auto-approved by your permission level (it shows applied with no buttons), or the session that produced the diff has ended, usually after a restart. In the second case you will see "Session ended. The diff is no longer actionable." Send a new message to start a fresh session, and the agent can re-propose the change so you can apply it.

What is the difference between /clear and starting a new project?

/clear ends the current conversation inside the same project and starts a fresh one. Your files, settings, and history stay put. It is the right tool when a conversation has wandered and you want a clean slate without losing the project.

Does the agent edit my files without asking?

Inside your project folder, yes, at every permission level including Careful. A role that can write applies its edits as it works rather than asking per edit, and that is true on every agent. What your permission level changes is everything else: on Careful and Balanced shell commands, network access, and anything reaching outside your project folder stop and ask, while on Autonomous nothing stops.

Every applied change is recorded either way, so you can review it in the conversation and roll it back with /undo.