---
name: phasedrift-project-setup
description: Connect a project to local PhaseDrift collection and install CLI-based session review instructions.
---

# Project setup

Use for an owner-authorized target. Preserve its dirty work, instructions, databases, and live locks. Never commit or change Git hooks.

1. Install a release with `bun scripts/install-cli.ts`, or build the source then run `bun run install:cli`. The launcher uses a versioned installed release.
2. From the authorized target repo run `phasedrift init`. It chooses a port and storage, starts collection, installs the review workflow, and queues/reuses the 10+20 history samples. Existing live connections are adopted without replacing their stores.
3. Run `phasedrift session setup --upgrade --hooks` to refresh the shared reporting skill and the shared AGENTS.md instructions and the Gemini GEMINI.md bridge. Run `phasedrift harness status` to check local OpenCode, Grok Build, Claude Code, Gemini CLI and Cursor collection. Run `phasedrift open` and verify the real timeline. Use `phasedrift status`, `phasedrift doctor` and `phasedrift projects` for collection status and project switching.
4. The active target agent runs `phasedrift session start`, then submits genuine checkpoint reports. Do not invent native identities or use another task's identity.
5. Structural collection runs while the tracker runs. Initial setup queues a full working-copy baseline; later full scans are explicit in Code health. `phasedrift stop` stops a verified managed tracker; `phasedrift service install|remove` explicitly controls macOS login startup. Never remove live locks.
6. Repeat init to verify replay; it preserves collection settings and retained partial history. Retry analyzer coverage explicitly instead of making setup repeat expensive scans.
7. Include Jev in setup: check `phasedrift learning status` and report credential presence, policy and saved classifications. Put a supplied server-side `TYPESAFE_API_KEY` in this connected project's root `.env.local`, never display it, and restart only the verified project tracker if needed. When the owner's setup request authorizes analysis, run `phasedrift init --analysis` (new allowance: 10 requests per UTC day, one per batch, concurrency one; existing limits preserved). For older CLIs, use the explicit policy command in [Jev setup](../phasedrift/references/jev-analysis.md). Without a supplied key, return the key location and keep local reporting working. Do not silently turn analysis off or skip describing its setup state.

The current agent submits outcomes, verification, friction, and learning through `phasedrift session review --stdin`; the installed skill provides the example. CLI handles persistence, permissions, evidence binding, and retries. Do not create transport files or copy internal IDs. No separate model calls. Ordinary authorized work continues if capture fails. Owner acceptance remains separate.

## Full historical timelines

For authorized full analysis, use Overview → Re-analyze historical commits. It prepares each revision in a disposable checkout, installs its exact Bun lockfile without lifecycle scripts, and runs all applicable analyzers. Up to 30 commits are sampled per run (newest 10 plus 20 older lifecycle samples including the first two); a small repository with at most 30 first-parent commits includes every commit. 30 is a scan-count bound, not a duration/storage promise; structural scans use local CPU/disk only. Results are recomputed today, not evidence that checks ran at the original date. Partial or unavailable tools stay explicit.

When the tracker is stopped normally, the equivalent CLI is:

```sh
phasedrift history --repo <target> --data-dir <state-directory> --profile full --prepare-dependencies --max-points 30
```

A single committed revision uses `phasedrift scan --repo <target> --data-dir <state-directory> --ref HEAD --profile full --prepare-dependencies`.
Dependency preparation currently supports Bun lockfiles. The exact supported `effect-tsgo patch --typescript --oxlint` preparation is recognized for Effect toolchains; a declared `next typegen` prerequisite generates route types in the disposable revision. Arbitrary lifecycle scripts and project builds are not run. Missing generated inputs may leave an analyzer partial. Local scans use CPU, disk and downloads, without AI calls or token charges. Agent coding and session-summary writing still use the active agent's tokens.