# Thread Workspace Relink

> Relink Codex threads to a new workspace folder path after a local folder rename. Use when chats appear under an old folder, show "working directory missing", or jump folders after opening due to stale state/index. Performs safe backup-first migration of JSONL cwd fields plus SQLite thread cwd index and verifies old/new counts.

- **Type:** Skill
- **Install:** `agentstack add skill-adam-bull-codex-thread-toolkit-thread-workspace-relink`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Adam-Bull](https://agentstack.voostack.com/s/adam-bull)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Adam-Bull](https://github.com/Adam-Bull)
- **Source:** https://github.com/Adam-Bull/Codex-thread-toolkit/tree/main/skills/thread-workspace-relink

## Install

```sh
agentstack add skill-adam-bull-codex-thread-toolkit-thread-workspace-relink
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Thread Workspace Relink

Use this skill to migrate Codex thread workspace paths from `old_path` to `new_path` safely and repeatably.

## Workflow

1. Confirm target and scope
- Collect `old_path` and `new_path`.
- Decide scope: `all` affected threads or selected `thread_ids`.

2. Run dry-run first
- Use script in `scripts/relink_thread_workspaces.py` with `--mode dry-run`.
- Review affected counts and files before writing.

3. Apply with backup
- Run with `--mode apply`.
- Script creates timestamped backup under `~/.codex/path_rename_backup_*`.
- Script updates:
  - Session JSONL `cwd` fields (`sessions/`, `archived_sessions/`)
  - State DB `threads.cwd` in `~/.codex/state_*.sqlite`

4. Verify
- Confirm old count is `0` for migrated scope.
- Spot-check requested thread IDs.
- If no compatible DB is discovered, run `--diagnose` and inspect `db_search_roots`, `db_candidates`, and `compatible_dbs`.

5. Refresh UI
- Quit/reopen Codex after apply so sidebar grouping refreshes.

## Commands

Dry-run all:
```bash
python3 scripts/relink_thread_workspaces.py \
  --old "/old/path" \
  --new "/new/path" \
  --mode dry-run \
  --scope all
```

Apply all:
```bash
python3 scripts/relink_thread_workspaces.py \
  --old "/old/path" \
  --new "/new/path" \
  --mode apply \
  --scope all
```

Dry-run selected thread IDs:
```bash
python3 scripts/relink_thread_workspaces.py \
  --old "/old/path" \
  --new "/new/path" \
  --mode dry-run \
  --scope ids \
  --ids "id1,id2,id3"
```

Apply selected thread IDs:
```bash
python3 scripts/relink_thread_workspaces.py \
  --old "/old/path" \
  --new "/new/path" \
  --mode apply \
  --scope ids \
  --ids "id1,id2,id3"
```

Diagnose DB discovery:
```bash
python3 scripts/relink_thread_workspaces.py \
  --old "/old/path" \
  --new "/new/path" \
  --mode dry-run \
  --scope all \
  --diagnose
```

Deep diagnostics (recommended for issue triage):
```bash
python3 scripts/relink_thread_workspaces.py \
  --old "/old/path" \
  --new "/new/path" \
  --mode dry-run \
  --scope all \
  --diagnose-deep
```

## Guardrails

- Do not bulk-rewrite arbitrary text/history; only structured `cwd` surfaces.
- Always run `dry-run` before `apply`.
- Always create backup before writes.
- Keep rollout reversible via backup restore.
- If JSONL matches exist but no compatible DB is found, `apply` exits with an error by default.
- Use `--db-path "/path/to/state_x.sqlite"` to include explicit DB files when discovery misses your active state DB.
- Use `--allow-jsonl-only` only when JSONL-only migration is intentional.

## Compatibility Note

- This skill targets current Codex local state surfaces (`sessions/*.jsonl`, `archived_sessions/*.jsonl`, `state_*.sqlite` with `threads.cwd`).
- Codex versions can change storage/schema details over time.
- Always run `dry-run` first and review counts before `apply`.
- If expected tables/fields are missing, stop and inspect local state layout before writing.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Adam-Bull](https://github.com/Adam-Bull)
- **Source:** [Adam-Bull/Codex-thread-toolkit](https://github.com/Adam-Bull/Codex-thread-toolkit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-adam-bull-codex-thread-toolkit-thread-workspace-relink
- Seller: https://agentstack.voostack.com/s/adam-bull
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.