# codex-relink

![codex-relink CLI hero image](./codex-relink-cli-twitter-image-warya-wayne.png)

`codex-relink` is a small read-only helper for finding missing or hard-to-locate Codex CLI chats that match the current working directory and printing the command needed to resume them.

Use it when a Codex chat looks lost, missing from the picker, or disconnected from the project you were working in, but the local Codex storage still has enough data to find the thread id.

This is especially for chats that do not appear in the Codex CLI resume picker or the Codex Desktop sidebar. Run `codex-relink latest` or `codex-relink list` from the project directory, and it searches local Codex storage directly so you can resume chats that are still in the database.

It reads local Codex storage:

- `~/.codex/state_5.sqlite`
- `~/.codex/sessions/**/*.jsonl`

It does not edit Codex SQLite, global state, `session_index.jsonl`, titles, previews, cwd values, or user data.

## Using Claude Code?

If you use Claude Code instead of the Codex CLI, there is a companion tool, [`claude-relink`](https://github.com/WaryaWayne/claude-relink), that solves this same problem for Claude Code chats — finding missing or hard-to-locate sessions that match the current working directory and printing the command needed to resume them.

It uses the same commands and usage as `codex-relink`. Install it globally:

```bash
npm install --global claude-relink
```

Then run it from the project directory whose Claude Code chats you want to find:

```bash
claude-relink latest
claude-relink list
```

Or run it without installing anything globally:

```bash
npx claude-relink latest
bunx claude-relink latest
```

## Install

Install it globally from npm if you want the `codex-relink` command available everywhere:

```bash
npm install --global codex-relink
```

Then run it from the project directory whose Codex chats you want to find:

```bash
codex-relink latest
codex-relink list
```

You can also run it without installing anything globally:

```bash
npx codex-relink latest
npx codex-relink list
```

Or with Bun:

```bash
bunx codex-relink latest
bunx codex-relink list
```

All three forms use the current working directory as the project to match against local Codex storage.

## Build

```bash
pnpm install
pnpm build
```

## Latest Chat

From any project directory:

```bash
codex-relink latest
```

Or from this checkout without installing:

```bash
node dist/cli.js latest
```

The command finds Codex chats matching `process.cwd()`, selects the newest chat by `updated_at_ms`, `updated_at`, `created_at_ms`, then `created_at`, and prints:

```text
  Copy the command below to resume your chat:

  codex resume <thread-id>
```

If there are no matching chats, it prints a short message for the current directory.

## Pick A Chat

From any project directory:

```bash
codex-relink list
```

Or from this checkout without installing:

```bash
node dist/cli.js list
```

`list` shows an interactive picker, newest first. Rows are numbered so `1` is always the latest matching chat, and the picker stops at the oldest chat instead of wrapping around. Each row includes the number, updated time, short thread id, and title or fallback. Press enter to select the highlighted chat. After selection, the accepted prompt line shows `Chosen ID: <short-id>` before it prints:

```text
  Copy the command below to resume your chat:

  codex resume <thread-id>
```

## Options

Show CLI help:

```bash
codex-relink -h
codex-relink --help
```

Use `--codex-home` when testing against another Codex home directory:

```bash
codex-relink --codex-home /tmp/codex-home latest
```

Normal use does not require `--project`; the current working directory is used automatically.

## Related tools

[`tailings`](https://github.com/WaryaWayne/tailings) — for when you want to gather a directory's *entire* agent history into the folder rather than resume one chat. It pulls the sessions and memories that Claude Code, Codex, OpenCode, and Gemini produced for the current directory into `./AGENTS.md` + `./.tailings/`, so the next agent — in any tool — is instantly caught up.

[`ai-hr`](https://github.com/WaryaWayne/ai-hr) — local AI employee performance reviews for coding agents. It scans your local usage history from Codex, Claude Code, and OpenCode, normalizes token usage, estimates API-equivalent cost, and prints a report card for your AI coding workforce.

## Author

Built by Warya Wayne, `@waryawayne`.

- GitHub: [@WaryaWayne](https://github.com/WaryaWayne)
- X: [@waryawayne](https://x.com/waryawayne)