thread-workspace-relink

Name: thread-workspace-relink
Author: Adam-Bull

31stars4forks

How to install thread-workspace-relink?

adam-bull/codex-thread-toolkit/thread-workspace-relink

$npx -y skills add Adam-Bull/Codex-thread-toolkit --skill thread-workspace-relink

Installs into the current project.

Summary

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 SQLi

Files · 1

View on GitHub

SKILL.md

1	# Thread Workspace Relink
2
3	Use this skill to migrate Codex thread workspace paths from `old_path` to `new_path` safely and repeatably.
4
5	## Workflow
6
7	1. Confirm target and scope
8	- Collect `old_path` and `new_path`.
9	- Decide scope: `all` affected threads or selected `thread_ids`.
10
11	2. Run dry-run first
12	- Use script in `scripts/relink_thread_workspaces.py` with `--mode dry-run`.
13	- Review affected counts and files before writing.
14
15	3. Apply with backup
16	- Run with `--mode apply`.
17	- Script creates timestamped backup under `~/.codex/path_rename_backup_*`.
18	- Script updates:
19	- Session JSONL `cwd` fields (`sessions/`, `archived_sessions/`)
20	- State DB `threads.cwd` in `~/.codex/state_*.sqlite`
21
22	4. Verify
23	- Confirm old count is `0` for migrated scope.
24	- Spot-check requested thread IDs.
25	- If no compatible DB is discovered, run `--diagnose` and inspect `db_search_roots`, `db_candidates`, and `compatible_dbs`.
26
27	5. Refresh UI
28	- Quit/reopen Codex after apply so sidebar grouping refreshes.
29
30	## Commands
31
32	Dry-run all:
33	```bash
34	python3 scripts/relink_thread_workspaces.py \
35	--old "/old/path" \
36	--new "/new/path" \
37	--mode dry-run \
38	--scope all
39	```
40
41	Apply all:
42	```bash
43	python3 scripts/relink_thread_workspaces.py \
44	--old "/old/path" \
45	--new "/new/path" \
46	--mode apply \
47	--scope all
48	```
49
50	Dry-run selected thread IDs:
51	```bash
52	python3 scripts/relink_thread_workspaces.py \
53	--old "/old/path" \
54	--new "/new/path" \
55	--mode dry-run \
56	--scope ids \
57	--ids "id1,id2,id3"
58	```
59
60	Apply selected thread IDs:
61	```bash
62	python3 scripts/relink_thread_workspaces.py \
63	--old "/old/path" \
64	--new "/new/path" \
65	--mode apply \
66	--scope ids \
67	--ids "id1,id2,id3"
68	```
69
70	Diagnose DB discovery:
71	```bash
72	python3 scripts/relink_thread_workspaces.py \
73	--old "/old/path" \
74	--new "/new/path" \
75	--mode dry-run \
76	--scope all \
77	--diagnose
78	```
79
80	Deep diagnostics (recommended for issue triage):
81	```bash
82	python3 scripts/relink_thread_workspaces.py \
83	--old "/old/path" \
84	--new "/new/path" \
85	--mode dry-run \
86	--scope all \
87	--diagnose-deep
88	```
89
90	## Guardrails
91
92	- Do not bulk-rewrite arbitrary text/history; only structured `cwd` surfaces.
93	- Always run `dry-run` before `apply`.
94	- Always create backup before writes.
95	- Keep rollout reversible via backup restore.
96	- If JSONL matches exist but no compatible DB is found, `apply` exits with an error by default.
97	- Use `--db-path "/path/to/state_x.sqlite"` to include explicit DB files when discovery misses your active state DB.
98	- Use `--allow-jsonl-only` only when JSONL-only migration is intentional.
99
100	## Compatibility Note
101
102	- This skill targets current Codex local state surfaces (`sessions/.jsonl`, `archived_sessions/.jsonl`, `state_*.sqlite` with `threads.cwd`).
103	- Codex versions can change storage/schema details over time.
104	- Always run `dry-run` first and review counts before `apply`.
105	- If expected tables/fields are missing, stop and inspect local state layout before writing.

People who liked this also viewed

6 picks

Type

thread-workspace-relink

31stars4forks

View on GitHub

How to install thread-workspace-relink?

adam-bull/codex-thread-toolkit/thread-workspace-relink

$npx -y skills add Adam-Bull/Codex-thread-toolkit --skill thread-workspace-relink

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Thread Workspace Relink
2
3	Use this skill to migrate Codex thread workspace paths from `old_path` to `new_path` safely and repeatably.
4
5	## Workflow
6
7	1. Confirm target and scope
8	- Collect `old_path` and `new_path`.
9	- Decide scope: `all` affected threads or selected `thread_ids`.
10
11	2. Run dry-run first
12	- Use script in `scripts/relink_thread_workspaces.py` with `--mode dry-run`.
13	- Review affected counts and files before writing.
14
15	3. Apply with backup
16	- Run with `--mode apply`.
17	- Script creates timestamped backup under `~/.codex/path_rename_backup_*`.
18	- Script updates:
19	- Session JSONL `cwd` fields (`sessions/`, `archived_sessions/`)
20	- State DB `threads.cwd` in `~/.codex/state_*.sqlite`
21
22	4. Verify
23	- Confirm old count is `0` for migrated scope.
24	- Spot-check requested thread IDs.
25	- If no compatible DB is discovered, run `--diagnose` and inspect `db_search_roots`, `db_candidates`, and `compatible_dbs`.
26
27	5. Refresh UI
28	- Quit/reopen Codex after apply so sidebar grouping refreshes.
29
30	## Commands
31
32	Dry-run all:
33	```bash
34	python3 scripts/relink_thread_workspaces.py \
35	--old "/old/path" \
36	--new "/new/path" \
37	--mode dry-run \
38	--scope all
39	```
40
41	Apply all:
42	```bash
43	python3 scripts/relink_thread_workspaces.py \
44	--old "/old/path" \
45	--new "/new/path" \
46	--mode apply \
47	--scope all
48	```
49
50	Dry-run selected thread IDs:
51	```bash
52	python3 scripts/relink_thread_workspaces.py \
53	--old "/old/path" \
54	--new "/new/path" \
55	--mode dry-run \
56	--scope ids \
57	--ids "id1,id2,id3"
58	```
59
60	Apply selected thread IDs:
61	```bash
62	python3 scripts/relink_thread_workspaces.py \
63	--old "/old/path" \
64	--new "/new/path" \
65	--mode apply \
66	--scope ids \
67	--ids "id1,id2,id3"
68	```
69
70	Diagnose DB discovery:
71	```bash
72	python3 scripts/relink_thread_workspaces.py \
73	--old "/old/path" \
74	--new "/new/path" \
75	--mode dry-run \
76	--scope all \
77	--diagnose
78	```
79
80	Deep diagnostics (recommended for issue triage):
81	```bash
82	python3 scripts/relink_thread_workspaces.py \
83	--old "/old/path" \
84	--new "/new/path" \
85	--mode dry-run \
86	--scope all \
87	--diagnose-deep
88	```
89
90	## Guardrails
91
92	- Do not bulk-rewrite arbitrary text/history; only structured `cwd` surfaces.
93	- Always run `dry-run` before `apply`.
94	- Always create backup before writes.
95	- Keep rollout reversible via backup restore.
96	- If JSONL matches exist but no compatible DB is found, `apply` exits with an error by default.
97	- Use `--db-path "/path/to/state_x.sqlite"` to include explicit DB files when discovery misses your active state DB.
98	- Use `--allow-jsonl-only` only when JSONL-only migration is intentional.
99
100	## Compatibility Note
101
102	- This skill targets current Codex local state surfaces (`sessions/.jsonl`, `archived_sessions/.jsonl`, `state_*.sqlite` with `threads.cwd`).
103	- Codex versions can change storage/schema details over time.
104	- Always run `dry-run` first and review counts before `apply`.
105	- If expected tables/fields are missing, stop and inspect local state layout before writing.

People who liked this also viewed

6 picks

Type