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