The easy installation path is not a replacement for the Osprey Strike README. The README is where the real commands live, and it should stay that way because it sits beside the code it configures. This cairn is the missing wrapper around it: the prerequisites, the order of operations, the places new developers usually hesitate, and the definition of “done enough to start.”

If you have already read The Workshop, you know the tool map. This cairn turns the map into a first-day route. It is intentionally narrower than Your Box and Your Trust Model: not the security philosophy, not every permission mode, not every optional tool. Just the shortest path to a working checkout.

What to have before you clone

Before You Start

  • Time required: 2–3 hours for beginners; 30–45 minutes for developers
  • Disk space required: At least 40GB free (setup uses approximately 34GB)
  • How to check disk space: Apple menu → About This Mac → Storage

Start with identity, not tools. A Constructured developer setup begins with GitHub because the code, the issues, the pull requests, and the automation all assume GitHub as the shared surface. You need a GitHub account that has access to the Constructured organization and the osprey-strike repository. If the repo is invisible to you, no local install sequence will fix that.

Then set up SSH authentication for GitHub. HTTPS clones can work, but SSH is the least surprising path once agents, hooks, and repeated repository operations enter the loop. The goal is simple: from a terminal, GitHub should recognize the key on your machine.

ssh -T git@github.com

The successful response usually says GitHub authenticated you but does not provide shell access. That is expected. If the command asks for a password, rejects the key, or identifies the wrong account, stop and fix GitHub SSH before cloning Strike.

Tip

Use GitHub’s own SSH-key guide when setting this up. Key generation and agent configuration differ enough across macOS, Linux, and Windows that copying a stale internal snippet is worse than linking to the maintained source.

Install the GitHub CLI as well. gh is not just convenience; it is how agents inspect pull requests, comments, checks, and GitHub API state without turning browser work into manual ceremony. The first local check is:

gh auth status

If the wrong account is active, fix that before continuing. If you use multiple GitHub identities on one laptop, make the Constructured identity explicit in your SSH config and gh auth state; ambiguity here becomes a strange failure later.

Claude Desktop versus Claude Code

If you are currently chatting with Claude in a browser or app, that is Claude Desktop. That is NOT what you need for development — Claude Code is a separate tool that lives in your terminal.

The phrase “install Claude” is overloaded enough to slow people down. Claude Desktop is a desktop chat client. It is useful when you want a GUI, local MCP connections, or a conversational workspace. Claude Code is the coding-agent harness this trail assumes: it sees the repo, edits files, runs shell commands, and participates in the review loop.

For development on Strike, install Claude Code. If you also want Claude Desktop, install it too, but do not treat Desktop as the coding harness. When the trail says the agent runs just check, reads .beads/issues.jsonl, or follows AGENTS.md, that is Claude Code or another terminal-connected coding agent doing the work.

Warning

During setup, opt out of vendor training, telemetry, or “help improve” sharing when the tool gives you the choice. Do this for Claude, GitHub Copilot, and any other agent harness you bring into Constructured work.

Codex is a valid alternative or second-opinion tool, covered later in Codex as Second Opinion. It does not change the day-zero sequence: GitHub access first, repo clone second, project setup third, verification last.

Let the README own the commands

Once identity and the harness are ready, switch to the README. The day-zero shape is two layers: a small manual bootstrap, then the project-pinned toolchain. Install mise first and follow the README for any remaining manual bootstrap notes, especially beads. Do not add a separate timbers installer; timbers is now part of the repo’s mise-managed project toolchain.

mise is the version manager that reads .mise.toml and installs the actual project stack. beads remains a manual bootstrap tool because it owns the repo-local issue graph. timbers is still required in the Constructured workflow, but mise install should provide it for this repo.

After installing mise, add its shell hook and restart the terminal, exactly as the README says. That restart matters. Many “mise is broken” setup sessions are just an old shell that has not loaded the activation hook.

Note: After mise installs, it will print several commands for you to run. Run all of them before continuing. Then close and reopen your terminal before running mise doctor.

Then clone the repo and let the project take over:

git clone <repo-url>
cd osprey-strike
mise trust
mise install

mise trust approves the repo’s .mise.toml on your machine. mise install installs the pinned tools: Go, Node, just, direnv, timbers, and the DevOps surface the repo knows about. You are not choosing versions by hand; the project is.

Next, install and configure direnv:

  1. Install direnv:

    brew install direnv

  2. Add the hook to your shell profile:

    echo 'eval "$(direnv hook zsh)"' >> ~/.zprofile

  3. Reload your profile:

    source ~/.zprofile
Key Takeaway

The invariant is simple: install the small bootstrap layer manually, then let the repo install the project layer. If you are installing Go, Node, just, or timbers by hand to make Strike work, you are probably fighting the intended path.

The repo-local setup

The next step is local state. Strike needs a per-checkout environment file, package dependencies, and git hooks. The README’s setup command handles the boring parts:

Before running setup, copy the example environment file:

cp .envrc.example .envrc

Note: The instructions below say just setup handles this automatically, but in practice it doesn’t always run — copy the file manually to be safe.

just setup
direnv allow

just setup creates .envrc from .envrc.example if .envrc does not already exist, installs package dependencies, and wires the repo hooks. It should be idempotent: safe to rerun and careful not to overwrite local secrets. direnv allow is the trust handshake. It tells your shell, “yes, this checkout is allowed to load this .envrc when I enter the directory.”

That handshake is deliberate. .envrc controls service URLs, database settings, encryption keys, local integration values, and other settings that should be local to the checkout. If .envrc changes later, direnv will ask again. Treat that prompt as a useful stop sign, not friction.

Docker is the other practical prerequisite. You do not need it to read code, run unit tests, or browse the repo, but you do need a running Docker daemon for the local service stack and integration tests. Docker Desktop and Colima are both acceptable.

On a Mac: Download the Apple Silicon version if you have a newer Mac (2020 or later).

Once Docker is running, the README’s service path is:

Important: Each of the commands below takes over the terminal window and keeps running in the background. Press Cmd + T to open a new terminal tab before running each one. Run them in the order listed, one per tab.

just services up
just mock dev
just api dev
just web dev

The mock server comes before the API and web app because it simulates integrations they expect to call. On a first database run, follow the README’s seed step before expecting realistic local data.

The verification pass

Installation is not complete when the commands stop scrolling. It is complete when the boring checks all pass. Two commands cover it, run from the osprey-strike repo root:

just doctor   # every readiness check in one shot
just check    # the quality gate

Known issue: When running just check you may see failing tests in createEco.helpers.spec.ts — these are known pre-existing issues and will not affect your work.

just doctor is the readiness sweep. It proves GitHub identity (ssh -T git@github.com and gh auth status), runs mise doctor, confirms the toolchain, .envrc, and git hooks, and — the part that earns its keep — runs bd ready and timbers pending rather than only checking that bd and timbers are on PATH. A binary that is installed but cannot read the repo’s issue graph is exactly the half-configured failure this pass exists to catch. Each problem prints a warning with its fix; a clean run ends in “ready to develop.”

just check is separate on purpose. It is the quality gate — it builds the web app and runs the test suites — so it is slow and belongs before your first commit, not inside a fast readiness probe. just doctor answers “is my environment wired correctly?”; just check answers “does the code pass?” Folding the second into the first would turn a ten-second sanity check into a multi-minute build.

If you would rather run the underlying checks by hand — to learn the moving parts, or to debug a just doctor warning — this is what it checks:

Check Proves
ssh -T git@github.com GitHub recognizes your SSH key
gh auth status the GitHub CLI is authenticated
mise doctor the version manager is healthy
just --list the project command surface loads
bd ready beads can read the repo’s issue graph
timbers pending the ledger is readable, and whether it is clean
claude --version the harness is on PATH

On a fresh clone, just doctor (or bd ready on its own) may report that the embedded database has not been initialized. Bootstrap from the committed issue graph — just doctor prints these exact lines when it detects that state:

bd bootstrap
bd config set beads.role maintainer
bd ready

Use contributor instead of maintainer if you are outside the organization. Do not run bd init in an existing project clone; that creates a new beads identity for a new project, which is not what you want.

Warning

Do not skip the verification pass because the app “seems to run.” Most painful day-two setup bugs are not dramatic failures; they are half-configured shells, untrusted env files, missing hooks, unauthenticated GitHub CLIs, or a Docker daemon that was never started — exactly the things just doctor now surfaces as warnings instead of letting them bite you on day two.

Where to go next

Once this passes, you have a working box, not mastery of the workflow. The next cairns explain what each tool is for: Beads, the Backbone for the issue graph, Timbers, the Ledger for the development ledger, Claude Code as Daily Driver for the harness, and Just: One Place to Discover for the command surface.

If your setup failed, go back to the README before improvising. The README lives with the code, so it is the first place that should change when setup changes. A cairn can teach the path, but the repo should own the commands.

Starting Work Each Day

The four service commands you ran during setup do not stay running when you close your computer — you will need to restart them each time you start a new work session.

Before running any of the service commands, make sure Docker is open and running (you should see the Docker icon in your menu bar).

Once Docker is running, open four terminal tabs (Cmd + T) and run each service command in its own tab, in the same order as during setup.

Summary

  1. Start with access. You need the right GitHub account, Constructured repo access, SSH auth, and gh auth status clean before cloning.
  2. Install the right Claude surface. Claude Desktop is useful, but Claude Code is the coding harness this trail assumes.
  3. Let the README own exact commands. This cairn gives the sequence; osprey-strike/README.md is the source of truth for setup commands.
  4. Bootstrap manually, then let mise work. Install mise and beads by hand; let mise install install Go, Node, just, direnv, timbers, and the pinned project stack.
  5. Finish with verification. A ready machine passes just doctor — GitHub auth, mise, hooks, beads, and timbers all green in one sweep — and then a passing just check.
  • Which setup step is most likely to be unclear to someone joining from a non-agent workflow: GitHub SSH, Claude Code, mise, direnv, or beads?
  • What belongs in this cairn versus the Strike README? Where would duplication become more dangerous than helpful?
  • If a new developer can only send one screenshot or terminal paste to prove setup health, should it be just doctor, just check, or something else?
  1. Osprey Strike README - The canonical source for current setup commands, service startup, database seeding, and troubleshooting.
  2. GitHub SSH documentation - The maintained guide for creating SSH keys, adding them to GitHub, and testing authentication.
  3. GitHub CLI - Required for the pull-request and review loop that agents use heavily.
  4. Claude Code quickstart - The coding-agent harness assumed by this trail.
  5. mise - The runtime version manager that installs the project-pinned toolchain from .mise.toml.
  6. direnv - The per-directory environment loader behind the direnv allow trust handshake.
  7. The Workshop - The broader tool map this installation path turns into a day-zero sequence.
  8. Your Box and Your Trust Model - The deeper explanation of mise, Docker, direnv, sandboxing, and BYOD trust posture.

Glossary

Term Plain-English meaning
Terminal A text-based window where you type commands directly to your computer instead of clicking buttons. Also called the command line.
SSH A secure way for your computer to talk to another computer (like a server) over the internet.
CLI Command-Line Interface — a tool you use by typing commands in the terminal rather than through a visual app.
PATH A list your computer keeps of folders where it looks for programs. When you install a tool, its location needs to be on your PATH so your terminal can find it.
direnv A tool that automatically loads environment variables (settings specific to a project) when you navigate into a project folder in the terminal.
Docker A tool that packages software and everything it needs to run into a self-contained unit called a container, so it works the same way on any computer.
Daemon A program that runs silently in the background, waiting to do its job (like Docker running behind the scenes so your services can start).
Repo Short for repository — a folder that contains a project’s code and its full history of changes, managed by Git.
Clone Downloading a copy of a repo from GitHub to your own computer so you can work on it locally.
mise A version manager — a tool that installs and manages different versions of programming languages and developer tools on your computer.