One hour to a repo with the crew in it. It talks to Linear, GitHub and Vercel. It refuses to write a secret. Nothing gets built in this chapter. Everything after it depends on it.
Agents are only as safe as the room they work in. This chapter builds the room. Two command-line tools signed in. A repo with the crew's instruction files at the root. Connectors to the places the crew reads and writes. Environment variables that live in your shell and in Vercel and never in git. And one deliberate attempt to break a rule so you see the guard stop it. Do the steps in order. Each one ends with a command whose output tells you it worked.
Where this chapter shows an exact install line or CLI flag, check it against the current docs before you rely on it: Claude Code, Codex CLI, Vercel CLI. The pattern is what matters. The flags change more often than this page does.
Node runs the hooks and Bellows. Git holds the work. The GitHub CLI signs you in once so every agent can open pull requests. Pick your platform.
Codex CLI has had the smoothest run on Mac and Linux. On Windows, if the native install gives you trouble, run this whole chapter inside WSL. Claude Code runs natively on Windows and inside WSL.
Then sign in to GitHub and check the versions.
Claude Code is the runtime for Anvil, Ember, Warden, Beacon, Ledger, Quill and Bellows. Install it globally, then run it once to sign in with the account that has your Claude subscription. A browser tab opens. When it closes you are in.
Codex is the runtime for Flint and Gauge. Same shape: install globally, run once, sign in with the ChatGPT account that includes Codex.
One private repository named alderline-crm. The name shows up in branch names, PR titles and Vercel, so pick it once. Replace ALDERLINE with your GitHub user or organisation.
Open the kit. Every file has a copy button. Instruction files and the .claude folder go at the repo root because that is where Claude Code and Codex look for them. Prompts, scripts and the rest stay under kit/ because Bellows reads them from there. When you are done the tree looks like this.
Commit it. This is the crew's first commit and it has no product code in it. That is the point.
.env.example with names only
The crew needs six values. The repo holds their names and nothing else. Priya sets the real values in two places: the Vercel project for anything the app reads, and her own shell for anything Bellows reads. Create this file at the root.
# Names only. Real values live in Vercel (the app) and in Priya's shell
# (Bellows). Never commit a filled-in copy. The guard hook will stop you.
LINEAR_API_KEY=
LINEAR_TEAM=ALD
NOTION_TOKEN=
# If you use Outline instead of Notion, drop NOTION_TOKEN and set these two:
# OUTLINE_URL=
# OUTLINE_TOKEN=
GITHUB_TOKEN=
PREVIEW_URL=
GATE_WEBHOOK=Where each one comes from. LINEAR_API_KEY: Linear, Settings → API → Personal API keys, created as a dedicated Alderline Crew user so agent comments look different from Priya's. LINEAR_TEAM: the team key. Create the team now with key ALD; chapter 8 and kit/linear/workflow.md set up its seven states. NOTION_TOKEN: a Notion integration token with access to the wiki pages. GITHUB_TOKEN: a fine-grained token scoped to this one repo. PREVIEW_URL: filled per branch by Vercel; leave it blank. GATE_WEBHOOK: a Slack incoming webhook or anything that accepts a JSON post. That is how Bellows pings Priya.
Then set them in your shell. Do not paste values into the terminal from a password manager on a shared screen.
Vercel builds every branch into a preview URL. Gauge runs its tests against that URL and Beacon walks the customer journey on it. Install the CLI, sign in, link the folder to a new project. Then connect the GitHub repo in the Vercel dashboard so every pushed branch gets a preview. That is the default when a Git repo is connected; check the project's Git settings.
Add the app's environment variables in Vercel under Project → Settings → Environment Variables. Never through an agent. The secrets gate exists so that never happens by accident.
vercel link asks change between versions. Check vercel.com/docs/cli.
MCP servers are how the Claude agents reach Linear, Notion, GitHub and Vercel. The kit's .mcp.json already declares them at project scope, so copying it in step 5 did most of this. Here it is. Tokens come from the environment you set in step 6 and never from this file.
{
"$comment": "MCP servers the crew can reach from Claude Code in this repo. Tokens come from the environment, never from this file. Linear and Notion are hosted servers (OAuth on first use); Outline is a small local bridge if you prefer it to Notion; GitHub and Vercel run locally with npx. Check each server's current install line in its own docs; these were correct when written.",
"mcpServers": {
"linear": { "type": "http", "url": "https://mcp.linear.app/mcp" },
"notion": { "type": "http", "url": "https://mcp.notion.com/mcp" },
"github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } },
"vercel": { "type": "http", "url": "https://mcp.vercel.com" },
"outline": { "command": "node", "args": ["kit/scripts/outline-mcp.mjs"], "env": { "OUTLINE_URL": "${OUTLINE_URL}", "OUTLINE_TOKEN": "${OUTLINE_TOKEN}" }, "$comment": "Only if you use Outline instead of Notion. Remove the notion entry then." }
}
}If you would rather add servers by hand, or want them at user scope so every repo sees them, the commands look like this. Linear and Notion are hosted servers that sign you in through the browser the first time an agent uses them. GitHub runs locally through npx.
Sign in to Linear as the Alderline Crew user when the browser asks. Every comment the agents write will then carry that name and Priya's own comments stay hers.
Theclaude mcp add syntax and the health-check wording are from the Claude Code docs at the time of writing. Verify at code.claude.com/docs. If you use Outline instead of Notion, remove the notion entry and keep the outline one.
Claude Code reads .claude/agents/*.md at start. Open it in the repo and type /agents. You should see the seven Claude agents. Flint and Bellows are not in the list because Flint lives in AGENTS.md for Codex and Bellows is a script.
/agents changes between versions. The seven names are what matters.
One headless call. Ask for Anvil by name and ask it something only CLAUDE.md can answer. If the reply lists the seven states in order, the agent file and the project file are both being read.
Same idea. codex exec runs one prompt without the interactive screen. Ask about Flint. Only AGENTS.md knows who that is.
This is the step that matters. Ask Claude Code to do something the gates forbid. The secrets rule in .claude/gates.json denies any write to a .env file. The guard hook runs before the tool and turns the rule into a refusal the agent has to explain.
Two things happened. The write was refused with the reason from the gates file. And the refusal was logged to telemetry/events.jsonl, which is where the dashboard counts gates from. The shell rules work the same way: ask it to run vercel --prod and the prod-deploy rule turns the command into a question for you instead of a deploy.
Before you leave the workshop, have Claude Code audit the setup. This prompt is the one Priya keeps. She runs it after every change to the kit.
Read CLAUDE.md, .claude/settings.json, .claude/gates.json and .mcp.json. Then check this repository against them and report in a table: 1. Every agent file named in CLAUDE.md exists under .claude/agents/. 2. Every hook command in settings.json points at a file that exists. 3. Every environment variable named in .env.example is set in this shell (say SET or MISSING, never print a value). 4. Every MCP server in .mcp.json answers `claude mcp list` as Connected. 5. No file in the repo matches the secrets rule in gates.json. Do not fix anything. Report only.
claude and codex both open signed ingh auth status shows your accountCLAUDE.md, AGENTS.md, .claude/, .mcp.json and kit/ at the root and one commit on GitHubclaude mcp list shows Linear, Notion (or Outline) and GitHub as Connected/agents lists seven names.env.local was denied with [gate:secrets]Either. Claude Code runs natively on Windows and inside WSL. Codex CLI has been strongest on Mac and Linux; on Windows the safe route is WSL. The hooks and Bellows are plain Node scripts and run wherever Node runs. Priya uses a Mac. Tom's office machine is Windows and runs Bellows in WSL on a schedule. Check the current install notes for both tools before you decide.
Keep Linear for this pack. The kit assumes it: the seven states by name, the issue templates, and the status lines Bellows reads and the states it moves. Jira or GitHub Issues would work in principle but Bellows would need rewriting where it talks to Linear, and the MCP entry would change. Get the loop running once as written. Then decide whether the swap is worth it.
Three places and none of them is the repo. Priya's shell profile, for everything Bellows and the hooks read. The Vercel project's environment variables, for everything the app reads. And the browser sign-ins for the hosted Linear and Notion servers, which Claude Code stores for you. .env.example carries names only. The guard denies any write to a .env file and the after-edit hook shouts if a key lands in an ordinary file. If a key ever does leak, rotate it first and ask questions second.
Both. Interactive Claude Code and Codex sessions run where you type. Bellows runs on a schedule on any always-on machine: a spare laptop, a GitHub Action every ten minutes, or a small VPS. Wherever it runs it needs Node, claude and codex installed and signed in, and the environment variables set. The agents it starts run on that machine too. Chapter 11 covers the scheduling.
The script itself costs nothing. A tick with nothing to do is one call to Linear. Cost comes from the agent runs it starts. The gates file caps those: runs per issue per day, minutes per run, review rounds and QA fails. A loop that gets stuck asks you instead of spending. On a quiet day Bellows runs every ten minutes and starts nothing. On a build day it might start twenty agent runs. Your subscriptions cover that up to their limits. The dashboard shows minutes per agent so you can see it.
A repo with the crew in it and no product code. Two signed-in runtimes that each know who they are. Linear, Notion, GitHub and Vercel reachable from inside Claude Code. Six environment variables set where the agents can read them and nowhere they can write them. And proof, in one log line, that the guard stops a forbidden write before it happens.
Next: Chapter 2 · The loop. The six stages every request goes through, who owns each one, and why the loop closes back on itself.