t3code-session-manager 0.0.0-stage → 0.4.1

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 +149 -0
  4. package/LICENSE +21 -0
  5. package/README.md +661 -2
  6. package/README.pt.md +617 -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
package/README.md CHANGED
@@ -1,3 +1,662 @@
1
- # Temporary Holding Version
1
+ <picture>
2
+ <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="docs/assets/hero-narrow-dark.svg">
3
+ <source media="(max-width: 600px)" srcset="docs/assets/hero-narrow-light.svg">
4
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hero-dark.svg">
5
+ <img alt="t3sm: five sources (Claude Code with a Personal and a Work account, Codex CLI, Pi, OpenCode) flow into a T3 Code window whose threads are grouped by project and tagged Personal or Work. Under the title: t3sm doctor, then t3sm plan, then t3sm apply; reviewed before it writes, journaled, reversible." src="docs/assets/hero-light.svg" width="100%">
6
+ </picture>
2
7
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
8
+ <p align="center">
9
+ <a href="https://github.com/brunobola-portfolio/t3code-session-manager/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/brunobola-portfolio/t3code-session-manager/actions/workflows/ci.yml/badge.svg"></a>
10
+ <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-3451D1"></a>
11
+ <img alt="Node 22.18 or newer" src="https://img.shields.io/badge/node-%E2%89%A5%2022.18-3451D1">
12
+ <img alt="Windows, macOS, Linux" src="https://img.shields.io/badge/os-Windows%20%7C%20macOS%20%7C%20Linux-3451D1">
13
+ <a href="https://www.npmjs.com/package/t3code-session-manager"><img alt="npm version" src="https://img.shields.io/npm/v/t3code-session-manager?color=3451D1&label=npm"></a>
14
+ <img alt="Zero runtime dependencies" src="https://img.shields.io/badge/runtime%20dependencies-0-3451D1">
15
+ ·&nbsp;<a href="README.pt.md">Português</a>
16
+ </p>
17
+
18
+ **t3sm** puts every session from every coding agent and every Claude account into
19
+ [T3 Code](https://t3.codes), as threads you can resume, each under the subscription it
20
+ was run with. T3 Code is an open-source (MIT) desktop app for coding agents such as
21
+ Claude Code and Codex: you need it installed and running.
22
+
23
+ Your history is scattered across VS Code windows, Claude accounts and agents, and T3
24
+ Code's own import takes only the last 30 days, 100 sessions at a time, without knowing
25
+ which subscription each project belongs to. t3sm brings all of it in, reviewed first.
26
+
27
+ ## Quick start
28
+
29
+ You need Node.js 22.18+ and T3 Code open. Open it from the Start menu or your
30
+ desktop launcher, not from a terminal that sets `CLAUDE_CONFIG_DIR`.
31
+
32
+ **1. Install once.** The same line on Windows, macOS and Linux:
33
+
34
+ ```bash
35
+ npm install -g t3code-session-manager
36
+ ```
37
+
38
+ Every npm release is built by GitHub Actions from its tag and signed with
39
+ [provenance](https://docs.npmjs.com/generating-provenance-statements) (`npm audit signatures`
40
+ checks it). From GitHub instead: `npm install -g --install-links github:brunobola-portfolio/t3code-session-manager#v0.4.1` (needs git).
41
+
42
+ **2. Run it:**
43
+
44
+ ```bash
45
+ t3sm
46
+ ```
47
+
48
+ The guided set-up takes it from there: check, plan, the questions only you can answer, a
49
+ pilot project, the full import, tidying the history and background sync. It explains each
50
+ step and asks before every write. Stop at any question, then run `t3sm` again to continue.
51
+ t3sm speaks English, and European Portuguese on a Portuguese system (`--lang en|pt` chooses).
52
+
53
+ <picture>
54
+ <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="docs/assets/screen-start-narrow-dark.svg">
55
+ <source media="(max-width: 600px)" srcset="docs/assets/screen-start-narrow-light.svg">
56
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/screen-start-dark.svg">
57
+ <img alt="t3sm start, step 5 of 11 (Decisions), on synthetic data: a rail of the 11 steps, then the first of 3 questions as a panel: 5 conversations were started in the home folder, which T3 Code does not accept; t3sm can copy each one into the project it worked in most. The default and where to change it later are shown; the answer is y." src="docs/assets/screen-start-light.svg" width="75%">
58
+ </picture>
59
+
60
+ **3. Updates come by themselves.** Once the background sync is installed, t3sm installs
61
+ newer patch and minor releases once a day and restarts itself
62
+ ([Automatic updates](#automatic-updates)); `t3sm update` does it by hand. Your settings and
63
+ run history carry over.
64
+
65
+ <details>
66
+ <summary><b>Prefer to run each step yourself?</b></summary>
67
+
68
+ ```bash
69
+ t3sm doctor # check: warnings (!) are fine; a failure (✗) says how to fix it
70
+ t3sm plan # writes plan.md and prints its path: read it
71
+ t3sm apply --dry-run # what apply would do (writes nothing)
72
+ t3sm apply --only "C:/work/demo" # pilot one project
73
+ t3sm apply # everything
74
+ ```
75
+
76
+ If the plan lists **mirror copies** or doctor reports **backup folders**, run `t3sm dedupe`
77
+ or `t3sm quarantine` before `apply`, each with `--dry-run` first (reversible; see
78
+ [Choosing your subscription](#choosing-your-subscription)). `apply` shows the summary
79
+ and waits for `yes`. In `plan.md`, check the **Project accounts** table: it says which
80
+ subscription each project will use. Step by step, with every check:
81
+ [docs/switching-from-vscode.md](docs/switching-from-vscode.md).
82
+
83
+ </details>
84
+
85
+ No install at all? `npx -y t3code-session-manager <command>` runs any command (background
86
+ sync needs the installed one). To be strict about what you run, pin the version
87
+ (`t3code-session-manager@<version>`). Other sources:
88
+ [docs/migrate/](docs/migrate/claude-code.md). In Claude Code you can also ask for it in
89
+ plain words with the bundled skill ([docs/install.md](docs/install.md#claude-code-plugin)).
90
+
91
+ ### First run checklist
92
+
93
+ - **Keep the machine awake** until `apply` finishes. If it sleeps during an import, t3sm
94
+ stops that batch when it wakes, puts its file times back, and leaves the rest for the
95
+ next run.
96
+ - **Close the sessions** of the projects you want imported. A project with a session
97
+ written in the last 10 minutes waits for a later run.
98
+ - **Pause cloud sync of your home folder** (OneDrive, Dropbox, iCloud) during the first
99
+ `apply`. A sync client can lock transcripts (t3sm then holds those projects for the
100
+ run) or copy files while their times are moved.
101
+ - **Install the schedule only after the first full `apply`**: `sync` imports nothing
102
+ while more than 200 sessions are pending.
103
+ - **Always name the run you undo:** `t3sm rollback --run <id>` (`t3sm runs` lists them).
104
+ With `--yes`, `--run` is required, so a scheduled `sync` is never undone by mistake.
105
+ - If a run is interrupted (crash, power cut), the next t3sm command puts every moved
106
+ file time back first. `t3sm doctor --repair` does only that.
107
+
108
+ <p align="center">
109
+ <picture>
110
+ <source media="(prefers-reduced-motion: reduce) and (prefers-color-scheme: dark)" srcset="docs/assets/demo-static-dark.svg">
111
+ <source media="(prefers-reduced-motion: reduce)" srcset="docs/assets/demo-static-light.svg">
112
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/demo-dark.svg">
113
+ <img alt="Terminal demo on synthetic data. t3sm plan prints a summary: 406 sessions to import as they are and 6 to convert from OpenCode, 58 skipped, 1 new instance, 12 new projects, imports split between Claude · Work (251) and Claude · Personal (161), and the path of plan.md. Then t3sm apply --yes imports them in 4 waves and ends with 'Imported 412, failed 0, converted 6'." src="docs/assets/demo-light.svg" width="75%">
114
+ </picture>
115
+ <br><sub>Synthetic demo: the <code>plan</code> summary, then <code>apply</code> importing in four waves.</sub>
116
+ </p>
117
+
118
+ ## Check that it worked
119
+
120
+ <picture>
121
+ <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="docs/assets/screen-import-narrow-dark.svg">
122
+ <source media="(max-width: 600px)" srcset="docs/assets/screen-import-narrow-light.svg">
123
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/screen-import-dark.svg">
124
+ <img alt="t3sm apply on synthetic data: one progress bar redrawn in place (260 of 412, the rate and the time left), then the result panel: 410 imported, 2 could not be imported, 6 converted, the run and the command that undoes it; then the two conversations that failed, each with its project, its title and why in words, and the t3sm help topics that explain them." src="docs/assets/screen-import-light.svg" width="75%">
125
+ </picture>
126
+
127
+ - `apply` imports behind one progress bar and ends with a result panel: what was imported,
128
+ what waits, the run id and the command that undoes it, and exit code 0. That run id is what
129
+ `t3sm runs` lists and `t3sm rollback` takes. Conversations that could not be imported are
130
+ listed by project and title with the reason in words (exit 5); `t3sm help <topic>` explains
131
+ each reason.
132
+ - In T3 Code, each project of the plan is in the sidebar with its old sessions as
133
+ threads. Opening a thread shows its history. Sending a message continues the original
134
+ session, as a real turn on that thread's account (it uses your subscription).
135
+ - New threads in a project open with the account from the **Project accounts** table.
136
+ - `t3sm plan` again shows those sessions under `already-in-t3`, and `t3sm doctor` has no
137
+ failure (✗). `t3sm runs` lists what was done:
138
+
139
+ ```text
140
+ Run Started Command Status Changes
141
+ 20261111-094501-7f3a 2026-11-11T09:45:01.000Z quarantine ok quarantined 2
142
+ 20261111-100003-b2d4 2026-11-11T10:00:03.000Z apply 20261111-093012-a1b2 --only ok imported 18, defaults 1, instances 1, projects 1
143
+ 20261111-101544-c3d4 2026-11-11T10:15:44.000Z apply 20261111-093012-a1b2 ok imported 394, files 6, defaults 11, projects 11
144
+ ```
145
+
146
+ <sub>Real output of `t3sm runs` on a synthetic journal.</sub>
147
+
148
+ ## The problem it solves
149
+
150
+ You work in several VS Code windows, each with the Claude Code extension, and you have
151
+ two Claude subscriptions, say a personal one in `~/.claude` and a work one in
152
+ `~/.claude-work`. Your history is split by account, by window and by agent, and the
153
+ same session can exist twice, once per account. T3 Code can import sessions, but only
154
+ the last 30 days, at most 100 per click, from the accounts it already knows, and
155
+ nothing tells it which subscription a project belongs to.
156
+
157
+ t3sm finds every session on the machine, decides which account owns each one, creates
158
+ what T3 Code is missing, and has T3 Code import everything, whatever its age, in
159
+ reviewed batches. Afterwards it keeps T3 Code in step with work you do in a terminal, and can tidy how the
160
+ imported history looks there.
161
+
162
+ ## How it works
163
+
164
+ <picture>
165
+ <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="docs/assets/flow-narrow-dark.svg">
166
+ <source media="(max-width: 600px)" srcset="docs/assets/flow-narrow-light.svg">
167
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/flow-dark.svg">
168
+ <img alt="Five steps: 1 Check (t3sm doctor), 2 Plan (t3sm plan writes plan.md), 3 Review (read plan.md, adjust config.json), 4 Apply (T3 Code's own importer, in waves, every file time journaled and put back), 5 Stay in sync (t3sm sync on a schedule or a watcher; merge brings terminal work back). Guarantees: never writes T3 Code's database, native transcripts untouched, journal before change, undo." src="docs/assets/flow-light.svg" width="100%">
169
+ </picture>
170
+
171
+ - **T3 Code imports, t3sm paces it.** Claude Code, Codex and Pi sessions are imported
172
+ by T3 Code's own importer, so they resume natively. t3sm talks to T3 Code only
173
+ through its `t3` CLI and its RPC API, never its database.
174
+ - **Old sessions without copies.** T3 Code imports only files touched in the last 30
175
+ days. t3sm moves a batch's file times to "now" for a moment, imports, and puts them
176
+ back. Every move is written to a journal first, and the next run repairs anything an
177
+ interruption left behind.
178
+ - **One project at a time is safe.** T3 Code imports every recent transcript of a
179
+ project at once, so t3sm parks the ones that should not go in (stale copies, excluded
180
+ files, later batches) by setting their time 7 days **ahead**: Claude Code deletes
181
+ old sessions by file time, so a parked file must never look old. A project with a
182
+ session in use waits for the next run, and a batch interrupted by sleep stops and is
183
+ retried.
184
+ - **Other agents are converted.** OpenCode sessions are written as Claude Code
185
+ transcripts in the project's account, then imported like any Claude session. They
186
+ resume in T3 Code and in `claude --resume`.
187
+ - **Everything is reviewable and reversible.** `plan` writes a report (and, on its
188
+ first run, `config.json`) in t3sm's own folder and nothing else. `apply` asks first.
189
+ `t3sm rollback` undoes a run. Details: [docs/architecture.md](docs/architecture.md).
190
+
191
+ ## Choosing your subscription
192
+
193
+ <picture>
194
+ <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="docs/assets/accounts-narrow-dark.svg">
195
+ <source media="(max-width: 600px)" srcset="docs/assets/accounts-narrow-light.svg">
196
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/accounts-dark.svg">
197
+ <img alt="Left: a session belongs to the account whose folder holds it (~/.claude is Personal, ~/.claude-work is Work); a session in both is compared by content: identical gives one thread in the project's account, prefix gives one thread from the longer copy, diverged gives two threads, one per account. Right: a project opens with, first match wins: routes in config.json, the .vscode/settings.json pin, the most recent session, defaultAccount." src="docs/assets/accounts-light.svg" width="100%">
198
+ </picture>
199
+
200
+ In T3 Code, an **instance** is one configured provider entry, such as "Claude" pointing at
201
+ one account folder. t3sm gives each Claude account its own instance, with its own name and
202
+ colour in T3 Code's model picker, so you choose the subscription per thread there, and
203
+ each project gets a default so new threads start on the right one. `apply` creates the
204
+ missing instances after you confirm the plan.
205
+
206
+ - **Discovered automatically.** From `~/.claude` and `~/.claude-*` folders,
207
+ `CLAUDE_CONFIG_DIR` in shell aliases and functions (PowerShell, bash, zsh, fish), VS
208
+ Code pins in `.vscode/settings.json`, the current shell and existing T3 Code instances.
209
+ `t3sm accounts` shows what was found (emails masked; `--show-emails` for the full
210
+ address). Optional: `t3sm accounts --init` writes the list to `config.json` so you can
211
+ edit it, `--apply` creates the instances before any import (it asks first), and
212
+ `--rename <id> "<name>" --color "#RRGGBB"` sets an instance's label in the picker.
213
+ - **A session keeps its account.** The folder a transcript lives in decides its account.
214
+ A session copied into both accounts is compared: identical or shorter copies are
215
+ mirrors (one thread), diverged ones are kept as two threads.
216
+ - **A project's default** comes from a `routes` rule, then the VS Code pin, then the
217
+ account of the most recent session there, then `defaultAccount`.
218
+ - **The default instance is pinned.** If T3 Code's own Claude instance has no folder set in
219
+ its settings, `apply` sets it to `~/.claude` (shown in the confirmation and in
220
+ `apply --dry-run`), so a T3 Code started from a shell with `CLAUDE_CONFIG_DIR` cannot move
221
+ it; until then `doctor` warns `instance-unpinned`. A session T3 Code already holds under
222
+ another account is never imported a second time (`plan.md` lists it).
223
+ - **You can override it.** One line in `~/.t3code-session-manager/config.json`:
224
+
225
+ ```json
226
+ "routes": [{ "match": "C:/work/clients/**", "account": "claude-work" }]
227
+ ```
228
+
229
+ Mirror copies matter because T3 Code's own Welcome import could pick a stale copy up under
230
+ the wrong account. `t3sm dedupe` moves them, and `t3sm quarantine` moves `.bak` folders
231
+ inside `projects/`, to a reversible quarantine. Sessions whose project folder no longer
232
+ exists are skipped as `cwd-missing`; if the project moved, a `remap` rule can point them
233
+ at the new folder (read its caveat first). More in [docs/accounts.md](docs/accounts.md)
234
+ and [docs/configuration.md](docs/configuration.md).
235
+
236
+ ## Keeping in sync
237
+
238
+ ```bash
239
+ t3sm sync # one cycle: import what is new since the last run
240
+ t3sm sync --watch # stay resident and run a cycle when transcripts change
241
+ t3sm schedule install # run sync every 15 minutes (Task Scheduler, launchd or cron)
242
+ t3sm schedule install --watch # or start the watcher at logon
243
+ t3sm schedule status # what is installed, last cycle
244
+ ```
245
+
246
+ `sync` is built to run unattended, so it is cautious: it never creates instances or moves
247
+ files, waits for projects with a session in use, and imports nothing when more than
248
+ [`sync.maxUnattendedImports`](docs/configuration.md#sync) (200) sessions are pending, so the
249
+ first big import is always a reviewed `apply`. It never asks a question: sessions of a kind
250
+ you have not decided about yet wait, and `t3sm status` says so. What it does by itself, each
251
+ change journaled in the cycle's run (`t3sm rollback --run <id>` undoes it):
252
+
253
+ - organizes the conversations it has just imported (archives automated ones, gives readable
254
+ titles);
255
+ - applies the [history rule](#the-history-rule) right after an import and once a day, at
256
+ most 200 changes per cycle, never moving a conversation you changed by hand;
257
+ - brings in what you add to the original of a
258
+ [copied conversation](#conversations-from-folders-t3-code-refuses) outside T3 Code;
259
+ - as a watcher, restarts itself into a newer t3sm after its next cycle, and looks for
260
+ [updates](#automatic-updates) once a day.
261
+
262
+ **The background watcher.** `t3sm schedule install --watch` starts it at logon, and on
263
+ Windows and Linux checks every 15 minutes that it still runs (one already running is left
264
+ alone; on macOS launchd keeps it alive). `t3sm schedule restart` stops it and starts it
265
+ again; `install` and `remove` stop it first too. t3sm stops a watcher by asking it over its
266
+ own authenticated endpoint and, only if that fails, by its process id after checking that
267
+ this process is a t3sm watcher started when its heartbeat says. Never by name.
268
+
269
+ **Work continued in a terminal.** If you resume an imported session with
270
+ `claude --resume`, T3 Code does not see the new turns: it continues from the last message
271
+ it knows. `sync` and `doctor` report those sessions, and `t3sm merge` lists them.
272
+ `t3sm merge --all` writes a new session file next to the original with the complete
273
+ branch, imports it as a new thread and archives the old thread. The original file is never
274
+ edited, and `t3sm rollback` undoes it. Compacted sessions are not merged, and terminal work
275
+ on a side branch (not the one `claude --resume` continues) is listed with a hint, never
276
+ merged.
277
+
278
+ ## Automatic updates
279
+
280
+ Once a day the background watcher looks up the newest release of the source t3sm was
281
+ installed from: GitHub's `vX.Y.Z` tags, or the `vX.Y.Z` tags on `main` of a checkout on this
282
+ computer (`t3sm update --from <folder>`). A newer **patch or minor** release (0.x minors
283
+ included) is installed by itself, in a separate hidden process, and the watcher restarts
284
+ into it. A **major** release is only announced (`t3sm status`, a notification): `t3sm update`
285
+ installs it after you say yes.
286
+
287
+ - **Health check and rollback.** After an install the new watcher must write a healthy
288
+ heartbeat within 2 minutes. If it does not, t3sm reinstalls the previous version and
289
+ restarts it: t3sm recovered by itself, so `t3sm status` mentions it as worth knowing, not as
290
+ a need. The automatic check skips that version from then on; `t3sm update` can still install
291
+ it on purpose.
292
+ - **Never a downgrade.** Only a release strictly newer than the installed one is installed.
293
+ - **Journaled.** Every update is a journal entry (from, to, outcome). `t3sm status` shows a
294
+ recent update ("Updated to 0.3.1 yesterday") and `t3sm changelog` what is new.
295
+ - **Off switch.** `t3sm update --auto off` (and `on`). A git checkout or `npx` is never
296
+ updated by itself.
297
+
298
+ **The one network call.** Apart from T3 Code on your own machine (loopback only), t3sm
299
+ itself contacts one thing: the release lookup (`npm view` on the npm registry, or
300
+ `git ls-remote` on GitHub for an install from GitHub), once a day from the watcher and when you run `t3sm update` or
301
+ `t3sm update --check`. Installing a release runs npm (and git), which download it. The only
302
+ other time anything goes online is the optional `/t3sm` plugin install in `t3sm start`,
303
+ after your yes (`claude plugin` commands). Nothing about your sessions is ever sent.
304
+
305
+ ```bash
306
+ t3sm update --check # installed, newest, patch/minor/major, source, automatic updates on or off
307
+ t3sm update # what is new, then it asks
308
+ t3sm changelog # the notes of the installed version
309
+ ```
310
+
311
+ ## Organize your history
312
+
313
+ <picture>
314
+ <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="docs/assets/organize-narrow-dark.svg">
315
+ <source media="(max-width: 600px)" srcset="docs/assets/organize-narrow-light.svg">
316
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/organize-dark.svg">
317
+ <img alt="Two T3 Code sidebars on synthetic data. Today: the projects billing-api, mobile-app and docs-site show no threads, and 3,267 imported conversations sit in Settled. After t3sm organize: the three projects are pinned with their conversation titles under each, the automated runs are archived (Archived, 2,614, out of sight) and Settled keeps only the 41 conversations T3 Code settled itself. Caption: Optional. Defaults shown; you choose each part." src="docs/assets/organize-light.svg" width="100%">
318
+ </picture>
319
+
320
+ An import is not the end of the story. T3 Code shows only unsettled threads inside a project,
321
+ and imported conversations arrive settled, so they sit in one long **Settled** list and your
322
+ projects look empty. In one real history about 80% of the sessions were runs by scripts
323
+ (Agent SDK), not conversations. And T3 Code cannot import conversations that were started in
324
+ your home folder or in a few other folders (Downloads, `Documents/Codex`, the temp folder). Temp and system folders are skipped by default, not copied.
325
+
326
+ `t3sm organize` tidies that, after showing you what it would do. t3sm is a small tool: it
327
+ uses only the commands T3 Code offers for this, and every part is optional.
328
+
329
+ | Part | What it does | Default |
330
+ | :-- | :-- | :-: |
331
+ | Automated sessions | Archives the ones started by scripts (Agent SDK), and those of a project t3sm created in a temp or system folder | on |
332
+ | Titles | Replaces a title that is a technical first message (`<command-name>`, `<ide_…>`) with a readable one, at most 80 characters | on |
333
+ | History in projects | The [history rule](#the-history-rule): the last 90 days shown inside each project, at least 10 per project, the rest settled. T3 Code's own auto-settle setting is **not** changed unless you ask | 90 days, at least 10 |
334
+ | Pin | Pins the 5 projects with the most recent activity, and unpins the ones t3sm pinned that are no longer among them | on |
335
+ | Empty projects | Deletes empty projects that t3sm created | on |
336
+
337
+ ```bash
338
+ t3sm organize --dry-run # what it would change; writes nothing
339
+ t3sm organize # the same list, then it asks
340
+ t3sm organize --undo # put back what it changed (asks first)
341
+ ```
342
+
343
+ Each kind of change comes with how many, why and how to undo it. On a terminal, `d` at the
344
+ question opens the changes as a list you can uncheck one by one. Options:
345
+ `--only "<folder>"` (one project; no pins, no deletes), `--plain` (plain text, no
346
+ interactive screen), `--no-pin <ids>`, `--no-delete`, `--no-archive-folders` (leave the
347
+ conversations of projects t3sm created in temporary or system folders unarchived), `--history <days|all|off>` and
348
+ `--min <n>` (the history rule for this run only), and `--auto-settle <1..90|off>` if you also want T3 Code's own
349
+ option for the conversations you start there set to that many days, or off (recorded, and undone by `--undo`).
350
+ The defaults and the `config.json` keys are in
351
+ [docs/configuration.md](docs/configuration.md#organize). The guided set-up (`t3sm start`)
352
+ asks the same questions, one at a time, with your real numbers.
353
+
354
+ ### The history rule
355
+
356
+ T3 Code shows only unsettled conversations inside a project; settled ones stay attached to
357
+ their project on the **Settled** shelf at the bottom of the sidebar. The rule, per project:
358
+
359
+ - every conversation active in the last **90 days** is shown;
360
+ - if that leaves fewer than **10** shown, the most recent settled ones are shown until 10 are
361
+ (everything shown counts, conversations you started in T3 Code and pinned ones included);
362
+ - everything else is settled, oldest first, so the shelf keeps the order of your history.
363
+
364
+ Only imported conversations are ever moved (`import:` threads, whether t3sm or T3 Code's own import brought them in;
365
+ the ones you start in T3 Code are only moved by T3 Code's own option), and one you settled, showed, pinned or
366
+ archived by hand is never touched again. The activity date is T3 Code's own: the newest user
367
+ message or run, else when the conversation was created. `organize.history` in `config.json`
368
+ holds the numbers (`{ "days": 1-3650 or "all", "minPerProject": 0-1000 }`),
369
+ `t3sm organize --history <days|all|off> --min <n>` uses others for one run, and `t3sm sync`
370
+ applies the rule once a day. For the conversations you start in T3 Code, T3 Code has its own
371
+ option (settle after 1 to 90 days without use): the guided set-up offers to set it to the same
372
+ days, and `t3sm organize --auto-settle <1..90|off>` sets it (journaled, undone by `--undo`).
373
+ `t3sm help history` explains it in your language.
374
+
375
+ **What it never touches:** conversations you started in T3 Code, projects you created
376
+ (except to pin them, and to unpin what t3sm pinned), T3 Code's settings (except `--auto-settle`, if you ask), and
377
+ anything you changed by hand afterwards: a conversation you unarchived, renamed or reopened,
378
+ a project you unpinned. That choice is yours for good. `t3sm rollback --run <id>` undoes an
379
+ organize run too, exactly like `--undo`. Because undoing changes T3 Code, `--undo --yes`
380
+ needs the run id (`t3sm organize --undo <run> --yes`), like `rollback`.
381
+
382
+ ### Conversations from folders T3 Code refuses
383
+
384
+ By default t3sm copies them, whole and unchanged, into the project they worked on. It reads
385
+ the paths the conversation touched: "63 of 80 paths are in `~/code/billing-api`" is enough
386
+ (at least 60% of the paths and at least 5 hits). With no clear project they go to a project
387
+ called **General** (`~/T3 General`; `~/T3 Geral` in the Portuguese assistant), whose folder
388
+ `t3sm apply` creates when it is missing (never `sync`; `rollback` removes it again while it is
389
+ empty). A folder T3 Code refuses, or a temporary or system one, is never used. The original is
390
+ never modified, and `rollback` removes the copy. If you keep talking in the original
391
+ **outside T3 Code after the import** (VS Code, from the home folder), `t3sm sync` follows it:
392
+ once the original and the copy have been idle for 10 minutes, it writes a new copy with the
393
+ new messages, imports it as a new thread with the old thread's title and settled state, and
394
+ only then archives the old thread. A copy you also continued in T3 Code is never
395
+ overwritten: `t3sm status` names both, and you choose. Temp and system folders, and automated
396
+ sessions, are skipped by default. Folder
397
+ rules can be changed per folder (`organize.overrides`), but an override never imports an
398
+ automated (Agent SDK) session: `organize.sessions.automated` decides those.
399
+
400
+ **Conversations started in T3 Code** are recognised and never imported again. If you deleted
401
+ such a conversation's thread in T3 Code, T3 Code refuses to import it again: after one
402
+ question (default yes) t3sm brings it back as a faithful copy with a new session id
403
+ (`organize.sessions.orphaned`). One whose thread t3sm cannot identify is left out, never
404
+ copied, so a live conversation is never duplicated.
405
+
406
+ ### Know what needs you
407
+
408
+ ```bash
409
+ t3sm status # "All good", "Needs you (N)" with the command for each, or "Working"
410
+ ```
411
+
412
+ <picture>
413
+ <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="docs/assets/screen-status-narrow-dark.svg">
414
+ <source media="(max-width: 600px)" srcset="docs/assets/screen-status-narrow-light.svg">
415
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/screen-status-dark.svg">
416
+ <img alt="t3sm status on synthetic data: 'Needs you (2)', then each item with the command that settles it: 3 conversations wait for your decision (t3sm start) and the background watcher is not running (t3sm schedule restart); worth knowing: a project waits while a conversation is in use, and t3sm 0.3.1 is available (t3sm update); then the last and next sync, the watcher, the version, the last organize run, the plugin per account and T3 Code." src="docs/assets/screen-status-light.svg" width="75%">
417
+ </picture>
418
+
419
+ `t3sm status` only reads: it does not connect to T3 Code and writes nothing. What needs you
420
+ comes first, each item with its command: the watcher not running, on an older t3sm or
421
+ failing; an update that failed or was interrupted; conversations waiting for your decision;
422
+ conversations that keep failing to import; copies continued in two places; organize changes
423
+ that could not be made. Then what is worth knowing: projects **held** because a conversation
424
+ in them is in use (they are imported once it has been idle for 10 minutes), a recent update,
425
+ an update that was rolled back (the previous version runs again) or a newer release, and the
426
+ last and next sync. `--json` prints the
427
+ same for scripts, and the exit code is 10 when something needs you (0 otherwise). When a scheduled `sync` needs you, it can raise one system notification
428
+ (`notify` in `config.json`: `attention` by default, `all`, or `off`) with project names and
429
+ counts only.
430
+
431
+ **Inside T3 Code.** The `t3sm` plugin adds `/t3sm:status`, `/t3sm:sync`, `/t3sm:organize`
432
+ and `/t3sm:import` to T3 Code's "/" menu. Each shows a preview first and writes only after
433
+ you say yes. `t3sm start` offers to install it, per Claude account, after a `y`; or run
434
+ `claude plugin install t3sm@t3code-session-manager` for that account yourself. The
435
+ conversation running `/t3sm:sync` or `/t3sm:import` counts as "in use", so its own project
436
+ waits for the next cycle; `/t3sm:organize` does not wait for it and may give it a new title or
437
+ show it inside its project.
438
+
439
+ t3sm does not refuse a T3 Code version it was not tested with: it warns once and goes ahead.
440
+ Every change is journaled and undoable.
441
+
442
+ ## Other commands
443
+
444
+ | Command | What it does |
445
+ | :-- | :-- |
446
+ | `t3sm scan` | Counts the sessions per agent and account, without T3 Code; it writes only t3sm's discovery cache. **Flagged** counts sessions with a remark (in use, a corrupt line, no folder, a backup or compressed copy, a sub-agent…); `plan.md` says what happens to each |
447
+ | `t3sm runs` | Lists the runs in the journal (sample above) |
448
+ | `t3sm rollback --run <id>` | Undoes a run; `--dry-run` lists what it would undo. `--yes` requires `--run` |
449
+ | `t3sm recover <session id>` | Brings back a conversation started in T3 Code whose thread you deleted, when t3sm cannot tell by itself (`t3sm status` lists them): a faithful copy with a new id, imported into its project. If the thread still exists in T3 Code, this makes a duplicate. Asks first; `--dry-run`; undone by `rollback` |
450
+ | `t3sm doctor --repair` | Puts back file times an interrupted run left moved; the only write `doctor` makes |
451
+ | `t3sm accounts` | Accounts found and their T3 Code instances |
452
+ | `t3sm projects` | Every project folder with its account and why; `projects set "<folder>" <account>` changes it (a route, and the T3 Code project's default, reversible); `projects unset` removes the route; `projects rename --suggest` proposes clean names for the projects t3sm created (before -> after, asks first, undone by `organize --undo`) |
453
+ | `t3sm organize` | Tidies imported history in T3 Code ([above](#organize-your-history)); `--dry-run`, `--undo`, `--only`, `--plain` |
454
+ | `t3sm status` | Says whether t3sm needs you, and what to run. Read-only; exit 10 when it needs you; `--json` |
455
+ | `t3sm start` | The guided assistant (also plain `t3sm` on a terminal) |
456
+ | `t3sm schedule` | `install [--watch]`, `remove`, `restart` (stops and starts the watcher safely), `status`; the writing ones ask, or take `--yes`, and have `--dry-run` |
457
+ | `t3sm update` | Installs the newest release, shows what is new and asks first; `--check` only looks, `--dry-run` shows what would be installed, `--from <folder>` installs from a checkout (remembered), `--source npm` or `--source github` chooses where updates come from, `--auto on` / `--auto off` turns the daily automatic update on or off. A git checkout or npx only gets instructions |
458
+ | `t3sm changelog` | What is new in the installed version (`--since <version>` for several releases). Read-only |
459
+ | `t3sm help [<topic>]` | What a message means, why it happens and what to do (`not-imported`, `held`, `decisions`, `history`, `updates`, `watcher`, ...). Read-only |
460
+
461
+ Every command has `--help` and takes `--lang en|pt` and `--no-color`. Without `--lang`, t3sm
462
+ follows `T3SM_LANG`, then `"language"` in `config.json`, then your system's language, else
463
+ English. `--json`, `plan.md`, the journal and `logs/sync.log` are always English. What each
464
+ skip reason in `plan.md` means is written next to it there; every screen that shows a problem
465
+ names the `t3sm help` topic that explains it ([docs/troubleshooting.md](docs/troubleshooting.md)
466
+ is their index).
467
+
468
+ ## Safety
469
+
470
+ In short: t3sm shows you what it will do before it does it, never touches T3 Code's
471
+ database or the content of your transcripts, records every change before making it, and
472
+ can undo a run. Each guarantee is pinned by tests you can read and run (`npm test`):
473
+
474
+ - **Review before write.** `plan` writes only its report (plus, on first run,
475
+ `config.json` and a discovery cache) in t3sm's folder. `apply`, `dedupe`, `quarantine`,
476
+ `merge`, `organize` and `rollback` ask first, and refuse with exit code 2 on a non-terminal without
477
+ `--yes`. `apply --dry-run` runs every check and lists what it would do, writing nothing.
478
+ [test/apply/apply.test.ts](test/apply/apply.test.ts),
479
+ [test/apply/dry-run.test.ts](test/apply/dry-run.test.ts),
480
+ [test/cli/ops.test.ts](test/cli/ops.test.ts)
481
+ - **Never writes T3 Code's database.** It uses the `t3` CLI and T3 Code's RPC API only, and
482
+ reads one T3 Code file, `server-runtime.json`.
483
+ [test/safety/boundaries.test.ts](test/safety/boundaries.test.ts)
484
+ - **Journal before change.** Every file time is recorded before it moves, and the run stops
485
+ if the journal cannot be written.
486
+ [test/apply/importer.test.ts](test/apply/importer.test.ts)
487
+ - **Restore on failure.** If an import throws, every file time is put back; after a crash,
488
+ the next run (even with T3 Code closed) restores them first.
489
+ [test/apply/importer.test.ts](test/apply/importer.test.ts),
490
+ [test/core/journal.test.ts](test/core/journal.test.ts),
491
+ [test/ops/sync.test.ts](test/ops/sync.test.ts)
492
+ - **Parked files go forward, never back.** A parked transcript is set 7 days into the
493
+ future, so Claude Code's cleanup of old sessions can never select it, and a batch stops
494
+ if the clock jumps (the machine slept) before T3 Code could see a parked file.
495
+ [test/apply/importer.test.ts](test/apply/importer.test.ts)
496
+ - **Native transcripts are never edited.** Conversions and merge revisions are new files;
497
+ the original stays byte-identical. Sessions in use (written in the last 10 minutes) are
498
+ not touched.
499
+ [test/ops/merge.test.ts](test/ops/merge.test.ts),
500
+ [test/apply/materialize.test.ts](test/apply/materialize.test.ts),
501
+ [test/sources/opencode.test.ts](test/sources/opencode.test.ts)
502
+ - **Rollback.** `t3sm rollback` deletes the files a run wrote (unless edited since), moves
503
+ quarantined folders back with their file times, restores project defaults, never leaves a
504
+ session without an active thread, and running it twice changes nothing.
505
+ [test/ops/rollback.test.ts](test/ops/rollback.test.ts)
506
+ - **Organize touches little, and only what it can undo.** It changes only imported
507
+ conversations and projects t3sm created (pinning and unpinning aside: it pins recent projects of any kind and unpins only the ones it pinned), through the commands T3 Code
508
+ offers for it, and never its database. Every change is journaled, with what it replaced.
509
+ Anything you changed in T3 Code afterwards is skipped for good, and `--undo` puts back only
510
+ what T3 Code still shows as t3sm left it. A native T3 Code conversation is never touched.
511
+ [test/organize/apply.test.ts](test/organize/apply.test.ts),
512
+ [test/organize/plan.test.ts](test/organize/plan.test.ts),
513
+ [test/organize/sessions.test.ts](test/organize/sessions.test.ts)
514
+ - **Never kills by name.** The watcher is stopped through its own authenticated endpoint
515
+ and, only if needed, by its process id once its command line and start time prove it is a
516
+ t3sm watcher.
517
+ [test/ops/watcherControl.test.ts](test/ops/watcherControl.test.ts)
518
+ - **Updates you can trust.** Never a downgrade, a health check after every install, the
519
+ previous version put back when the new one does not start, every update journaled.
520
+ [test/ops/updater.test.ts](test/ops/updater.test.ts)
521
+ - **One run at a time.** A lock keeps a scheduled sync away from a manual apply. A lock
522
+ left by a run that died, or by one from before the last restart, is taken over.
523
+ [test/core/lock.test.ts](test/core/lock.test.ts), [test/cli/sync.test.ts](test/cli/sync.test.ts)
524
+
525
+ What t3sm reads and writes, and where: [SECURITY.md](SECURITY.md).
526
+
527
+ ## Works with
528
+
529
+ | Agent | Status | How | Notes |
530
+ | :-- | :-- | :-- | :-- |
531
+ | **Claude Code**, one or more accounts | ✅ verified live | T3 Code's importer | Two accounts discovered and planned live on a real machine; import, merge and rollback run live on synthetic sessions |
532
+ | **OpenCode** 1.19.5 | ✅ verified live | converted to Claude Code | Conversion and import run live on a synthetic session; real database discovery verified read-only |
533
+ | **Codex CLI** | 🟡 verified with fixtures | T3 Code's importer; compressed sessions converted to Claude Code | Plus discovery on real files; no live native import yet. Codex 0.167+ compresses older sessions (`.jsonl.zst`), which T3 Code cannot read: t3sm converts them into Claude threads (conversion and import run live on a synthetic compressed session; 108 real compressed files discovered read-only) |
534
+ | **Pi** | 🟡 verified with fixtures | T3 Code's importer | Plus discovery on real files; imported only when T3 Code has a Pi instance (enable Pi in T3 Code's settings, under providers; see [T3 Code's docs](https://github.com/pingdotgg/t3code/tree/main/docs/user)); not run live |
535
+ | Gemini CLI, Cursor, Copilot CLI, Cline, Crush, goose, Amp, Grok Build, Qwen Code, Kilo, Antigravity | ⏳ planned | conversion | [Help add one](docs/adding-a-harness.md) |
536
+
537
+ Tested live: T3 Code `0.1.9-nightly.20261110`, `.20261111` and `0.1.10-nightly.20261113` on Windows 11; `0.1.8` is
538
+ supported from reading its source; stable releases are not tested yet. Any other build runs
539
+ with a one-line warning (`--allow-untested` hides it); a changed response shape stops with exit 4. macOS
540
+ and Linux are covered by unit tests in CI only. Versions, storage formats and caveats per
541
+ agent: [docs/harnesses.md](docs/harnesses.md).
542
+
543
+ ## Residual limits
544
+
545
+ These come from T3 Code itself; t3sm reports them instead of working around them.
546
+
547
+ - T3 Code shows at most **200 visible messages** per imported thread. Resuming still uses
548
+ the whole session.
549
+ - **Tool activity** (commands, file edits) is not in the imported timeline, only the
550
+ conversation text.
551
+ - Imported threads show the **import time** as their last activity.
552
+ - **Compacted sessions** (`/compact` after the import) are not merged.
553
+ - A thread stays on the account its session was run with. To use the other subscription
554
+ for the same work, start a new thread and pick it.
555
+
556
+ ## Exit codes
557
+
558
+ | Code | Meaning |
559
+ | :-: | :-- |
560
+ | 0 | Done, nothing to do, or you answered no. Also when another t3sm run holds the lock: a scheduled `sync` that finds a manual `apply` running should stay quiet, not raise an alarm |
561
+ | 1 | Unexpected error, a `doctor` check failed, an update that failed or was rolled back, or `schedule install --watch`, `restart` or `remove` that could not stop the running watcher |
562
+ | 2 | Usage or `config.json` error; a writing command on a non-terminal without `--yes`; a plan refused as stale (older than 24 h or made for another T3 Code version); T3 Code's default instance reading another account folder (`instance-home-drift`) |
563
+ | 3 | T3 Code is not running, or stopped answering during the run |
564
+ | 4 | T3 Code speaks another protocol, or an unexpected response from it |
565
+ | 5 | Finished, but some sessions could not be imported (listed; the next run retries) |
566
+ | 10 | `t3sm status` only: something needs you (not an error) |
567
+ | 130 | Interrupted with Ctrl+C (file times restored) |
568
+
569
+ ## FAQ
570
+
571
+ **Will it touch my Claude history?** It never edits a transcript. It changes a
572
+ transcript's file time for the length of a batch and restores it (journaled). It writes
573
+ new files only for conversions and merges, and moves files only when you run `dedupe` or
574
+ `quarantine`, both reversible.
575
+
576
+ **What if I continue a session in the terminal?** That works, but T3 Code will not see the
577
+ new turns until you run `t3sm merge`. Never have the same session open in T3 Code and a
578
+ terminal at the same time.
579
+
580
+ **Can I undo everything?** `t3sm runs` lists the runs and `t3sm rollback --run <id>` undoes
581
+ one. Imported threads are listed, not deleted; `--archive-threads` archives them, and you
582
+ can delete them in T3 Code.
583
+
584
+ **Does it need my Claude login or an API key?** No. It reads no Claude or API credentials
585
+ and never calls a model. T3 Code's instances use the logins you already have in each
586
+ account folder.
587
+
588
+ **How long does it take?** Planning is quick: in one real run on Windows 11, a plan of
589
+ about 3,800 imports across two accounts took 24 seconds (an illustration, not a
590
+ benchmark). `apply` works in waves of at most 5 projects and 50 sessions per project; no
591
+ full-size run has been timed yet (first figures will go into the CHANGELOG after the
592
+ pilot). Start with `t3sm apply --only <project folder>`.
593
+
594
+ **Why are my old conversations in Settled?** T3 Code settles imported conversations and
595
+ shows only unsettled ones inside a project. They are not lost: open **Settled**, or run
596
+ `t3sm organize` to apply the [history rule](#the-history-rule) (the last 90 days, at least
597
+ 10 per project, shown inside their project) and to archive the automated ones that fill the
598
+ list. Once the background sync runs, it keeps the rule by itself.
599
+
600
+ **Where did my home-folder conversations go?** T3 Code cannot import them, so t3sm copies
601
+ each into the project it worked on, or into **General**. `plan.md` lists them. Work you
602
+ continue in the original outside T3 Code is brought in by `t3sm sync`.
603
+
604
+ **Does t3sm go online?** Only to look up its own newest release, once a day and when you run
605
+ `t3sm update` ([details](#automatic-updates)); installing a release downloads it with npm, and
606
+ the optional `/t3sm` plugin install in `t3sm start` goes through `claude plugin` after your
607
+ yes. Nothing about your sessions ever leaves your machine. `t3sm update --auto off` stops the
608
+ daily look.
609
+
610
+ **Does t3sm change T3 Code's settings?** Not by default. `organize` leaves auto-settle as it
611
+ is unless you pass `--auto-settle <1..90|off>` (journaled, undone by `--undo`); `t3sm sync` never changes it. Pinning is the one
612
+ thing it does to projects you created yourself (it unpins only what it pinned), and a project you unpin stays unpinned.
613
+
614
+ **Can I use T3 Code or VS Code while `apply` runs?** Yes. A project with a session written
615
+ in the last 10 minutes is held and imported on a later run, so your work is never touched.
616
+ Do not open the same session in two places at once. Keep the machine awake: a batch
617
+ interrupted by sleep is stopped and retried on the next run.
618
+
619
+ **Can I keep using VS Code?** Yes, for anything T3 Code does not do. Just keep each session
620
+ in one place at a time. See [docs/switching-from-vscode.md](docs/switching-from-vscode.md).
621
+
622
+ **Is T3 Code's database safe?** t3sm never opens it. Projects, instances, defaults and
623
+ imports go through T3 Code's own CLI and API, so T3 Code makes every change itself.
624
+
625
+ **Is this an official T3 Code or Anthropic tool?** No. t3sm is an independent project, not
626
+ affiliated with or endorsed by T3 Code, Ping or Anthropic.
627
+
628
+ ## Uninstall
629
+
630
+ ```bash
631
+ t3sm schedule remove # if you installed the background sync (it stops the watcher too)
632
+ t3sm rollback --run <id> # optional: undo runs you no longer want (see t3sm runs)
633
+ ```
634
+
635
+ Then `npm uninstall -g t3code-session-manager`, delete the state folder
636
+ `~/.t3code-session-manager/` (its `cache/opencode/` holds the stripped OpenCode copies),
637
+ and, once you are sure you do not need them, the quarantine folders
638
+ `~/.claude*/session-manager-quarantine/`. Threads already imported stay in T3 Code.
639
+
640
+ ## Contributing
641
+
642
+ Issues and pull requests are welcome; start with [CONTRIBUTING.md](CONTRIBUTING.md).
643
+ Adding an agent is a self-contained task: [docs/adding-a-harness.md](docs/adding-a-harness.md).
644
+ To check a release live on your own machine, step by step: [docs/testing-0.3.md](docs/testing-0.3.md).
645
+ Security reports: [SECURITY.md](SECURITY.md).
646
+ What comes next, and where help is wanted: [ROADMAP.md](ROADMAP.md).
647
+
648
+ ## Support the project
649
+
650
+ t3sm is free and MIT, built and kept up to date in spare time. If it saved you an afternoon of copying sessions by
651
+ hand, a coffee keeps it going:
652
+
653
+ <p>
654
+ <a href="https://ko-fi.com/brunobola"><img alt="Support on Ko-fi" src="https://img.shields.io/badge/Ko--fi-support-3451D1?logo=kofi&logoColor=white"></a>
655
+ <a href="https://buymeacoffee.com/brunobola"><img alt="Buy me a coffee" src="https://img.shields.io/badge/Buy%20me%20a%20coffee-support-3451D1?logo=buymeacoffee&logoColor=white"></a>
656
+ </p>
657
+
658
+ A star on GitHub, a bug report or a pull request help just as much.
659
+
660
+ ## License
661
+
662
+ [MIT](LICENSE), © 2026 BolaLabs. Not affiliated with T3 Code or Anthropic.