Install and first run

Guild Stack installs into the AI coding tool you already use and is driven with /guild: commands. This page gets you from nothing to a first, checked change. Start at the top; the Power and Architect layers further down add update control and the receipt internals when you want them.

The install route: clone the release, run install.sh, get a per-tool install receipt, open a new session and see the /guild: commands. — Open full size

Install Guild Stack

This page installs Guild Stack v3.0.0, the current stable release, into Claude Code. You need git, bash, node, and the Claude Code command-line tool (claude) on your machine.

1. Try the install in a test folder

Run these lines in any empty folder. They install Guild Stack into a throwaway home folder, so your real setup is not touched yet:

GUILD_PLUGIN_ROOT=https://github.com/lookatitude/guild.git
GUILD_PLUGIN_SHA=v3.0.0
git clone -q "$GUILD_PLUGIN_ROOT" src
git -C src checkout -q "$GUILD_PLUGIN_SHA"
mkdir home
HOME="$PWD/home" bash src/install.sh --host claude-code-cli

The first two lines say where Guild Stack comes from and which release to use.
git clone downloads Guild Stack into a folder called src.
git checkout picks the exact 3.0.0 release.
The last line installs Guild Stack into the test folder home.

Our test suite runs these same four lines (from git clone on) when it checks a release.

2. Install for real

When the test looks good, run the install line again without the HOME="$PWD/home" part. This installs Guild Stack into your own Claude Code:

bash src/install.sh --host claude-code-cli

Shortcut

The home page shows this one-line installer (its host tabs add the matching --host flag). The steps above are the ones our test suite checks, so start with those.

curl -fsSL https://guildstack.dev/install.sh | bash

3. Check that it worked

Two files tell you the install worked:

~/.claude/plugins/installed_plugins.json has an entry called guild@guild with version 3.0.0.
~/.guild/receipts/claude-code-cli.json is Guild Stack's own install receipt. It records the version and the exact source commit.

cat ~/.guild/receipts/claude-code-cli.json

4. Open Claude Code

Start a new Claude Code session inside one of your projects:

cd your-project
claude

Type /guild: and you should see Guild Stack's commands in the list.

Your first task

Your first task has three steps. First, Guild Stack learns your project. Second, it makes one small change for you. Third, you check the result.

1. Let Guild Stack learn your project

Inside Claude Code, in your project folder, type:

/guild:init

Guild Stack reads your code and writes notes about it into a new .guild/ folder. It does not change your code or your tests.

When it finishes, you have:

.guild/settings.json: Guild Stack's settings for this project.
.guild/wiki/index.md: the start page of your project's notes.
.guild/wiki/concepts/architecture-map.md: a first draft of how your code fits together.
.guild/indexes/codebase-map.json: a map of your files and which file uses which.
.guild/init/<project>.md: a short record of what init did.

Guild Stack may ask you a few questions along the way. Accepting the defaults is fine.

2. Ask for one small change

Pick something small and easy to check. For example, a --version flag:

/guild:guild add a --version flag to src/index.js that prints the version from package.json

/guild:guild is the front door. It looks at your request and your project, then suggests where to start. It asks before it does anything big.

For a small change like this, Guild Stack goes through four steps:

Ideate: it writes down exactly what you want.
Plan: it decides who does what.
Build: it makes the change.
QA (quality check): it tests the change and writes down the result.

You can also run each step yourself: /guild:ideate, /guild:plan, /guild:build, /guild:qa.

3. Check the result

Your change is in your code. In this example, node src/index.js --version prints the version.
Only the file you asked about changed.
Guild Stack wrote a check report at .guild/runs/<run-id>/verify.md. Look for a line that says the result passed.
Your tests still pass.

Review the change with git diff, then commit it yourself.

Updates and release channels

Guild Stack updates the same way it installs: with one script. This page shows how to update, how to pick a release channel, and how to turn the update notice off.

Update now

Run the install command again with --update:

curl -fsSL https://guildstack.dev/install.sh | bash -s -- --update

--update re-installs every tool that has an install receipt (see below). It does not ask you which tools to use. If there are no receipts, it stops (exit 1) and looks for a Guild Stack install made by the tool's own plugin manager. What it prints depends on what it finds:

Claude Code install: the Claude update command (claude plugin marketplace update guild && claude plugin update …).
Codex install from a git marketplace: the Codex update command (codex plugin marketplace upgrade && codex plugin add …).
Codex install from a local marketplace directory: Codex cannot refresh it, so run a normal install (not --update), for example with --host codex-cli.
Codex install whose marketplace source it cannot read: both options, git command or normal install.
Nothing found: run a normal install once first.

The first install uses the same script:

curl -fsSL https://guildstack.dev/install.sh | bash

Release channels

A channel is the line of releases you follow. There are two:

Channel	Git branch	What it is
`stable`	`main`	Released versions. This is the default.
`beta`	`next`	Builds that are ahead of the release. New features land here first.

Pick a channel with the --channel flag or the GUILD_CHANNEL environment variable:

curl -fsSL https://guildstack.dev/install.sh | bash -s -- --channel beta
curl -fsSL https://guildstack.dev/install.sh | GUILD_CHANNEL=beta bash

The channel chooses which branch the script downloads when it is not running from a checkout. If you run the script from a local checkout of the Guild Stack repo, it installs that checkout and ignores --channel. To test beta from a checkout, check out the next branch there. GUILD_SOURCE_REF picks the git ref only for the download path, not for a local checkout.

Install script flags

Pass flags after bash -s --.

Flag	What it does
`--dry-run`	Prints what would run. Changes nothing.
`--host HOST`	Installs into one tool.
`--hosts A,B,C`	Installs into a comma-separated list of tools.
`--yes`, `-y`	Agrees to a write into more than one tool without asking.
`--project`	Installs for the current directory only, not for your user.
`--channel C`	`stable` or `beta`.
`--update`	Re-installs every tool that has a receipt.

With no --host, the script installs into every supported tool it finds. If that means more than one tool, it needs your agreement: --yes, or a y/N answer at the terminal. It never writes to several tools silently. It never uses sudo and never edits your shell profile.

Install receipts

Each install writes a small JSON file per tool under ~/.guild/receipts/. It records the tool, the channel, the git ref, the commit, the version, and the install time. --update reads these files to know what to re-install and which channel each tool follows. To move every tool to one channel, set GUILD_CHANNEL, for example GUILD_CHANNEL=stable. --channel beta also overrides the receipts. --channel stable does not: it is the default, so a tool whose receipt says beta stays on beta.

The update notice

On Claude Code and Codex, Guild Stack runs a check each time a session starts. It does not use the network while your session starts. It reads a cached answer from ~/.guild/update-check.json. When the cache is older than the cadence, a background process refreshes it, so the notice appears in your next session. If anything goes wrong, the check stays silent and your session is not slowed. A development checkout never shows a notice.

You control it in your Guild Stack settings:

Setting	Values	Default
`defaults.update.mode`	`notify`, `auto`, `off`	`notify`
`defaults.update.cadence_hours`	a number above 0	`24`

notify prints a one-line notice when a newer version exists.
auto also stages the update. It takes effect the next time you start the tool, because Claude Code loads plugins at startup.
off turns the check off.

auto works only on tools that can apply it. On the others, it falls back to notify and prints how to update.

What the install receipt proves

Each install writes one JSON receipt per tool under ~/.guild/receipts/ (the fields are listed under Install receipts above). Because the receipt pins the exact source commit, two things follow:

Updates are grounded. --update re-installs exactly the tools that have a receipt, each on its own recorded channel. There is no guessing from the filesystem.
The install is attributable. The receipt records the exact commit that was installed. For a stable 3.0.0 install that is the tagged release commit; the release's conformance evidence is hash-bound to a source commit in that release's history, so the receipt lets you walk from the bytes on your machine to the release and from the release to its evidence. A beta install or a local checkout records its own commit instead. The receipt stays honest about what you actually ran. How the release record is produced and signed is covered in Conformance and evidence.

Our release test suite runs the same install script lines shown above, character for character, before a release ships.