Getting started — your first project in 6 steps

1. Create a project with the + button in the sidebar header.
2. Give it a track (a color-coded category) so it groups sensibly in the Portfolio, and optionally a label, which is shown but never groups anything.
3. Add a few verb-first moves to What's Next (e.g. "Draft the pricing page copy").
4. Under Reference, attach where you actually work: the repo, the Claude Project, specs, deployment URLs.
5. Under Reference, if you have a paired device, link the project to its folder on that machine. Start Work then knows where the code lives instead of guessing.
6. Click ⚡ Start Work on a move. If a device is paired, Forge runs the session for you; if not, it hands you a briefing to paste into a fresh Claude Code session. Either way, you're off.

The session loop — your daily rhythm with Claude Code

This is how Forge and Claude Code work together. Forge holds the thread between sessions; the session holds the live code.

1. Blueprint (once per repo) — click 📐 Blueprint at the top of a project to copy its priming prompt, then paste it into that repo's CLAUDE.md. Now every Claude Code session in that repo knows about Forge and how to use the MCP server.
2. Start Work (per move) — generate a briefing for a specific move and hand it to a session.
3. Work — Claude Code does the work in the repo, where the context lives.
4. "Wrap up" — tell the session you're done. It syncs back to Forge: completed work lands in the Work Log, and the next moves are queued into What's Next.
5. Land it — a finished session leaves its work on a branch and stops. Open ⑃ Unlanded work in the Work Log header to merge that branch, push it, and confirm the deploy, all from here. See Reference → Unlanded work.

Next session, you pick up exactly where you left off — because Forge carried the thread.

The whole loop is meant to run without a terminal. If you find yourself opening one, that is worth noting as a gap rather than a habit.

Handing work to Claude Code — Blueprint vs. Start Work

• 📐 Blueprint — one-time priming of a repo. Teaches a project's sessions the Forge workflow (awareness + the session loop). Use it when setting a project up.
• ⚡ Start Work — a per-task briefing for one move. Use it each time you pick up a move from the queue.

The principle behind both: a briefing proposes intent and constraints — it does not dictate how. The session has the live codebase in front of it and holds final say on the technical approach. See Reference → Start Work for the full division of authority.

Keeping projects healthy

• Set Waiting On when a project is blocked on someone or something — it surfaces in the Needs You portfolio view and ages visibly.
• Scan the Most Stale portfolio view to catch projects falling through the cracks before they go cold.
• Enable the morning briefing in Settings for a daily summary of what needs attention across the portfolio.

Working with others

• Share a project and it appears in your collaborator's Shared with me section.
• Collaborators can add and complete moves, log work, and edit the project — only the owner can delete it.

Portfolio

The home view — all your projects at a glance. Switch between three layouts using the tabs at the top:

• By Track — projects grouped by track (e.g. Product, Ops, Personal).
• Needs You — projects with no "Waiting On" set; things that are in your court.
• Most Stale — projects sorted by how long since their last update. Use this to find things falling through the cracks.

Hover a project card to preview its next move and recent log. Click to open the project. A ● Stale flag appears when a project hasn't been touched in more than the configured staleness threshold (default: 14 days).

A morning briefing appears at the top of the portfolio if enabled in Settings — a daily summary of what needs attention.

Start Work

⚡ Start work (on any move in the What's Next queue) generates a tailored Claude Code briefing prompt for that move and opens a panel where you can copy, regenerate, then paste it into a fresh Claude Code session. The briefing is assembled from the move's task, the other queued moves (as context), recent Work Log entries, and the project's references — then written up by Claude as a self-contained prompt for a session that has no prior context on the project.

Start Work is built on a deliberate division of authority — Forge directs attention, it does not author solutions:

• Forge decides what, when, and why — the queue, the priority, the intent, and any hard constraints. It is the product-owner memory that outlives any single session.
• The Claude Code session decides how — it has the live codebase in front of it, so it holds final say on the technical approach.
• The briefing proposes, it does not dictate. A generated prompt hands off intent, constraints, and a suggested first step — not a frozen implementation spec.
• Prompts are self-invalidating. Each briefing tells the session to verify the suggested approach against the current code before building, and to take a better path (noting why) if the code has moved on. This guards against acting on a decision frozen at the moment of least context.

The practical upshot: keep big design decisions in the session where the context lives, and let Forge carry intent between sessions rather than dictate it.

Projects

Create a project with the + button in the sidebar header. Each project has:

• Name and description — editable inline at the top of the project view.
• Status — Active, Paused, or Archived. Controls which sidebar filters show the project.
• Track — a color-coded category (e.g. Product, Finance). Create new tracks inline when editing a project.
• Label: a second, optional marker. It is independent of the track rather than a subdivision of one, and the two can be set in any combination. When set, it appears as a pill next to the project name in the sidebar.
• Waiting On — mark a project as blocked, name who or what it's waiting on, and set a date. Blocked projects surface in the Needs You view.
• Star (★) — pin frequently-used projects to the top of the sidebar. Click the star next to any project in the sidebar.
• Shared with me — projects another user has shared with you appear in a Shared with me section at the bottom of the sidebar. You can add and complete moves, log work, and edit the project — only the owner can delete it. A small green dot (●) appears on a shared project when new What's Next or Work Log entries have been added since your last visit; it clears the next time you open the project.

To delete a project, open it and use the Delete button in the header. This is permanent.

What's Next

A prioritized queue of the next moves for each project. Designed for verb-first, action-sized entries: "Draft the pricing page copy", not "Pricing page".

• Add a move — type in the input at the top of the What's Next section (visible when a project is open). Press ⌘↵ / Ctrl↵ to add without clicking.
• Paste a list — paste multiple lines at once; each line becomes a separate move.
• Reorder — drag moves to any position in the queue, or use the shift buttons: ⤒ makes a queued move the Next Move, ↑ moves it up one, ↓ moves it down one, and ⤓ sends it to the bottom of the queue.
• ⚡ Start work — generates a Claude Code briefing prompt for the move, including the task, other queued moves, recent Work Log entries, and project references. Opens a panel where you can copy or regenerate it, then paste into a fresh Claude Code session.
• Complete a move — click ✓ on any move. You'll be prompted for an optional outcome note, then the move is removed from the queue and logged in the Work Log automatically.
• Delete without logging — click Delete to remove a move without adding a Work Log entry.
• ⧉ Copy prompt (What's Next header) — copies a prompt to paste into your AI assistant; includes all queued moves so Claude can work through them.
• ⧉ Copy work prompt (project header) — a longer prompt that asks Claude to work through the entire queue in one session.
• ▾ / ▸ Collapse — click the arrow to the left of the "What's Next" heading to roll up the section. The item count stays visible. Click again to expand. Your preference is saved and persists across sessions.

Milestones

A milestone is the goal a run of moves is serving, so the queue reads as progress toward something rather than a flat list of tasks. Each one carries a done_when, the sentence that decides whether it is finished.

• The current milestone is the first uncompleted one. That is what "what are we working toward" means at any moment, and it is why reordering milestones is how focus changes.
• Every move belongs to one, which is what keeps the queue honest: a move nobody can attach to a goal is usually a move worth questioning.
• Fold the sections with the control beside the What's Next heading. The current milestone stays open and the rest collapse, so a long queue stays readable.
• Claude can recommend, not perform. An assistant may propose reordering the milestones or closing one, and you apply it here. Closing a milestone forces a decision on every move still open inside it, which is the point rather than an obstacle.

Sessions

⚡ Start Work does more than hand you a prompt. When a device is paired, Forge runs the session and streams it back into the app, so you can watch it work and read what it did.

• Where it runs. Forge picks the first engine available: your paired device, then cloud execution if the project has it configured, then the server. If none is available it refuses with a message saying why rather than failing quietly.
• Link the project to a folder in Reference, so a device session knows which checkout to work in. Without a link, Forge is guessing.
• Each session works on its own branch and never merges, pushes or deploys it. Landing is a separate, deliberate act.
• The session view keeps the transcript, the branch and the resulting commit together, so a run you started yesterday can still be read and landed today.

Unlanded work

⑃ Unlanded work in the Work Log header asks your connected device what has not reached main yet: commits from sessions Forge ran, and branches Forge never ran at all. It is the answer to "did anything I finished never actually ship?"

• Adopt brings in a branch Forge did not run, for example one you made yourself in a terminal, so it can be landed the same way as everything else.
• Merge lands the branch on one click. Forge never moves your HEAD, not even to put it back, so nothing happens to the checkout you are sitting in.
• Push sends it to the remote. Forge pushes and does not deploy: it will tell you what it did, and never claim a deployment it did not watch.
• Confirm the deploy by asking the running deployment what commit it is serving. A host's green status is not evidence, and has been wrong before.
• Acknowledge a branch you have no intention of landing, with the reason, so it stops appearing without anyone having to remember why.

The sweep runs when you press it, rather than sitting as a badge. A badge written once is wrong the moment the branch merges.

Queue audit and queue runs

• Audit reviews the queue and reports what it finds: duplicates, moves that read as placeholders, work that looks already done, and an ordering it can justify. It comes back as one plain-language proposal you can accept or ignore, not as rival lists you would have to referee.
• Queue run works several moves in sequence in one go. On a clean run it pushes its own branch for that batch and never main, so merging to main stays a decision you make.
• Deleted moves can be shown again from the What's Next header. A deleted move is hidden, not destroyed.

Test Runner and Dev Log

• Test Runner runs a project's suite on a paired device and reports the result in the app, so "is it green?" does not require a terminal. It tests the working tree as it stands, so an uncommitted change is included in what you are looking at.
• Dev Log (in the left nav) is the running, user-facing record of what has actually shipped, written for reading rather than for a changelog parser.

Work Log

A running record of what happened on each project — decisions made, work completed, blockers encountered. Entries are timestamped and shown newest-first.

• Entry number (#) — every entry carries a stable, per-project number (e.g. #14) shown next to its timestamp. The number is assigned once and never reused, so you can reference a specific entry unambiguously in conversation, the briefing, or via MCP.
• Types: Note (general), Decision (a choice that was made), Blocked (a blocker or impediment).
• Paste a list — paste multiple lines; each becomes a separate entry of the selected type.
• Completed moves appear here automatically when you complete them from the What's Next queue.
• Delete — remove individual entries with the ✕ button.
• ⧉ Copy prompt (Work Log header) — copies a prompt that asks Claude to summarize recent work from this log.
• ▾ / ▸ Collapse — click the arrow next to "Work Log" to hide the entries. Entry count stays visible. Preference is saved across sessions.

Reference

Each project has a Reference section for the resources attached to it — three types:

• Tool Locations — where you work on this project: a Claude Project URL, GitHub repo, Figma file, Notion page, etc. Anything with a URL becomes a clickable link.
• Documents — transcripts, specs, briefs, and other reference files. Can be a URL or a local file path.
  • URLs become clickable Open ↗ links.
  • Local absolute paths (starting with /) also become clickable — clicking opens the file directly. ⧉ Copy path and ⧉ Copy folder buttons are available for each local entry.
  • Drag a file from Finder onto the Documents section to open the add dialog with the path pre-filled in the location field.
• Deployments — live environment URLs (Production, Staging, etc.).

Claude + MCP Integration

Forge exposes an MCP server that lets Claude read and write your queues and logs directly — no copy-pasting needed.

Setup (one time):

1. Go to Settings → Access Tokens and generate a token. Copy it — it's only shown once.
2. In your terminal, run:
   claude mcp add vector --transport http https://<your-vector-url>/mcp -H "Authorization: Bearer vec_…"

Session-start: say "check Forge" or "where did we leave off" — Claude pulls the current queue and recent log for your project.

Session-end: say "wrap up", "we're done", or "log this session" — Claude synthesizes what was accomplished, pushes work log entries, and updates What's Next with planned moves. You don't have to tell it what to write.

Settings

• General — staleness threshold: the number of days of inactivity before a project is flagged stale (● in the sidebar and portfolio).
• AI Prompts — customize the prompts copied by the ⧉ buttons in What's Next and the Work Log. Edit these to match your preferred AI tool and working style.
• Morning Briefing Email — enable a daily email summary of your portfolio. Set the delivery hour and timezone. Use "Send me one now" to test it immediately.
• Appearance — choose a light-mode color palette; recolor individual tracks.
• Data — export your entire portfolio as a JSON file.
• Access Tokens — generate and revoke MCP bearer tokens for Claude integration.

Admin

Visible only to admin users (⚡ in the sidebar). Opens a modal with three tabs:

• Users — lists all accounts. Deactivate or reactivate users; generate a password-reset link.
• Members — shows all projects grouped by owner. Click any project to see who has access to it. Use the Add user dropdown to share the project with another user, or Remove to revoke access.
• Projects — search and open any project in the system regardless of ownership. Useful for troubleshooting or reviewing another user's project directly.

Keyboard Shortcuts

• ⌘K / Ctrl+K — open the command palette. Search projects, What's Next moves, and Work Log entries by keyword. Press ↑↓ to navigate, ↵ to open.
• ⌘⇧K / Ctrl+⇧+K — open the Telemetry panel. Chat with Claude about your portfolio — ask what's stale, what's blocked, what to focus on next. Also accessible via the Telemetry button at the bottom of the sidebar.
• ⌘↵ / Ctrl+↵ — add a What's Next move while typing in the What's Next input.
• Esc — close the command palette or Telemetry panel.

Glossary

Plain-language definitions for the terms Forge uses.

• Blueprint: the one-time step of priming a repo so every Claude Code session in it knows how to work with Forge. Click the Blueprint button to copy that priming prompt into the repo's CLAUDE.md. "Liftoff" and "Blast Off" are the same feature under earlier internal names you may still see in code or URLs.
• Canon: the knowledge your project holds as true: the authoritative facts, decisions and documents it is grounded in. Answers are held to what is in here, so adding to it is how you teach Forge about your business rather than re-explaining it every session. Canon was called Knowledge on these screens until October 2026.
• Capabilities: the governed jobs a platform can actually do, each one defined rather than improvised. A capability is answered from Canon, cites what it used, and refuses when the honest answer is that it cannot say.
• Compass: the standing intent and boundaries a platform is held to. Canon says what is true; Compass says what this organization is trying to do and what it will not do, which is how a capability knows to refuse a question that is not its to answer.
• Control: the record of what was actually run, by whom, against which version of Canon. It is what makes an answer auditable after the fact rather than only convincing at the time.
• Console: the chat surface you work from inside a project, opened with the Dispatch button. It holds three partners you switch between as tabs: Planner, Inspector and Strategist. Each one is grounded in the project's real data.
• Daemon: a small program you run on your own machine that lets the Start Work button execute Claude Code locally, using your own environment and credentials, instead of on a remote server.
• Device: a paired daemon installation, one entry per machine you've connected. Devices are listed in Settings → Devices, and it's what a Start Work session runs on when working locally.
• Forged platform: a working application Forge generates for a business, which inherits Canon, Compass, Capabilities, Control and its own Console, under that business's own name and vocabulary. It is the thing Forge is ultimately for; Forge itself is the first one.
• Foreman: recommends which AI model to use for a session based on the kind of work a move needs, so you don't have to pick manually every time.
• Forge: this app itself, a tool that holds the continuity of a project between coding sessions, so nothing gets lost when you close the laptop and come back tomorrow.
• Handoffs (staged / promoted): the record of a session's progress, kept in Forge rather than a local file, so two sessions can never overwrite each other's notes. A handoff is staged during a session as a draft you can keep adding to, then promoted at the end, which publishes it into the project's Work Log and What's Next.
• Milestone: the goal a run of moves is serving, with a done_when sentence that decides when it is finished. The first uncompleted milestone is the current one, so reordering milestones is how you change what the work is aiming at.
• Move (and Move numbers): one queued task in a project's What's Next list, written verb-first so it's easy to act on (e.g. "Draft the pricing page copy"). Each move gets a stable number once it's added, so you can refer to a specific one in conversation.
• Pairing: the step that links your local daemon to your Forge account, using a short-lived code you generate in Settings → Devices, so Forge knows it's allowed to hand work to that machine.
• Pipeline: the multi-step build process a Start Work session can run for a move: plan, implement, review, and fix, rather than doing the whole task in one uninterrupted pass.
• Queue audit: a review of the What's Next queue that reports duplicates, placeholders, work that looks already done, and an ordering it can justify. It arrives as one proposal you accept or ignore, never as a change made on your behalf.
• Planner: the Console tab for one specific project, where you talk through what to do next. It can propose new moves for you to accept, and when you explicitly ask it to add or revise one, it shows you exactly what would change and waits for your click. Nothing it suggests reaches your queue until you press the button, so it never changes your queue silently.
• Punch List: a project's living list of test steps, the checklist you run through to confirm a feature actually works before calling it done. It grows over time as new features are appended to it. "Preflight" is the same feature under an earlier internal name you may still see in code, in URLs, and at the top of test plans written before the rename.
• Start Work: the button on a move that generates a tailored Claude Code briefing (the move's task, other queued moves, recent Work Log entries, and the project's references) for you to copy into a fresh session.
• What's Next: the prioritized queue of upcoming moves for a project. This is where you decide what to work on next and hand it off with Start Work.
• Unlanded work: anything finished that has not reached main yet, whether Forge ran it or you made it yourself. Found with the ⑃ button in the Work Log header, and landed from there: adopt, merge, push, then confirm the deploy by watching what the deployment actually serves.
• Work Log: a timestamped, running record of what actually happened on a project: decisions, completed work, and blockers. Completed moves land here automatically.