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 alpha build, so you may see the toggle without it.

A project's type also decides what the Preview tab shows. For a Web app project, Preview is a live embedded view of your dev server. For an Unreal Engine project, Preview opens a dedicated Unreal panel instead, with its own viewport, camera controls, and Time Machine timeline. You pick a project's type at setup and can change it any time from settings; see "Preview and iterate" for the Unreal panel in detail.

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.

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.

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).
• Noise folders like node_modules, dist, and target are hidden by default. Use the eye button in the FILES header to show or hide them. Gitignored files appear dimmed and are never counted as changes.

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.

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.

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," with 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 small dot appears on the Memory tab so you notice it even while you are on another tab.

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 every action. Every file edit, shell command, and product question pops a permission prompt you approve or deny.
• 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 runs without asking. Tool actions and product decisions are auto-approved. It is meant for trusted, overnight, or unattended runs.

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.

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.

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 and clears the queue; it asks you to click twice to confirm.

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?

That depends on your permission mode. In Careful it asks before every edit. In Balanced and Autonomous it can edit files without a prompt, but every applied change is still recorded so you can review it in the conversation and roll it back with /undo.