t3code-session-manager 0.0.0-stage → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (172) hide show
  1. package/.claude-plugin/marketplace.json +21 -0
  2. package/.claude-plugin/plugin.json +19 -0
  3. package/CHANGELOG.md +138 -0
  4. package/LICENSE +21 -0
  5. package/README.md +660 -2
  6. package/README.pt.md +616 -0
  7. package/bin/entry.d.mts +2 -0
  8. package/bin/entry.mjs +19 -0
  9. package/bin/t3sm.mjs +44 -0
  10. package/commands/import.md +30 -0
  11. package/commands/organize.md +36 -0
  12. package/commands/status.md +24 -0
  13. package/commands/sync.md +26 -0
  14. package/dist/apply/apply.js +993 -0
  15. package/dist/apply/claudeWriter.js +168 -0
  16. package/dist/apply/copyTranscript.js +116 -0
  17. package/dist/apply/importer.js +697 -0
  18. package/dist/apply/materialize.js +335 -0
  19. package/dist/apply/waves.js +108 -0
  20. package/dist/assistant/core.js +295 -0
  21. package/dist/assistant/deps.js +256 -0
  22. package/dist/assistant/i18n.js +38 -0
  23. package/dist/assistant/messages.en.js +494 -0
  24. package/dist/assistant/messages.pt.js +495 -0
  25. package/dist/assistant/runner.js +64 -0
  26. package/dist/assistant/steps.js +1362 -0
  27. package/dist/build.json +1 -0
  28. package/dist/cli/applyScreen.js +158 -0
  29. package/dist/cli/commands/accounts.js +254 -0
  30. package/dist/cli/commands/apply.js +199 -0
  31. package/dist/cli/commands/changelog.js +61 -0
  32. package/dist/cli/commands/doctor.js +105 -0
  33. package/dist/cli/commands/help.js +158 -0
  34. package/dist/cli/commands/merge.js +224 -0
  35. package/dist/cli/commands/organize.js +872 -0
  36. package/dist/cli/commands/plan.js +161 -0
  37. package/dist/cli/commands/projects.js +430 -0
  38. package/dist/cli/commands/quarantine.js +203 -0
  39. package/dist/cli/commands/recover.js +230 -0
  40. package/dist/cli/commands/rollback.js +281 -0
  41. package/dist/cli/commands/scan.js +117 -0
  42. package/dist/cli/commands/schedule.js +288 -0
  43. package/dist/cli/commands/start.js +45 -0
  44. package/dist/cli/commands/status.js +615 -0
  45. package/dist/cli/commands/sync.js +336 -0
  46. package/dist/cli/commands/update.js +398 -0
  47. package/dist/cli/errors.js +53 -0
  48. package/dist/cli/failures.js +91 -0
  49. package/dist/cli/flags.js +53 -0
  50. package/dist/cli/help.en.js +549 -0
  51. package/dist/cli/help.pt.js +566 -0
  52. package/dist/cli/helpText.js +211 -0
  53. package/dist/cli/helpTopics.js +58 -0
  54. package/dist/cli/locked.js +12 -0
  55. package/dist/cli/main.js +155 -0
  56. package/dist/cli/screen.js +3 -0
  57. package/dist/cli/ui.js +111 -0
  58. package/dist/cli/words.js +2 -0
  59. package/dist/core/activity.js +16 -0
  60. package/dist/core/changelog.js +47 -0
  61. package/dist/core/config.js +530 -0
  62. package/dist/core/fsutil.js +171 -0
  63. package/dist/core/glob.js +34 -0
  64. package/dist/core/history.js +32 -0
  65. package/dist/core/journal.js +274 -0
  66. package/dist/core/lock.js +337 -0
  67. package/dist/core/mask.js +31 -0
  68. package/dist/core/paths.js +68 -0
  69. package/dist/core/pid.js +101 -0
  70. package/dist/core/run.js +4 -0
  71. package/dist/core/semver.js +18 -0
  72. package/dist/core/sysroot.js +29 -0
  73. package/dist/core/types.js +229 -0
  74. package/dist/core/uuid.js +29 -0
  75. package/dist/core/version.js +72 -0
  76. package/dist/help/convert.md +20 -0
  77. package/dist/help/convert.pt.md +21 -0
  78. package/dist/help/cwd-unreadable.md +22 -0
  79. package/dist/help/cwd-unreadable.pt.md +22 -0
  80. package/dist/help/decisions.md +20 -0
  81. package/dist/help/decisions.pt.md +20 -0
  82. package/dist/help/errors.md +20 -0
  83. package/dist/help/errors.pt.md +22 -0
  84. package/dist/help/held.md +20 -0
  85. package/dist/help/held.pt.md +20 -0
  86. package/dist/help/history.md +27 -0
  87. package/dist/help/history.pt.md +29 -0
  88. package/dist/help/instance-unavailable.md +18 -0
  89. package/dist/help/instance-unavailable.pt.md +19 -0
  90. package/dist/help/not-imported.md +19 -0
  91. package/dist/help/not-imported.pt.md +19 -0
  92. package/dist/help/orphaned.md +19 -0
  93. package/dist/help/orphaned.pt.md +19 -0
  94. package/dist/help/project-mismatch.md +15 -0
  95. package/dist/help/project-mismatch.pt.md +15 -0
  96. package/dist/help/t3-native.md +22 -0
  97. package/dist/help/t3-native.pt.md +22 -0
  98. package/dist/help/updates.md +26 -0
  99. package/dist/help/updates.pt.md +28 -0
  100. package/dist/help/watcher.md +24 -0
  101. package/dist/help/watcher.pt.md +25 -0
  102. package/dist/i18n/cli.js +41 -0
  103. package/dist/i18n/lang.js +55 -0
  104. package/dist/i18n/messages.en.js +1140 -0
  105. package/dist/i18n/messages.pt.js +1149 -0
  106. package/dist/i18n/words.js +12 -0
  107. package/dist/ops/accounts.js +170 -0
  108. package/dist/ops/autoUpdate.js +223 -0
  109. package/dist/ops/discoverAccounts.js +343 -0
  110. package/dist/ops/doctor.js +811 -0
  111. package/dist/ops/elevated.js +47 -0
  112. package/dist/ops/errorCodes.js +39 -0
  113. package/dist/ops/follow.js +558 -0
  114. package/dist/ops/merge.js +830 -0
  115. package/dist/ops/notify.js +249 -0
  116. package/dist/ops/plugin.js +92 -0
  117. package/dist/ops/projects.js +113 -0
  118. package/dist/ops/quarantine.js +415 -0
  119. package/dist/ops/rollback.js +868 -0
  120. package/dist/ops/schedule.js +464 -0
  121. package/dist/ops/successor.js +51 -0
  122. package/dist/ops/sync.js +859 -0
  123. package/dist/ops/syncStatus.js +290 -0
  124. package/dist/ops/update.js +273 -0
  125. package/dist/ops/updater.js +641 -0
  126. package/dist/ops/watch.js +676 -0
  127. package/dist/ops/watcherControl.js +212 -0
  128. package/dist/ops/watcherHealth.js +75 -0
  129. package/dist/organize/apply.js +495 -0
  130. package/dist/organize/history.js +192 -0
  131. package/dist/organize/plan.js +283 -0
  132. package/dist/organize/rename.js +58 -0
  133. package/dist/organize/sessions.js +100 -0
  134. package/dist/organize/titles.js +70 -0
  135. package/dist/organize/types.js +73 -0
  136. package/dist/plan/categories.js +104 -0
  137. package/dist/plan/dedupe.js +137 -0
  138. package/dist/plan/folders.js +82 -0
  139. package/dist/plan/names.js +93 -0
  140. package/dist/plan/ownership.js +316 -0
  141. package/dist/plan/planner.js +669 -0
  142. package/dist/plan/rehome.js +101 -0
  143. package/dist/plan/report.js +407 -0
  144. package/dist/sources/cache.js +89 -0
  145. package/dist/sources/claude.js +297 -0
  146. package/dist/sources/codex.js +496 -0
  147. package/dist/sources/flatten.js +23 -0
  148. package/dist/sources/jsonl.js +169 -0
  149. package/dist/sources/native.js +233 -0
  150. package/dist/sources/opencode.js +483 -0
  151. package/dist/sources/pi.js +133 -0
  152. package/dist/sources/registry.js +67 -0
  153. package/dist/sources/types.js +80 -0
  154. package/dist/t3/api.js +492 -0
  155. package/dist/t3/auth.js +248 -0
  156. package/dist/t3/compat.js +62 -0
  157. package/dist/t3/decode.js +408 -0
  158. package/dist/t3/errors.js +185 -0
  159. package/dist/t3/rpc.js +185 -0
  160. package/dist/t3/runtime.js +80 -0
  161. package/dist/ui/caps.js +56 -0
  162. package/dist/ui/components.js +202 -0
  163. package/dist/ui/layout.js +205 -0
  164. package/dist/ui/list.js +423 -0
  165. package/dist/ui/locale.js +73 -0
  166. package/dist/ui/organizePreview.js +72 -0
  167. package/dist/ui/progress.js +237 -0
  168. package/dist/ui/style.js +32 -0
  169. package/dist/ui/terminal.js +126 -0
  170. package/dist/ui/text.js +186 -0
  171. package/package.json +58 -4
  172. package/skills/t3code-sessions/SKILL.md +183 -0
@@ -0,0 +1,549 @@
1
+ // What `t3sm --help` and `t3sm <command> --help` say, in English (help.pt.ts is the European Portuguese twin, with the
2
+ // same commands). Plain text in a small fixed shape that src/cli/helpText.ts styles and fits to the window:
3
+ // - blocks are separated by blank lines;
4
+ // - "Usage:" starts the usage block (one form per line, later forms indented);
5
+ // - a heading line ("Options:", "Examples:", a group such as "Import") followed by items indented by two spaces: a
6
+ // term, two or more spaces, its description (continued on lines indented further; a continued line with aligned
7
+ // columns inside is kept as it is);
8
+ // - a command form ("t3sm projects set ...") followed by an indented paragraph;
9
+ // - any other block is a paragraph (lines are joined), with " - " bullets; `backticks` mark a command.
10
+ // Every option shown must be one the command accepts (src/cli/flags.ts; test/cli/usage.test.ts checks).
11
+
12
+ export const GLOBAL = `
13
+ Global options (every command):
14
+ --lang en|pt The language of what t3sm prints. Default: env T3SM_LANG, then
15
+ "language" in config.json, then your system's language, else
16
+ English. --json, plan.md and the logs are always English.
17
+ --no-color No colour (NO_COLOR is honoured too)
18
+ `;
19
+
20
+ export const USAGE = `t3sm brings your Claude Code, Codex, Pi and OpenCode sessions into T3 Code.
21
+
22
+ Usage: t3sm [command] [options]
23
+
24
+ Start here
25
+ t3sm start Guided set-up, step by step (also plain \`t3sm\`; \`--lang pt\` in Portuguese)
26
+
27
+ Import
28
+ t3sm doctor Check this machine, T3 Code and the accounts (read-only)
29
+ t3sm plan Build the import plan in plan.md (changes no session)
30
+ t3sm apply Import the planned sessions (--dry-run, --only "<folder>")
31
+
32
+ Accounts and projects
33
+ t3sm accounts Your Claude subscriptions and their T3 Code instances
34
+ t3sm projects The account each project uses (set "<folder>" <account>, rename --suggest)
35
+
36
+ Keep in sync
37
+ t3sm status Does t3sm need you? All good, needs you or working (read-only; exit 10: needs you)
38
+ t3sm sync Import what is new since the last run (--watch keeps going)
39
+ t3sm schedule Run sync in the background: install [--watch], remove, restart, status
40
+ t3sm merge Bring sessions continued in a terminal into T3 Code
41
+ t3sm recover <id> Bring back a conversation started in T3 Code whose thread is gone
42
+
43
+ Tidy T3 Code
44
+ t3sm organize Tidy the imported history: archive, retitle, show, pin (--undo)
45
+
46
+ Clean up and undo
47
+ t3sm quarantine Move backup folders to a reversible quarantine
48
+ t3sm dedupe Move the plan's mirror copies to a reversible quarantine
49
+ t3sm runs List what each run did
50
+ t3sm rollback Undo a run (--run <id>)
51
+
52
+ Help and maintenance
53
+ t3sm help What a message means and what to do (t3sm help <topic>)
54
+ t3sm scan Count sessions per agent and account (no T3 Code needed)
55
+ t3sm update Update t3sm to the newest release (--check only looks)
56
+ t3sm changelog What is new in this version (--since <version>)
57
+ t3sm --version Show the version
58
+
59
+ Every command explains itself: \`t3sm <command> --help\`. Commands that write ask first; --dry-run shows what they would
60
+ do.
61
+ `;
62
+
63
+ export const COMMANDS = {
64
+ doctor: `Usage: t3sm doctor [--json] [--repair]
65
+
66
+ Check everything t3sm depends on and say what to fix: Node, the state folder, config.json, the lock, interrupted runs,
67
+ the shell's CLAUDE_CONFIG_DIR, T3 Code (running, version, CLI, a read-only session), its Claude instances and the
68
+ account each one is signed in to (emails masked), accounts found on this machine but missing from config.json, backup
69
+ and quarantine folders, the agents (Claude Code, Codex, Pi, OpenCode), the /t3sm commands and the background sync.
70
+ Read-only: it opens one read-only T3 Code session and revokes it before exiting. Exit 1 when a check fails.
71
+
72
+ Options:
73
+ --json Print the checks as JSON (always English)
74
+ --repair Restore transcript file times left bumped by an interrupted run
75
+ (takes the lock; the only thing doctor ever writes)
76
+ `,
77
+ accounts: `Usage: t3sm accounts [--show-emails] [--allow-untested]
78
+ t3sm accounts --init [--force]
79
+ t3sm accounts --apply [--yes] [--allow-untested]
80
+ t3sm accounts --rename <id> "<Display Name>" [--color "#RRGGBB"]
81
+
82
+ With no option: a read-only table of the accounts in config.json against T3 Code's instances (signed-in email, masked
83
+ like b***@example.com; sign-in, availability, where each account was found), with a warning for shared emails,
84
+ accounts without an instance, signed-out instances and accounts found on this machine but missing from config.json.
85
+
86
+ Accounts are found in ~/.claude, ~/.claude-* folders, CLAUDE_CONFIG_DIR in shell profiles (PowerShell, bash, zsh,
87
+ fish; the alias or function name becomes the account id), .vscode/settings.json pins, the current shell and the homes
88
+ of existing T3 instances. A folder counts only when it holds projects/.
89
+
90
+ Options:
91
+ --init Write config.json with every account found (never emails)
92
+ --force With --init, overwrite an existing config.json
93
+ --apply Create the missing instances and pin claudeAgent to ~/.claude
94
+ --yes Skip the confirmation (required when not on a terminal)
95
+ --rename Set the T3 Code picker label (and colour) of an instance, and
96
+ mirror it in config.json
97
+ --color With --rename: the instance's colour, as #RRGGBB
98
+ --show-emails Show the signed-in emails in full in the table (masked by default)
99
+ --allow-untested No warning on a T3 Code version t3sm was not tested with (it never blocks)
100
+
101
+ Examples:
102
+ t3sm accounts
103
+ t3sm accounts --apply
104
+ t3sm accounts --rename claude-work "Claude Work" --color "#7C3AED"
105
+ `,
106
+ apply: `Usage: t3sm apply [--plan <path>] [--yes | --dry-run] [--only <root>] [--quiet] [--verbose] [--allow-untested]
107
+
108
+ Import the sessions of a plan into T3 Code: create the missing instances and projects, set the per-project default
109
+ account, then import in waves (old transcripts get a short, journaled file-time bump so T3 Code's own importer takes
110
+ them; every time is restored afterwards). Ctrl+C restores the current wave and stops. Exit 5 when some sessions could
111
+ not be imported: a table says why and what to do, and \`t3sm help <topic>\` explains each reason.
112
+
113
+ Options:
114
+ --plan <path> Plan to apply (default: the latest runs/*/plan.json)
115
+ --yes Skip the confirmation (required when not on a terminal)
116
+ --dry-run Run every check (read-only T3 Code session), print the
117
+ summary and what would be done, write nothing
118
+ --only <root> Apply only the sessions of this project folder
119
+ --quiet No progress output (and nothing when another run holds the lock)
120
+ --verbose Also print one line per import wave (the progress bar stays)
121
+ --allow-untested No warning on a T3 Code version t3sm was not tested with (it never blocks)
122
+
123
+ T3 Code imports every recent transcript of a project at once, from every account. So while a project is imported,
124
+ its other recent transcripts (mirror and backup copies, excluded ones, later waves) are parked: their file time is set
125
+ 7 days into the future, which T3 Code skips, and put back right after (a crash is repaired by the next t3sm run). A
126
+ project with a session in use right now waits for the next run (\`t3sm help held\`). Mirror copies in the window are
127
+ reported: run \`t3sm dedupe\` so T3 Code's own Welcome import cannot take them either.
128
+
129
+ A plan older than 24 h, or made against another T3 Code version, is refused: run \`t3sm plan\` again.
130
+
131
+ Examples:
132
+ t3sm apply --dry-run
133
+ t3sm apply --only "~/code/app"
134
+ t3sm apply
135
+ `,
136
+ quarantine: `Usage: t3sm quarantine [--yes | --dry-run]
137
+
138
+ Move the backup folders inside each account's projects/ folder (\`.bak-*\`, \`<dir>.bak\`, \`<dir>.bak-YYYYMMDD-HHMMSS\`)
139
+ to <account home>/session-manager-quarantine/backups/. Nothing is deleted: each move is a rename on the same drive
140
+ (file times kept), journaled, and undone by \`t3sm rollback --run <id>\`. A folder holding a file changed in the last
141
+ 10 minutes is skipped.
142
+
143
+ Options:
144
+ --yes Skip the confirmation (required when not on a terminal)
145
+ --dry-run Only list what would move
146
+ `,
147
+ dedupe: `Usage: t3sm dedupe [--plan <path>] [--yes | --dry-run]
148
+
149
+ Move the plan's mirror copies (a session copied into a second account that is identical to, or an older prefix of,
150
+ the copy that is kept) to <account home>/session-manager-quarantine/mirror/<project folder>/, together with the
151
+ session's sidecar folder. Each copy is compared again right before it moves; forks, active files and copies whose kept
152
+ copy is gone are skipped. Undo with \`t3sm rollback --run <id>\`.
153
+
154
+ Options:
155
+ --plan <path> Plan to use (default: the latest runs/*/plan.json; older than 24 h is refused)
156
+ --yes Skip the confirmation (required when not on a terminal)
157
+ --dry-run Only list what would move
158
+ `,
159
+ merge: `Usage: t3sm merge [--session <id> | --all] [--yes | --dry-run] [--allow-untested]
160
+
161
+ Bring work continued in a terminal (\`claude --resume\`) into T3 Code. T3 Code continues an imported thread from the
162
+ last message it knows, so terminal turns made after the import stay invisible there. A merge:
163
+ - creates a new session file next to the original (<revision id>.jsonl) holding the branch \`claude --resume\`
164
+ would continue; the original session file is never edited;
165
+ - imports it into T3 Code as a new thread, then archives the old T3 thread;
166
+ - is reversible with \`t3sm rollback --run <id>\`.
167
+
168
+ With neither --session nor --all it only lists the candidates (project, session, last terminal activity, messages
169
+ added) and exits 0. A session counts as continued only on positive evidence: a message after the import written by
170
+ another entrypoint than T3 Code. Sessions written in the last 10 minutes wait; a project with another session in use
171
+ waits. A compacted session is not merged (not supported yet), nor one with a broken message chain. Terminal work on a
172
+ side branch (not the one \`claude --resume\` continues) is listed with the \`claude --resume <id>\` hint, never merged.
173
+
174
+ After a merge: continue in T3 Code on the new thread, or in a terminal with \`claude --resume <revision id>\` (printed
175
+ for each merge). The original session id stays resumable in the terminal but is now a stale branch, and \`claude
176
+ --resume\`'s picker shows both. Never have the same session open in T3 Code and a terminal at the same time. Undo with
177
+ \`t3sm rollback --run <id>\`: an untouched revision is deleted and the old thread unarchived; a revision continued
178
+ since is kept (both threads stay). \`t3sm sync\` only reports pending merges, unless config sync.autoMerge is true
179
+ (default false): then it merges them itself.
180
+
181
+ Options:
182
+ --session <id> Merge one session (its id, or a unique prefix of 8+ characters)
183
+ --all Merge every candidate
184
+ --yes Skip the confirmation (required when not on a terminal)
185
+ --dry-run Only list the candidates
186
+ --allow-untested No warning on a T3 Code version t3sm was not tested with (it never blocks)
187
+
188
+ Examples:
189
+ t3sm merge
190
+ t3sm merge --session 1a2b3c4d
191
+ t3sm merge --all
192
+ `,
193
+ recover: `Usage: t3sm recover <session id> [--yes | --dry-run] [--allow-untested]
194
+
195
+ Bring back one conversation started in T3 Code whose T3 Code thread is gone. t3sm cannot tell that by itself when the
196
+ transcript names no T3 Code thread (\`t3sm status\` lists such conversations under Worth knowing), so you name it. It
197
+ refuses unless the conversation was started in T3 Code and no T3 Code thread t3sm can see holds it. The conversation
198
+ comes back as a faithful copy with a new session id, imported into its project (journaled; undo with \`t3sm rollback
199
+ --run <id> --archive-threads\`). The original file stays as it is. If the thread still exists in T3 Code, this makes
200
+ a duplicate. On a terminal it shows what it will do and asks first.
201
+
202
+ Options:
203
+ --yes Skip the confirmation (required when not on a terminal)
204
+ --dry-run Only show what it would do
205
+ --allow-untested No warning on a T3 Code version t3sm was not tested with (it never blocks)
206
+
207
+ Examples:
208
+ t3sm recover 1a2b3c4d --dry-run
209
+ t3sm recover 1a2b3c4d
210
+ `,
211
+ rollback: `Usage: t3sm rollback [--run <id>] [--yes | --dry-run] [--instances] [--archive-threads] [--allow-untested]
212
+
213
+ Undo one run. Without --run it shows the latest run that is not itself a rollback (possibly an unattended sync) and
214
+ asks; --yes needs --run <id>:
215
+ - converted files it wrote are deleted, unless edited since (then kept and listed);
216
+ - what it quarantined moves back (an original path that exists again is left in quarantine and reported);
217
+ - per-project default accounts it set are restored (needs T3 Code running; otherwise the file part still runs and
218
+ the rest is reported);
219
+ - a merge (\`t3sm merge\`): its revision is deleted, its old thread unarchived and its revision thread archived; a
220
+ revision continued since is kept and both threads stay as they are (reported);
221
+ - an organize run (\`t3sm organize\`, \`t3sm projects rename --suggest\`): its changes are reverted where T3 Code
222
+ still shows what t3sm set, exactly as \`t3sm organize --undo <run>\` does; what you changed since stays.
223
+ Imported threads, created instances and projects are listed, never deleted. Running it twice changes nothing the
224
+ second time.
225
+
226
+ Options:
227
+ --run <id> The run to undo (see \`t3sm runs\`)
228
+ --yes Skip the confirmation (needs --run; required when not on a terminal)
229
+ --dry-run Only list what would be undone
230
+ --instances Also restore instance names, colours and homes the run changed
231
+ --archive-threads Archive (not delete) the threads the run imported
232
+ --allow-untested No warning on a T3 Code version t3sm was not tested with (it never blocks)
233
+
234
+ Examples:
235
+ t3sm runs
236
+ t3sm rollback --run 20261114-120000-abcd --dry-run
237
+ t3sm rollback --run 20261114-120000-abcd --yes
238
+ `,
239
+ sync: `Usage: t3sm sync [--quiet] [--verbose] [--allow-untested]
240
+ t3sm sync --watch [--quiet] [--allow-untested]
241
+ t3sm sync --dry-run [--allow-untested]
242
+
243
+ One unattended cycle: build a fresh plan and apply it without asking. Built to run from a scheduler, so it is
244
+ cautious:
245
+ - never creates T3 instances (sessions of a missing account wait for \`t3sm accounts --apply\`), never quarantines
246
+ or dedupes;
247
+ - sessions continued in a terminal since t3sm imported them are reported (run \`t3sm merge\`); with sync.autoMerge
248
+ true (default false) it merges them itself when idle 10 min, at most 20 per cycle;
249
+ - a session with a mirror copy inside T3 Code's 30-day window waits for \`t3sm dedupe\` (the copy is parked while
250
+ its project imports);
251
+ - a project with a session in use right now waits for the next cycle;
252
+ - a session whose import failed (and has not changed since) waits for \`t3sm apply\`;
253
+ - more than sync.maxUnattendedImports (default 200) pending: nothing is imported, one line says to run \`t3sm
254
+ apply\` once (even with --quiet);
255
+ - a default account you chose in T3 Code is never overridden;
256
+ - nothing to import means nothing written (no journal entry, no run folder).
257
+ Exit 3 when T3 Code is not running (silent with --quiet), 0 when another t3sm run holds the lock, 4 for an
258
+ incompatible T3 Code, 2 when T3 Code's default Claude instance reads another home. Each cycle appends one line (counts
259
+ and run ids only) to <state>/logs/sync.log (rotated at 1 MiB, 3 kept).
260
+
261
+ Options:
262
+ --quiet No output except a one-line error (exit 2/4/1/5)
263
+ --watch Stay resident: watch the transcript folders, run a cycle
264
+ after changes settle and again once a changed session has
265
+ been idle 10 min, plus every schedule.everyMinutes; waits
266
+ while T3 Code is closed. Writes <state>/sync-status.json.
267
+ Ctrl+C stops after the current cycle. A second watcher exits 0.
268
+ --dry-run Only print what a cycle would import (writes nothing, not
269
+ even the discovery cache)
270
+ --verbose Also print one line per import wave (no effect with --quiet
271
+ or --watch, which never draw progress)
272
+ --allow-untested No warning on a T3 Code version t3sm was not tested with (it never blocks)
273
+
274
+ Examples:
275
+ t3sm sync --dry-run
276
+ t3sm sync
277
+ t3sm schedule install --watch
278
+ `,
279
+ schedule: `Usage: t3sm schedule install [--watch] [--yes | --dry-run]
280
+ t3sm schedule remove [--yes | --dry-run]
281
+ t3sm schedule restart [--yes | --dry-run]
282
+ t3sm schedule status
283
+
284
+ Register \`t3sm sync --quiet\` with the system scheduler, as the current user, without elevation: Windows Task
285
+ Scheduler (a task XML in <state>/schedule/: every schedule.everyMinutes, only while you are logged on, hidden window,
286
+ never two at once), a macOS LaunchAgent, or a crontab line tagged "# t3sm". With --watch the scheduler starts \`t3sm
287
+ sync --watch --quiet\` at your logon, load or reboot instead, and Windows and cron check every 15 min that it still
288
+ runs (one already running is left alone). The watcher restarts itself into a newer t3sm after its next cycle once one
289
+ is installed. Run it from your own account: in a shell run as Administrator, t3sm warns that the schedule is installed
290
+ for that user only.
291
+
292
+ install and remove can be run any number of times. install --watch first stops a running watcher (asked over its own
293
+ endpoint; a verified process only as a fallback, never by name), recreates the entry and starts the new watcher now;
294
+ remove stops it too, and says so (exit 1 with the pid if it is still running); restart stops and starts the scheduled
295
+ watcher without reinstalling (exit 2 when nothing is installed). status shows the scheduler entry, the command it
296
+ runs (and whether its paths still exist), the watcher heartbeat and the last logged cycle.
297
+
298
+ Options:
299
+ --watch With install: start a resident watcher at logon instead of a cycle every few minutes
300
+ --yes Skip the confirmation (required when not on a terminal)
301
+ --dry-run Print what would happen; change nothing
302
+
303
+ Examples:
304
+ t3sm schedule install --watch --dry-run
305
+ t3sm schedule install --watch
306
+ t3sm schedule status
307
+ `,
308
+ start: `Usage: t3sm start [--lang en|pt] [--no-color]
309
+
310
+ A guided set-up for people who would rather not learn the commands. In short steps it runs t3sm's own commands for
311
+ you: check (doctor), accounts, plan and the project-to-account table, clean-up (quarantine, dedupe), a pilot import
312
+ of one project, the full import, background sync, and a summary with the run ids and how to undo them. Before every
313
+ write it asks, and only y goes ahead (Enter means no). At any question: ? explains more, b goes back, q stops;
314
+ nothing is left half done. Run it again to continue: it works out where you were from t3sm's own state (journal,
315
+ plan, config, scheduler).
316
+
317
+ Plain \`t3sm\` on a terminal starts it too. Not on a terminal, it prints the quick start and exits 0.
318
+
319
+ Options:
320
+ --lang en|pt Language (see the global options below); start offers to
321
+ save it as "language" in config.json
322
+ `,
323
+ projects: `Usage: t3sm projects [--json] [--allow-untested]
324
+ t3sm projects set "<folder>" <account> [--yes | --dry-run] [--force] [--allow-untested]
325
+ t3sm projects unset "<folder>" [--dry-run]
326
+ t3sm projects rename --suggest [--yes | --dry-run] [--allow-untested]
327
+
328
+ With no subcommand: a read-only table of every project folder t3sm knows, with the account its new threads start on,
329
+ why (route: a rule in config.json; vscode-pin: .vscode/settings.json; recent-activity: the account of the most recent
330
+ session; default: defaultAccount), the sessions waiting to be imported, whether the project is already in T3 Code (yes,
331
+ no, archived) and whether a session of it is in use (an import waits for it). With T3 Code closed it shows what this
332
+ machine knows and says so.
333
+
334
+ t3sm projects set "<folder>" <account>
335
+ Writes a route for that exact folder in config.json (or replaces its route in place). A new route goes right before
336
+ the first wildcard route matching the folder, so it wins for that folder only: no other folder's account changes.
337
+ When the folder is already a T3 Code project and T3 Code is running, it also sets the project's default account
338
+ there (journaled: \`t3sm rollback --run <id>\` undoes it). The route decides where new threads start and which
339
+ account the folder's OpenCode and compressed Codex sessions not imported yet go to; Claude Code sessions keep the
340
+ account they were recorded in, and threads already in T3 Code keep theirs. ~ is your home folder; a route covers
341
+ that exact folder, not its sub-folders. Asks first.
342
+
343
+ t3sm projects unset "<folder>"
344
+ Removes that folder's route (wildcard routes are left alone). T3 Code is not changed.
345
+
346
+ t3sm projects rename --suggest
347
+ Clean names for the projects t3sm created whose title is still the one t3sm gave them (a project you renamed is
348
+ never touched): the folder's name, \`parent/name\` for generic folders such as src or app, at most
349
+ organize.names.maxLength characters (default 40), a parent folder added when the name is taken. Shows each title
350
+ before -> after and asks. Every rename is journaled: \`t3sm organize --undo <run>\` puts the old titles back.
351
+
352
+ Options:
353
+ --json Print the table as JSON
354
+ --yes Skip the confirmation (required when not on a terminal)
355
+ --dry-run Only show the change; write nothing
356
+ --force With set: accept a folder that does not exist (yet)
357
+ --suggest With rename: compute the clean names (the only mode)
358
+ --allow-untested No warning on a T3 Code version t3sm was not tested with (it never blocks)
359
+
360
+ Examples:
361
+ t3sm projects
362
+ t3sm projects set "~/code/app" claude-work --dry-run
363
+ t3sm projects rename --suggest --dry-run
364
+ `,
365
+ organize: `Usage: t3sm organize [--dry-run | --yes] [--only <folder>] [--history <days|all|off>] [--min <n>]
366
+ [--auto-settle <days|off>] [--no-delete] [--no-pin <ids>] [--no-archive-folders]
367
+ [--allow-untested] [--plain]
368
+ t3sm organize --undo [<run>] [--dry-run | --yes] [--allow-untested]
369
+
370
+ Tidy the history t3sm imported into T3 Code. It first shows one line per kind of change, with how many, why and how
371
+ to undo it, then the projects with the most conversations shown (now -> after), and asks before changing anything:
372
+ - archive automated conversations (started by the Agent SDK), and the ones of a project t3sm created in a temp or
373
+ system folder;
374
+ - new titles for conversations whose title is a technical first message (<command-name>, <ide_...>, [external
375
+ ...]): the transcript's own title, summary or first real message, at most 80 characters;
376
+ - keep each project's history tidy (organize.history, default the last 90 days and at least 10 per project):
377
+ conversations active in those days are shown inside their project, older ones are settled (they stay in their
378
+ project, on its Settled shelf), and a project with fewer recent ones still shows its most recent; T3 Code's own
379
+ auto-settle setting does not change unless you pass --auto-settle (\`t3sm help history\`);
380
+ - pin the projects with the most recent activity (organize.pinRecent, default 5) and unpin the ones t3sm pinned
381
+ that are no longer among them;
382
+ - delete the empty projects t3sm created (no conversations at all).
383
+ Settings live under "organize" in config.json (organize.titles, organize.archiveAutomated, ...).
384
+
385
+ Conversations you started in T3 Code are never touched, and neither are projects you created (except for pinning),
386
+ T3 Code's settings (unless you pass --auto-settle) or its database. Anything you change in T3 Code after t3sm did is
387
+ left alone from then on: a conversation you unarchived, renamed, settled or reopened, or a project you unpinned.
388
+ Every change is journaled. On a T3 Code version t3sm was not tested with, it warns once and proceeds.
389
+
390
+ Options:
391
+ --dry-run Show what would change; write nothing (not even t3sm's
392
+ discovery cache)
393
+ --yes Skip the confirmation (required when not on a terminal)
394
+ --only <folder> Only the conversations of this T3 Code project (no pins,
395
+ no deletes)
396
+ --undo [<run>] Revert an organize run. Without a run id it offers the
397
+ newest one not undone yet and asks; with --yes the run
398
+ id is required. Only what T3 Code still shows as t3sm
399
+ left it goes back; a deleted project is re-created.
400
+ \`t3sm rollback --run <run>\` does the same.
401
+ --history <days|all|off> The history rule for this run only (config.json is
402
+ not changed): the last 1-3650 days, all of it, or off
403
+ --min <n> Show at least n (0-1000) conversations per project, for
404
+ this run only (with the configured days)
405
+ --auto-settle <days|off> Also set T3 Code's own auto-settle, for
406
+ conversations started in T3 Code: after 1-90 days (T3
407
+ Code accepts nothing else), or off (recorded; --undo
408
+ puts the old value back)
409
+ --no-delete Leave the empty projects t3sm created where they are
410
+ --no-pin <ids> Never pin these projects (T3 Code project ids, comma separated)
411
+ --no-archive-folders Leave the conversations of projects t3sm created in
412
+ temporary or system folders unarchived
413
+ --allow-untested No warning on a T3 Code version t3sm was not tested with (it never blocks)
414
+ --plain Print plain text only, never an interactive screen. On a
415
+ terminal, the question offers d = details: the changes as a
416
+ list you review with the arrow keys; unchecked ones are not
417
+ applied
418
+
419
+ Examples:
420
+ t3sm organize --dry-run
421
+ t3sm organize
422
+ t3sm organize --only "~/code/app" --yes
423
+ t3sm organize --history 90 --min 10 --auto-settle 90 --dry-run
424
+ t3sm organize --undo
425
+ t3sm organize --undo 20261114-120000-abcd --dry-run
426
+ t3sm organize --undo 20261114-120000-abcd --yes
427
+ `,
428
+ update: `Usage: t3sm update [--from <folder> | --source npm|github] [--yes | --dry-run]
429
+ t3sm update --check
430
+ t3sm update --auto on|off [--dry-run]
431
+
432
+ Update t3sm to the newest release of its source: the npm registry (an install that came from it), GitHub's vX.Y.Z
433
+ tags (the repository in package.json), or the tags on main of a checkout on this computer. It first shows what is new
434
+ (a folder: that tag's CHANGELOG.md; npm and GitHub: after the install, from the CHANGELOG.md it installed), then asks.
435
+ The install is \`npm install -g\` of that exact version; the background watcher is stopped (by its own control, never by name) and started again on the new version, and if no
436
+ heartbeat of it comes within 2 minutes the previous version is reinstalled. Every update is journaled. t3sm never
437
+ downgrades. A git checkout or the npx cache only gets instructions. In a shell run as Administrator, t3sm warns that
438
+ the update is installed for that user only.
439
+
440
+ Once a day the background watcher also looks (update.auto, default on): a newer patch or minor release (0.x minors
441
+ included) is installed by itself, a major one is only announced; a failed or rolled-back update shows in \`t3sm
442
+ status\` (\`t3sm help updates\`), and the automatic check skips a rolled-back version (t3sm update can still install
443
+ it). Looking up the releases (npm view, or git ls-remote for GitHub) is t3sm's only network call; installing a release
444
+ downloads it with npm.
445
+
446
+ Options:
447
+ --check Only look: installed version, the newest release and its
448
+ kind (none, patch, minor, major), the source, automatic
449
+ updates on or off, the last check, an interrupted update
450
+ and how to go back. Read-only (no lock); exit 0 offline too
451
+ --from <folder> Update from this checkout (a local absolute path such as
452
+ D:\\code\\t3sm; never a network folder); remembered for
453
+ the next updates once the new version is in
454
+ --source npm Update from the npm registry (remembered the same way)
455
+ --source github Update from GitHub's release tags (remembered the same way)
456
+ --auto on|off Turn the daily automatic update on or off in config.json
457
+ (run t3sm start first if there is none). A preference
458
+ switch like \`projects unset\`: it needs no --yes
459
+ --yes Skip the confirmation (required when not on a terminal);
460
+ the only way a major release is installed without asking
461
+ --dry-run Show what would be installed; change nothing
462
+ --auto-run Used by the background watcher with --yes (a patch or
463
+ minor only); you do not need it
464
+
465
+ Examples:
466
+ t3sm update --check
467
+ t3sm update --dry-run
468
+ t3sm update --auto off
469
+ `,
470
+ changelog: `Usage: t3sm changelog [--since <version>]
471
+
472
+ The release notes of the installed t3sm, from its own CHANGELOG.md (written in English): this version's section, or
473
+ with --since every release newer than that version, newest first. Read-only.
474
+
475
+ Options:
476
+ --since <version> The notes of the releases after this one (such as 0.2.1)
477
+ `,
478
+ runs: `Usage: t3sm runs [--json]
479
+
480
+ List the runs recorded in the journal: id, start time, command, status and what each changed. Read-only.
481
+
482
+ Options:
483
+ --json Print the runs as JSON
484
+ `,
485
+ status: `Usage: t3sm status [--json]
486
+
487
+ Say whether t3sm needs you. The first line is one level: "All good", "Needs you (N)" or "Working" (a t3sm run is in
488
+ progress). Then the items, what needs you first, each with the command that settles it: the background watcher (not
489
+ running, on an older t3sm, or failing); a t3sm update that failed or was interrupted; conversations waiting for your
490
+ decision; conversations that keep failing to import; rehome copies continued twice; copies waiting for a folder;
491
+ organize changes the last organize run could not make. Worth knowing (never a need): a recent update, an update that
492
+ was rolled back (the previous version runs again: t3sm recovered by itself), a newer release that was not installed (a major release is only announced: t3sm never installs one by itself),
493
+ projects waiting because a conversation is in use, conversations started in T3 Code that t3sm leaves out. Then the
494
+ last and next sync, the last organize run and whether T3 Code is running. Strictly read-only: no lock, no journal or
495
+ cache write, and it never connects to T3 Code (it reads T3's runtime file only).
496
+
497
+ Exit 0, or 10 when something needs you (so a script or a notification can tell); 10 is not an error. 2 for a usage
498
+ error.
499
+
500
+ Options:
501
+ --json Print the same data as one JSON object (no colour). Keys:
502
+ version 2
503
+ ran false (and nothing else) when t3sm has not run yet
504
+ level "ok" | "needs-you" | "working"
505
+ items [{ level: "needs-you"|"info", key, text, command }] (command may be null)
506
+ needsAttention { reason, detail, command, since, facts } or null (as the last sync cycle recorded it)
507
+ waiting [{ project, title, modifiedAt, since }] projects held in use
508
+ heldRehome copies waiting for a destination folder in T3 Code
509
+ decisionsPending { <question>: sessions waiting }
510
+ pendingImports { count, source: "sync" | "plan", at } or null
511
+ lastSync { at, outcome, runId } or null
512
+ nextSync { at, source: "watcher" } or null
513
+ watcher { running, pid, version, stale } or null
514
+ update { installed, available, failure, lastInstalled }
515
+ runInProgress { pid, startedAt } or null
516
+ lastOrganize { runId, at, changes, reverted, rolledBackBy } or null
517
+ plugin [{ account, state: installed|outdated|missing, version }] (the /t3sm commands)
518
+ t3Code { running, version }
519
+ `,
520
+ scan: `Usage: t3sm scan [--json]
521
+
522
+ Count the sessions on this machine per agent and account. Needs no running T3 Code. Writes only t3sm's own discovery
523
+ cache (in its state folder); never a session file.
524
+
525
+ Options:
526
+ --json Print the discovered sessions as a JSON array
527
+ `,
528
+ plan: `Usage: t3sm plan [--json] [--allow-untested]
529
+
530
+ Connect to the running T3 Code (read-only), find the sessions and write the import plan to
531
+ <state>/runs/<runId>/plan.md and plan.json. It also updates t3sm's discovery cache and, on the first run, saves the
532
+ detected accounts to <state>/config.json. T3 Code and session files are not changed.
533
+
534
+ Options:
535
+ --json Print the plan as JSON instead of the summary
536
+ --allow-untested No warning on a T3 Code version t3sm was not tested with (it never blocks)
537
+ `,
538
+ help: `Usage: t3sm help [<topic> | <command>]
539
+
540
+ What a message on a t3sm screen means, why it happens and what to do, in your language. Without a topic it lists
541
+ them; a screen that shows a problem names its topic (\`t3sm help not-imported\`). \`t3sm help <command>\` is the same
542
+ as \`t3sm <command> --help\`.
543
+
544
+ Examples:
545
+ t3sm help
546
+ t3sm help held
547
+ t3sm help apply
548
+ `,
549
+ };