# Codex setup — PsychArch Reader

> Send every completed Codex reply to PsychArch Reader: install the CLI, sign in, install the hook, and verify.

Every completed Codex reply is saved to your private Reader library as Markdown. Replies expire after three days by default.

Agents: run the steps in order, one command at a time, and wait for each to finish. This page is also available as [Markdown](https://reader.psycharch.com/intro/codex/index.md); fetch it with `curl -fsSL` if browsing fails. No repository, source code, or OAuth registration is needed.

## 1. Install the CLI

```
curl -fsSL https://reader.psycharch.com/intro/install.sh | sh
psycharch-reader version
```

This installs the latest Reader CLI to `~/.local/bin`. If the command is not found, run `export PATH="$HOME/.local/bin:$PATH"`. On Windows, download the ZIP from the [Download page](https://reader.psycharch.com/intro/download/#cli) and put `psycharch-reader.exe` on PATH.

## 2. Sign in

```
psycharch-reader auth status
```

If it reports `Logged in.` for `https://reader.psycharch.com`, go to step 3. Otherwise, sign in as the account that runs Codex.

On a desktop (macOS Keychain, Windows Credential Manager, or an unlocked Linux keyring):

```
psycharch-reader doctor
psycharch-reader login --open
```

On a remote or headless Linux machine, use encrypted systemd storage (systemd 256+):

```
psycharch-reader doctor --credential-store systemd-creds
psycharch-reader login --device --credential-store systemd-creds
```

If doctor does not report `ready`, use `--credential-store file` in both commands instead. File storage keeps tokens unencrypted, readable only by your account.

**Device login prints a URL and a code.** Give the user that exact URL, keep the command running, and wait until it prints `Logged in.` Do not run other Reader commands meanwhile.

## 3. Install the hook

```
psycharch-reader hooks codex install --ttl 3d
psycharch-reader hooks codex test
```

Retention can be `1h`, `1d`, `3d`, or `7d`. The installer adds an asynchronous `Stop` hook to `config.toml`, preserving other settings and hooks. Run the installer again after updating the CLI to keep the hook current. The test should print `Local simulation passed.`

Proposed plans are included by default, including for existing hooks after upgrading the CLI. To disable them:

```
psycharch-reader hooks codex install --upload-plans=false
```

Use `--upload-plans=true` to enable them again. Reinstalling without this flag preserves your saved preference. The local test checks reply delivery and plan recovery using synthetic content.

## 4. Test and restart

```
psycharch-reader hooks codex test --upload
```

This uploads one test document and prints `Test document: https://reader.psycharch.com/doc/...`. Share that link with the user; it opens in their signed-in Reader.

**Restart Codex and review/trust the new hook when prompted**, then check that the next reply appears once in Reader. Until then, report setup as installed but not yet confirmed.

## What gets sent

Only completed main-thread replies, titled `Codex · project`. In Plan mode, the final reply and proposed plan are saved together as one document, with Markdown preserved and plan wrapper tags removed. Internal title generation and subagent replies are excluded.

To recover a plan, the hook reads the matching session and turn in the local transcript supplied by Codex. Prompts, reasoning, tool output, and the rest of the transcript stay local. If recovery fails, the hook reports it and sends the supplied reply when available. Replies up to 1 MiB are sent; failed uploads retry for up to a minute and are not queued.

## If setup fails

- `another Reader CLI command is active`: wait for the other command, including a pending login, to finish.

- `log in to Reader before installing the hook`: finish step 2.

- Credential store errors: run `psycharch-reader doctor` as the account that runs Codex. A Linux keyring needs D-Bus and an unlocked Secret Service.

- Daily upload limit: the error shows when you can upload again.

## Remove the hook

```
psycharch-reader hooks codex uninstall
```

Restart Codex afterwards. `psycharch-reader logout` signs the CLI out.