Everything Foremen can do for you
A plain-language guide to the whole tool. No jargon, no assumed knowledge — if you can describe what you want to an AI coding agent, you can use everything on this page.
Looking for connection snippets and the API? The technical docs live here.
What Foremen is
AI coding agents are brilliant for one session and then forget everything. Close the chat and the agent that knew your project inside-out is gone — the next one starts from zero, re-reads your code, re-asks your preferences, and sometimes re-makes a mistake you already fixed the hard way.
Foremen is memory that lives with your project instead of the chat. As agents work, they record what they did, what was decided, what broke and how it was fixed, and where they stopped. The next session — tomorrow, or in a different tool entirely — picks all of that up in one call and continues where the last one ended.
You do not need to learn commands. Everything in this manual works by talking to your agent normally — “get the session brief”, “remember this as a lesson”, “ask Foremen first”. The agent does the bookkeeping; you get the continuity.
Getting connected
There are two ways in. Most people should start with the first one — it takes a minute and covers every project you own.
Connect your account
Add Foremen to your AI tool as a connection and sign in with your account — no keys to copy. Claude Code, Cursor, VS Code, claude.ai, and ChatGPT all support this. Once connected, every conversation in that tool can reach all of your projects; the agent simply names the one it wants.
The address you connect to is https://dreamkid.org/api/mcp. Exact steps for each tool are on the docs page, and the same snippets live in your dashboard under Settings.
Install into a repository
Each project's Directives tab shows a single command — pnpm dlx dreambuild init — that wires one repository to one project. Paste it into your terminal and it sets up the connection and the messenger that delivers your directives to Claude Code in real time (more on that below).
The command carries a single-use install token instead of your real key — it works once, expires in ten minutes, and your actual credential never appears on screen or in your terminal history. Files it writes that belong in git are safe to commit; your key lands only in a git-ignored file. Undo everything later with pnpm dlx dreambuild uninstall.
Which one do you need? Path 1 gives every agent memory. Path 2 adds the only thing Path 1 can't: real-time directive delivery inside Claude Code, including the ability to stop an agent before it finishes. Many people use both — sign in once for everything, then run the install command in the repos where they want directives enforced.
Your first session
- 1
Create a project
Do it in the dashboard, or just tell a connected agent “create a Foremen project for this codebase” — it will fill in the name, description, and tech stack from what it sees.
- 2
Start every session with the brief
Say “get the session brief for my-project”. One call hands the agent everything: your greeting and ground rules (written once, delivered to every agent before work starts), the notes previous sessions left, the current task, standing decisions, hard-won lessons, the architecture map, and recent activity. This is the heart of the whole tool — the difference between an agent that starts cold and one that walks in already briefed.
- 3
Work normally, then leave breadcrumbs
Agents record activity as they go. Before you close a session, a habit worth building: “leave a session note about where we stopped”. The next session reads it first.
What your project remembers
Five kinds of memory, each answering a different question. Agents write to all of them as they work; you can also add to any of them by asking.
Session notes — “where were we?”
Timestamped breadcrumbs from one session to the next: what was finished, what's half-done, what to watch out for. Append-only, so nothing gets silently rewritten. The ten most recent ride along in every session brief.
Decisions — “what did we choose, and why?”
One-liners with context: “We use Zod for validation because it's already a dependency.” Every future agent sees them, so nobody re-litigates a settled question. Decisions can also be temporary — “don't touch auth this week” gets an expiry date and quietly disappears from briefs when it lapses.
Lessons — “what bit us last time?”
The expensive kind of knowledge: a pattern to watch for, what happens if it's ignored, and the fix — optionally with the exact before-and-after code that inspired it. When an agent hits a nasty bug, say “remember this as a lesson” and no future session has to rediscover it. Lessons surface in briefs and whenever an agent asks Foremen for advice.
Activity — “what actually happened?”
A running feed of real work: what was built or fixed, which files were touched, when. Agents can also check in at the start of a session with the files they plan to touch — and get warned if another agent worked on those same files in the last two hours, so two sessions don't trample each other.
Artifacts — “keep that file”
Agents do real work in temporary scratch space — generated SQL, test scripts, rollback snapshots — and that space is wiped when the session ends. Artifacts let an agent keep a file past the end of the session that made it: “save that migration script as an artifact”. Every saved file is scanned first and refused outright if it contains personal data or credentials — more on that in the security section.
Steering your agents
Memory is what agents know. These four features are how you shape what they do — before, during, and at the end of their work.
Tasks — a to-do list agents can actually run
Each task carries a title, a priority, and a full set of instructions — a prompt, written once, executed whenever an agent picks the task up. Say “what's the next task?” and the agent gets the highest-priority item with its complete instructions, marks it in progress, and marks it done when finished. Queue up a week of work on Sunday; let sessions burn it down all week. A task can also be flagged “needs a fresh chat” for big jobs that deserve a clean context window.
Directives — standing instructions with perfect timing
A directive is an instruction you write once in the dashboard that reaches the working agent at the moment you chose, in every future session, without you repeating it. Six moments to pick from:
- Session starts — delivered before any work begins — house rules, context, warnings
- New request arrives — fires when you send a prompt, optionally only when it contains a keyword
- Matching file is edited — watches a file pattern like app/api/** and speaks up the moment an agent touches it
- Every N actions — a periodic nudge — every 20 tool actions, remind the agent to run the tests
- Task starts — rides along whenever an agent picks up a task from the to-do list
- Before the agent finishes — the strongest one: in Claude Code this actually stops the agent from ending its turn until it has followed your instruction — run the type checker, report honestly, leave a session note
Directives are deliberately quiet. Each one delivers at most once per session unless you raise its limit (capped at ten), there's a hard ceiling of twelve deliveries per session across all directives, and “every N actions” can't be set below five — so a directive can never turn into spam. An honest note on timing: instructions reach the agent between its steps, not mid-keystroke. In Claude Code (with the repo install from Path 2) delivery is automatic; on every other platform, session-start directives arrive inside the brief and agents are told to check for the rest at natural pauses. Every delivery is logged, so the Directives tab shows you exactly what reached which session, and when.
Guardrails — “don't touch that”
Mark a file, a directory, or a filename pattern as protected, with a message explaining why and a severity from a gentle FYI up to blocked. Agents are expected to check guardrails before making changes, and any consultation that involves a protected path leads with your warning. “Add a guardrail on the payments folder — nobody touches it without asking me first” is a one-sentence insurance policy.
Ask Foremen — a second opinion before acting
Say “ask Foremen first” and the agent submits its plan for review against everything the project knows: guardrails on the files involved, lessons that match the situation, related architecture, and what other sessions did recently. Back comes a plain recommendation — proceed, proceed with caution, or stop — with the receipts attached. It's the cheapest way to catch a repeat of a past mistake before it happens.
Teaching your project
Beyond memory of what happened, a project can hold reference material you want every agent to build from — style guides, instructions, documentation.
References — the project's bookshelf
A reference is a named piece of standing material: a design style guide, a reusable prompt, AI instructions, documentation. Each has a short tag — like style-guide — that agents and tasks use to pull it up. Writing to an existing tag updates it in place, so there's always exactly one current version. References marked as AI instructions are delivered automatically in every session brief — write your house rules once and every agent starts with them. References can also be attached to each other, so fetching one brings its companions along.
Documents — big files, small answers
Drop a large document into a reference — an API spec, a product brief — and Foremen splits it by its headings into searchable sections. Agents then search across everything (“find what our docs say about refunds”) and fetch just the one section they need instead of stuffing the whole file into their context. There's also a relevance finder: give it a task description and it ranks which references and sections matter for that job.
Prompt expansion — one tag, the whole package
A prompt reference can be expanded: its attached documents, linked references, and optionally the project's tech stack and architecture get inlined into one complete, ready-to-run prompt. Build a “new feature” prompt once, attach your style guide and conventions to it, and every future use carries them automatically.
Your dashboard
Everything agents record lands in a place you can read. Each project has a hub with tabs for its tasks, directives, knowledge (lessons and decisions), client work, collected files, invoices, and the full activity feed — plus an overview of stats, architecture, and recent commits at a glance.
The Lineage view deserves a special mention: it draws the connections between work items and the files they touched — this task led to these edits, this lesson came from that file. The more faithfully agents report their work, the richer the map gets.
Under Settings you'll find account tools: passkey sign-in (use your fingerprint or face instead of waiting for an email link), API key management (create, reveal, revoke), and the connection snippets for every supported tool.
If you build for clients, the memory agents accumulate doubles as something presentable — without you writing status reports.
The client work tracker
One click in a project's hub creates a private link you can hand to a client. It opens a live page — no login — showing progress, budget with a visual burn-down, a roadmap of what's in progress and coming up, and a day-by-day timeline of real work, updating as it happens. It reads from the same activity agents are already recording.
File collection links
Need a logo, brand photos, or documents from a client? Create a file request and send the link. They upload with labels, mark themselves done, and the link closes itself. Everything arrives in your uploads library and in the project's Files tab.
Invoices
Build an invoice with line items, send a private payment link, and get paid by card online. Status flows back automatically — paid invoices mark themselves. Invoices attach to projects, so the money side lives next to the work it paid for.
Client updates
Ask an agent to write up what it just shipped and it publishes a designed page at /updates/<slug> and emails it to the client. One commit, one update. You can queue several and send them together, so a week of work arrives as one note instead of five.
Tutorials inside updates
An update can carry a recorded walkthrough in the body, so the client reads what changed and watches it work in the same place, instead of taking your word for it and finding the video somewhere else.
You don't have to have recorded it yet. Ask for a tutorial slot and the update holds an empty place for the video — invisible to the client until something is in it, so the update can go out today and the walkthrough can arrive Thursday. When you make the tutorial, pick the slot it fills and it appears in the page that was already sent.
Brand & naming studies
A client questionnaire (the wizard) captures how a brand should feel; the answers become briefs in your dashboard, and finished naming studies publish to a private client page that records which directions they reacted to. Their feedback flows straight back to you.
Working with someone else
Debugging someone else's problem means seeing their machine, and their machine is not yours. You can't install anything on it, you shouldn't hand them a key, and half the time they won't open a terminal. A slot is a shared space both sides can write to — they paste, you read, your agent reads the same thing.
How a slot works
Every slot is a six-character space code and a page at dreamkid.org/s/CODE. Open it in any browser, on any device, with no sign-in. Anything either side puts there appears on the other's screen straight away.
The code is the only credential, and it opens that one space — not your account, not your projects, not your other slots. That's what makes it safe to send to someone you're helping.
Four ways in
Paste or type in the box at the bottom. Drag a file onto the slot — a log, a screenshot, an HTML export, anything. Record your screen with the record button when showing is easier than describing; it uploads itself when you stop and plays back in place. Or pipe a command from a terminal, which is the one that works on a locked-down box where nothing can be installed.
Files stay files
A dropped file keeps its name, size and type instead of being flattened into a wall of text. Your agent still reads the contents of anything textual. Downloads are short-lived signed links, so a URL that leaks doesn't stay useful.
Pointing your agent at it
Connect once with “connect to slot HF9JWX” and your agent reads that space from then on. Say “check the slot” and it picks up whatever landed last.
Every entry also has its own reference. Tap an entry's four-character code and you copy something like slot://HF9JWX/AC9K — paste that in front of whatever you were going to type and your agent reads that entry before answering. You don't have to explain what it is, and it works even in a session that has never connected to the slot.
Handing a slot to someone else
Say “open a slot for the client so they can send me the build error” and your agent opens a fresh space and writes out the message to send them. It comes back with four ways in, and you forward the one that fits the person:
- A link — for anyone who won't open a terminal. Paste, drag, or record, all in the browser.
- A command — pipes whatever they run straight to you.
- A file upload — for a log or export already on disk.
- Their agent — one line connects their coding agent to the same space, so both of you and both agents work from one thread.
Each handoff opens its own space, so two people you're helping never see each other's logs. Watching theirs doesn't disturb the slot your own machines use.
Holding a conversation
Your agent can write into a slot as well as read it, so it can ask the other person a question directly — “ask them to run npm ls and send the output” — and it lands on their screen immediately. They reply the same way, by typing, dropping a file, or letting their own agent answer.
Your agent isn't pinged when something arrives — nothing pushes into a running session. It can wait for a reply instead, holding for up to 25 seconds and picking it up the moment it lands, so you're not the one relaying messages between the two of them. If nothing comes, it says so rather than guessing.
Privacy & security
Your memory is encrypted per account
The content of your notes, tasks, decisions, lessons, and activity is encrypted with a key unique to your account before it's stored. Your code never leaves your machine — Foremen stores what agents report about the work, not the codebase itself.
Saved files are screened for personal data
Every artifact an agent tries to keep is scanned first. Files containing things like card numbers, government IDs, or credentials are refused outright; files accumulating personal details like emails and addresses are refused past a small threshold. And the scanner reports only counts of what it found, never the values — a scanner that echoes what it caught would just move the leak.
A shared slot shares only itself
A space code opens one slot and nothing else — not your account, not your projects, not your other slots. Nobody you hand one to needs a key or a sign-in, so you never have to put a credential on someone else's machine. Anything sent through a slot is scanned on the way in and obvious secrets are masked before they are stored, because a slot is exactly where someone pastes a config file without thinking. Files download through short-lived signed links rather than permanent public URLs.
Credentials are handled like they matter
API keys are verified by fingerprint (a one-way hash), with a per-account encrypted copy so the dashboard can show them back to you — and any key can be revoked in one click. Install commands carry a ten-minute, single-use token instead of the key itself, so your real credential never crosses your screen or your shell history. Sign-in supports passkeys — your face or fingerprint — alongside email links.
Things you can say
None of these are magic words — say them however you naturally would. The agent translates.
- “Get the session brief for acme-site”start any session fully briefed
- “Leave a session note about where we stopped”breadcrumbs for next time
- “Record a decision: REST, not GraphQL”settle it once, for every future agent
- “Remember this as a lesson”keep a hard-won fix from being re-learned
- “Add a task: redesign the login page”queue work with full instructions
- “What's the next task?”pull the top of the to-do list and run it
- “Ask Foremen before touching checkout”second opinion with the project's receipts
- “Add a guardrail on the payments folder”mark an area protected, with a reason
- “Save that script as an artifact”keep a working file past the session
- “Check for directives”on tools without the hook, pull standing instructions
- “Connect to slot HF9JWX”point this session at a shared space
- “Check the slot”read whatever just landed there
- “Open a slot so the client can send me the error”a link to forward, no account needed
- “Ask them to run npm ls and wait for the reply”message the other side and hold for an answer
- “Write up what we shipped and send it to the client”a designed update page, emailed
- “Leave a tutorial slot for each feature”hold the video's place before it exists
- “What tutorial slots are still open?”the walkthroughs left to record
- “Put that walkthrough in the discount slot”drop a video into a page already sent