> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qredence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex worktree setup for Fleet Pi

> Bootstrap Codex worktree threads against Fleet Pi using the shared .codex local environment, the workspace-bootstrap.zsh script, and advanced multi-agent flow.

This is the advanced path. For the recommended public setup, start with the [quickstart](/fleet-pi/quickstart).

Fleet Pi ships a shared Codex local environment so new Codex worktree threads can bootstrap the repo consistently.

## Shared environment

* Environment definition: `.codex/environments/environment.toml`
* Setup entrypoint: `.codex/workspace-bootstrap.zsh`

Open the Fleet Pi repo in the Codex app and choose the shared local environment when starting a worktree-backed thread.

## Setup behavior

The current setup script is intentionally bootstrap-only:

```zsh theme={null}
pnpm install --frozen-lockfile
```

This matches the repo's normal dependency flow and keeps worktree creation predictable.

Setup stays separate from canonical workspace state: `agent-workspace/` remains the durable adaptive layer, while Codex setup only bootstraps the local worktree so later commands can operate on the repo safely.

## Expectations

* `node` and `pnpm` must already be available on the machine.
* The script should stay focused on dependency and bootstrap work.
* Do not put long-running processes in the setup script.
* Do not rely on `export` statements in the setup script for later Codex turns — setup runs in a separate shell session.

## Suggested Codex actions

After the worktree is ready, add separate Codex actions for the common repo workflows so each action can be invoked independently from a Codex thread:

```zsh theme={null}
pnpm dev
pnpm typecheck
pnpm lint
pnpm --filter web test
pnpm e2e
```

## Related

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/fleet-pi/quickstart">
    Standalone setup without the Codex worktree flow.
  </Card>

  <Card title="Adaptive workspace contract" icon="file-contract" href="/fleet-pi/adaptive-workspace">
    Why setup scripts must not touch canonical workspace state.
  </Card>
</CardGroup>