Getting started — your first project in 5 steps

1. Create a project with the + button in the sidebar header.
2. Give it a track (a color-coded category) — and an optional subtrack — so it groups sensibly in the Portfolio.
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. Click ⚡ Start Work on a move and paste the generated briefing into a fresh Claude Code session. 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.

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

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.
• Subtrack — an optional finer-grained label within a track. When set, the subtrack 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.

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.
• 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.
• 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.
• Knowledge: the authoritative facts, decisions and documents a project 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.
• 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.
• 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 a move, it queues that move directly. Anything it adds is shown to you right away with an Undo, 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.
• Work Log: a timestamped, running record of what actually happened on a project: decisions, completed work, and blockers. Completed moves land here automatically.