@tinchu0/knitt 0.1.0-beta.4 → 0.1.0-beta.5
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/README.md +26 -15
- package/dist/apps/server/src/conversation-server.js +203 -0
- package/dist/apps/server/src/http-gateway.js +1 -1
- package/dist/apps/server/src/main.js +6 -2
- package/dist/apps/server/src/server.js +292 -81
- package/dist/memory-schema.json +1 -0
- package/dist/packages/adapters/src/cli.js +193 -45
- package/dist/packages/adapters/src/command.js +149 -18
- package/dist/packages/adapters/src/discovery.js +128 -0
- package/dist/packages/adapters/src/handoff.js +13 -8
- package/dist/packages/adapters/src/histories.js +222 -0
- package/dist/packages/adapters/src/history-time.js +10 -0
- package/dist/packages/adapters/src/hooks.js +123 -44
- package/dist/packages/adapters/src/launch.js +10 -3
- package/dist/packages/adapters/src/picker.js +2 -1
- package/dist/packages/adapters/src/providers/jsonl.js +105 -0
- package/dist/packages/adapters/src/question-ui.js +37 -0
- package/dist/packages/adapters/src/repository.js +32 -5
- package/dist/packages/adapters/src/scope.js +9 -3
- package/dist/packages/adapters/src/server-name.js +6 -0
- package/dist/packages/adapters/src/status.js +81 -0
- package/dist/packages/adapters/src/transcript.js +72 -15
- package/dist/packages/contracts/src/conversations.js +30 -0
- package/dist/packages/installer/src/antigravity.js +90 -0
- package/dist/packages/installer/src/cli.js +210 -48
- package/dist/packages/installer/src/connections.js +193 -38
- package/dist/packages/installer/src/runtime.js +73 -11
- package/dist/packages/memory/src/checkpoints.js +68 -0
- package/dist/packages/memory/src/context.js +91 -0
- package/dist/packages/memory/src/conversations.js +148 -0
- package/dist/packages/memory/src/migrations.js +55 -0
- package/dist/packages/memory/src/store.js +201 -23
- package/dist/skills/continue-chat/SKILL.md +15 -0
- package/dist/skills/knit/SKILL.md +11 -5
- package/docs/clients/connector-setup.md +1 -1
- package/docs/clients/local-agent-memory.md +50 -0
- package/docs/clients/npm-installation.md +23 -11
- package/docs/clients/support-matrix.md +12 -0
- package/docs/usage.md +19 -29
- package/package.json +5 -4
|
@@ -1,6 +1,14 @@
|
|
|
1
1
|
# npm installation and runtime lifecycle
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## Install the beta
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npx --yes @tinchu0/knitt@next setup --workspace /path/to/project --client antigravity
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Setup registers Antigravity’s global MCP server and verifies its memory tools automatically. Restart Antigravity and use `/knit` in a fresh chat. Choose a conversation inside the same coding interface. Antigravity uses its selectable question UI; clients with native MCP forms can use those.
|
|
10
|
+
|
|
11
|
+
## Test a local build
|
|
4
12
|
|
|
5
13
|
Build and pack from the repository:
|
|
6
14
|
|
|
@@ -14,12 +22,12 @@ npm pack
|
|
|
14
22
|
Then use the tarball (absolute paths work from any directory):
|
|
15
23
|
|
|
16
24
|
```bash
|
|
17
|
-
npx --yes --package ./tinchu0-knitt-0.1.0-beta.
|
|
25
|
+
npx --yes --package ./tinchu0-knitt-0.1.0-beta.5.tgz knitt setup \
|
|
18
26
|
--workspace /path/to/project --client codex --client claude-code \
|
|
19
|
-
--package /absolute/path/to/tinchu0-knitt-0.1.0-beta.
|
|
27
|
+
--package /absolute/path/to/tinchu0-knitt-0.1.0-beta.5.tgz
|
|
20
28
|
```
|
|
21
29
|
|
|
22
|
-
The outer `--package` tells npx which CLI to run. The `--package` after `setup` tells setup which exact artifact to install persistently.
|
|
30
|
+
The outer `--package` tells npx which CLI to run. The `--package` after `setup` tells setup which exact artifact to install persistently. For a local build, pass this second argument to setup/update so the persistent runtime uses your local artifact. For a published CLI, omitting it installs the CLI's exact published version. `update` follows the `next` registry tag for prerelease CLIs and `latest` for stable CLIs.
|
|
23
31
|
|
|
24
32
|
Use `--preview` to inspect changes without creating installation/configuration files. Interactive setup asks before applying; automation must pass `--yes`. Repeat `--client` for several agents. Setup requires Git repository metadata to derive a stable repository identity.
|
|
25
33
|
|
|
@@ -27,19 +35,19 @@ Use `--preview` to inspect changes without creating installation/configuration f
|
|
|
27
35
|
|
|
28
36
|
Install Node.js 24+ (including npm) and Git, and ensure both are on PATH. Use the same package on all platforms. Windows hooks use built-in Windows PowerShell 5.1 (`powershell.exe` on PATH); no WSL or Python is needed for npm setup. macOS and Linux hooks use their existing POSIX shell.
|
|
29
37
|
|
|
30
|
-
|
|
38
|
+
For a local build, pack the tarball as above, then run from its directory. Windows PowerShell example (one line, with quoted paths):
|
|
31
39
|
|
|
32
40
|
```powershell
|
|
33
|
-
npx --yes --package .\tinchu0-knitt-0.1.0-beta.
|
|
41
|
+
npx --yes --package .\tinchu0-knitt-0.1.0-beta.5.tgz knitt setup --workspace "C:\Users\you\My Project" --client codex --client claude-code --package "C:\Downloads\tinchu0-knitt-0.1.0-beta.5.tgz"
|
|
34
42
|
```
|
|
35
43
|
|
|
36
44
|
macOS example:
|
|
37
45
|
|
|
38
46
|
```sh
|
|
39
|
-
npx --yes --package ./tinchu0-knitt-0.1.0-beta.
|
|
47
|
+
npx --yes --package ./tinchu0-knitt-0.1.0-beta.5.tgz knitt setup --workspace "$HOME/Projects/My Project" --client codex --client claude-code --package "$HOME/Downloads/tinchu0-knitt-0.1.0-beta.5.tgz"
|
|
40
48
|
```
|
|
41
49
|
|
|
42
|
-
Replace the artifact path with its actual location. The existing lifecycle commands below work on each platform. Restart clients and approve their normal hook/MCP trust prompts. For Claude Desktop, merge the generated fragment into Desktop settings manually.
|
|
50
|
+
Replace the artifact path with its actual location. The existing lifecycle commands below work on each platform. Restart clients and approve their normal hook/MCP trust prompts. For Claude Desktop, merge the generated fragment into Desktop settings manually. For Antigravity, setup registers a separate server for each project in `~/.gemini/config/mcp_config.json`, preserving existing servers, and verifies its tool connection. Project `.agents/mcp_config.json` alone does not activate it. Override the global config location with `--antigravity-config PATH` during setup; the installer remembers it for later commands. `KNITT_ANTIGRAVITY_CONFIG` is an alternative override for isolated environments.
|
|
43
51
|
|
|
44
52
|
## Durable installation
|
|
45
53
|
|
|
@@ -57,7 +65,7 @@ The project-local `.memory/npm-connection.json` records original and generated s
|
|
|
57
65
|
|
|
58
66
|
## Commands
|
|
59
67
|
|
|
60
|
-
Run commands through
|
|
68
|
+
Run commands through `npx --yes @tinchu0/knitt@next` or the local tarball CLI above:
|
|
61
69
|
|
|
62
70
|
```text
|
|
63
71
|
knitt setup --workspace PATH --client codex --preview
|
|
@@ -72,10 +80,14 @@ Use the same `--home` for every lifecycle command if you customized it. `doctor`
|
|
|
72
80
|
|
|
73
81
|
Update installs another runtime before changing project connections. Failed dependency installation leaves the active installation metadata and bindings untouched. Rollback switches managed projects to the previous runtime, preserving memory. Old runtime directories remain available; garbage collection is not implemented.
|
|
74
82
|
|
|
75
|
-
Uninstall restores unchanged managed values and preserves independent additions or user edits. It removes one project's bindings and registry entry while retaining the runtime and all memory. It does not recursively delete the application directory or memory. Claude Desktop fragments must
|
|
83
|
+
Uninstall restores unchanged managed values and preserves independent additions or user edits. It removes one project's bindings and registry entry while retaining the runtime and all memory. It does not recursively delete the application directory or memory. Antigravity’s unchanged global entries are removed automatically; user-edited entries remain. The `.knitt-*.json` ownership file beside its MCP config is retained until the last managed entry is removed. Claude Desktop fragments must be removed manually from Desktop settings if previously merged there. Older manually merged Antigravity entries are not adopted or removed automatically.
|
|
76
84
|
|
|
77
85
|
## Release gates
|
|
78
86
|
|
|
79
|
-
The
|
|
87
|
+
The npm package is `@tinchu0/knitt`; prereleases use the `next` tag. Knitt is licensed under Apache-2.0; LICENSE ships in the archive. Linux tarball lifecycle checks cover automatic Antigravity registration, native session IDs, MCP tool discovery, updates, rollback after failed server verification and uninstall. CI is configured for Linux, macOS and Windows; native macOS/Windows runs and live client behavior remain unverified until observed.
|
|
80
88
|
|
|
81
89
|
ChatGPT, Claude web and teammate machines require a separately reachable authenticated service. Packaging a CLI does not supply hosting, authentication accounts or background synchronization.
|
|
90
|
+
|
|
91
|
+
### Optional local conversation mode
|
|
92
|
+
|
|
93
|
+
Add `--capture-new-sessions` to setup to opt a connected project into independent session capture and explicit continuation links. The preference survives subsequent setup/update operations. Existing connections keep their previous semantics until opted in. This mode upgrades the database using consistent SQLite backups; the updated installer blocks incompatible runtime downgrade rather than restoring data automatically. Use `doctor` for content-free capture status. See [setup and recovery](local-agent-memory.md).
|
|
@@ -35,3 +35,15 @@ Live local result: fresh Codex sessions verified automatic Stop capture and star
|
|
|
35
35
|
| Windows | Native PowerShell hooks; shell-free npm JS entry point; LOCALAPPDATA storage | Windows command generation/npm discovery checked on Linux; CI configured on windows-latest. Native execution and live client handoff not yet observed. |
|
|
36
36
|
|
|
37
37
|
The matrix workflow runs Node.js 24 and Python 3.12. Python is used only by legacy source-installer tests, not the npm runtime. All runners execute type checking, the full suite and the tarball lifecycle smoke test. Configured CI is not evidence that a remote run has passed.
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
## Antigravity npm registration and picker · 2026-11-14
|
|
41
|
+
|
|
42
|
+
Npm setup now registers a separate MCP entry per project in Antigravity’s global config and verifies its five tools before runtime activation. Project hooks name that entry and supply the native chat ID. Antigravity shows conversation options inside the same chat because a recorded native-form request returned `selected: false` without an accepted choice. Other coding clients use native forms where supported and in-chat options otherwise. Tests exercise explicit selection, cancellation, session isolation, single-use choice IDs, preservation of unrelated settings and rollback on failed server verification. Automated process evidence does not establish that a human completed this flow inside each client. Browser pickers remain a remote HTTP connector feature.
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
## Cross-agent history discovery · 2026-11-14
|
|
46
|
+
|
|
47
|
+
Coding connections identify their host with MEMORY_CLIENT. The picker excludes that source before searching/limiting, merges local Claude Code project JSONL, Codex indexed/session-file history and Antigravity indexed history, labels the source and orders by timestamp newest first. Tests cover every host/source pair, same-ID collisions across agents, indexed and session-file Codex discovery, incomplete-index fallback, source/branch attribution, redaction, worktrees, unrelated projects and subagent exclusion. Local scans confirmed Claude and Codex discovery for Weave; actual rigved connections returned 16 Codex histories for Antigravity and seven Antigravity histories for Codex, without importing a choice. No local Claude history was found for rigved.
|
|
48
|
+
|
|
49
|
+
72 tests and the packaged install/update/rollback/uninstall smoke passed after the correction. Native visual behavior still depends on the host client; the test validates protocol behavior and source selection, not a human completing every client UI.
|
package/docs/usage.md
CHANGED
|
@@ -16,26 +16,15 @@ git --version
|
|
|
16
16
|
|
|
17
17
|
The installer includes native Linux, macOS and Windows paths. Windows hooks require built-in Windows PowerShell; macOS and Linux use POSIX hooks. Linux checks passed locally; native Windows/macOS runs still need confirmation. Client configuration support does not guarantee that every client has passed a live handoff test. See the [client support evidence](clients/support-matrix.md).
|
|
18
18
|
|
|
19
|
-
## 2.
|
|
19
|
+
## 2. Run the package
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
From the Knitt source checkout:
|
|
21
|
+
Use the published beta through npm’s `next` channel:
|
|
24
22
|
|
|
25
23
|
```bash
|
|
26
|
-
|
|
27
|
-
npm run check
|
|
28
|
-
npm run build
|
|
29
|
-
npm pack
|
|
24
|
+
npx --yes @tinchu0/knitt@next --version
|
|
30
25
|
```
|
|
31
26
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
```bash
|
|
35
|
-
KNITT_TARBALL="/absolute/path/to/knitt/tinchu0-knitt-0.1.0-beta.1.tgz"
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
Replace the example path with the location printed by `npm pack`. If the package version changes, use the new filename. Keep the tarball available for later management commands.
|
|
27
|
+
No source checkout is needed. To test a source build instead, see [local tarball installation](clients/npm-installation.md).
|
|
39
28
|
|
|
40
29
|
## 3. Connect your project
|
|
41
30
|
|
|
@@ -44,7 +33,7 @@ Replace `/absolute/path/to/your-project` below with the Git repository whose con
|
|
|
44
33
|
First preview the configuration:
|
|
45
34
|
|
|
46
35
|
```bash
|
|
47
|
-
npx --yes
|
|
36
|
+
npx --yes @tinchu0/knitt@next setup \
|
|
48
37
|
--workspace /absolute/path/to/your-project \
|
|
49
38
|
--client codex --client antigravity \
|
|
50
39
|
--preview
|
|
@@ -53,17 +42,16 @@ npx --yes --package "$KNITT_TARBALL" knitt setup \
|
|
|
53
42
|
Then install:
|
|
54
43
|
|
|
55
44
|
```bash
|
|
56
|
-
npx --yes
|
|
45
|
+
npx --yes @tinchu0/knitt@next setup \
|
|
57
46
|
--workspace /absolute/path/to/your-project \
|
|
58
|
-
--client codex --client antigravity
|
|
59
|
-
--package "$KNITT_TARBALL"
|
|
47
|
+
--client codex --client antigravity
|
|
60
48
|
```
|
|
61
49
|
|
|
62
50
|
Review the displayed changes and confirm in the terminal. For noninteractive setup, add `--yes` after `setup`; the outer `npx --yes` only approves npx's package prompt.
|
|
63
51
|
|
|
64
52
|
Supported `--client` values are `codex`, `claude-code`, `antigravity`, and `claude-desktop`. Repeat the flag for each client you use. Running setup without `--workspace` and `--client` asks for them interactively.
|
|
65
53
|
|
|
66
|
-
|
|
54
|
+
Setup installs a persistent runtime matching the CLI version. Connected agents use it independently of npx's temporary cache.
|
|
67
55
|
|
|
68
56
|
Restart connected agents, open the target project, and approve their normal MCP and hook trust prompts. Claude Desktop needs an extra manual step described below.
|
|
69
57
|
|
|
@@ -79,9 +67,9 @@ If your client does not expose slash skills, ask:
|
|
|
79
67
|
|
|
80
68
|
> Use Knitt's shared-memory connection to open the conversation picker. Let me choose a chat, then retrieve its checkpoint and summarize the last progress and next step.
|
|
81
69
|
|
|
82
|
-
Choose the source conversation
|
|
70
|
+
Choose the source conversation inside your coding interface. Antigravity opens its selectable question UI; click the conversation you want. Clients supporting native forms can show those directly. No browser or separate terminal is required for a connected coding client. Knitt requires the active folder on each coding-picker call and rejects a connection for a different project. The picker shows the project folder above its choices. It discovers local **Claude Code, Codex and Antigravity histories** belonging to that repository, including linked worktrees. It excludes the agent you are using, labels each source, and offers only the four most recent matching chats, newest first. It does not browse remote Claude or ChatGPT account history.
|
|
83
71
|
|
|
84
|
-
After selection, the
|
|
72
|
+
After selection, Knitt returns bounded context in the acceptance response and the agent shows the restored checkpoint. Older servers fall back to one `get_context` call. Review it, then give a concrete instruction, for example:
|
|
85
73
|
|
|
86
74
|
> Continue the retry implementation from this checkpoint. Inspect the current branch first and run the relevant tests after making changes.
|
|
87
75
|
|
|
@@ -107,9 +95,11 @@ Checkpoints are reference material: inspect current files and branch state befor
|
|
|
107
95
|
|
|
108
96
|
## Claude Desktop, ChatGPT, and Claude web
|
|
109
97
|
|
|
98
|
+
**Antigravity:** setup automatically registers and verifies a project-specific memory server in `~/.gemini/config/mcp_config.json`, preserving existing servers. Restart Antigravity and use `/knit` in a fresh chat. Choose a conversation inside the same coding interface. Antigravity uses its selectable question UI; clients with native MCP forms can use those. Several projects can coexist; startup hooks identify the matching server. Update, rollback and uninstall manage Knitt’s unchanged entries. Use `--antigravity-config PATH` during setup if your installation uses another location; subsequent lifecycle commands remember that path.
|
|
99
|
+
|
|
110
100
|
**Claude Desktop:** select `--client claude-desktop` during setup. Merge the generated project's `.memory/connectors/claude-desktop.json` `mcpServers` entry into Desktop's local MCP settings, then restart Desktop. Knitt generates the fragment; it does not perform this merge for you.
|
|
111
101
|
|
|
112
|
-
In a new ordinary chat, ask the agent to call `start_session`, then `choose_conversation`, wait for your selection, and call `get_context
|
|
102
|
+
In a new ordinary chat, ask the agent to call `start_session`, then `choose_conversation`, wait for your selection, and summarize the returned context (or call `get_context` if using the browser fallback). Use the session ID returned for that chat. Ask for `save_memory` after substantive progress.
|
|
113
103
|
|
|
114
104
|
**ChatGPT and Claude web:** require a separately hosted HTTPS MCP endpoint and a compatible OAuth provider. Local CLI setup does not deploy that service. Follow [remote connector setup](clients/connector-setup.md) for profiles, authentication requirements, and browser picker behavior. These clients are not assumed to be live-connected by completing the local quickstart.
|
|
115
105
|
|
|
@@ -117,12 +107,12 @@ Local memory lives on one machine. Connecting another machine or using an identi
|
|
|
117
107
|
|
|
118
108
|
## Manage your installation
|
|
119
109
|
|
|
120
|
-
Use the same
|
|
110
|
+
Use the same npm channel and, if configured, the same `--home /absolute/path` for all commands.
|
|
121
111
|
|
|
122
112
|
Check the installation:
|
|
123
113
|
|
|
124
114
|
```bash
|
|
125
|
-
npx --yes
|
|
115
|
+
npx --yes @tinchu0/knitt@next doctor
|
|
126
116
|
```
|
|
127
117
|
|
|
128
118
|
`configured` means local paths and managed settings passed inspection. It does not verify client login, trust approval, or a live handoff.
|
|
@@ -138,13 +128,13 @@ npx --yes --package "$KNITT_NEXT_TARBALL" knitt update \
|
|
|
138
128
|
Return to the previous runtime, if an earlier installation exists:
|
|
139
129
|
|
|
140
130
|
```bash
|
|
141
|
-
npx --yes
|
|
131
|
+
npx --yes @tinchu0/knitt@next rollback --yes
|
|
142
132
|
```
|
|
143
133
|
|
|
144
134
|
Disconnect one project:
|
|
145
135
|
|
|
146
136
|
```bash
|
|
147
|
-
npx --yes
|
|
137
|
+
npx --yes @tinchu0/knitt@next uninstall \
|
|
148
138
|
--workspace /absolute/path/to/your-project --yes
|
|
149
139
|
```
|
|
150
140
|
|
|
@@ -155,8 +145,8 @@ Uninstall restores unchanged managed settings while retaining user edits, the ru
|
|
|
155
145
|
| Symptom | What to check |
|
|
156
146
|
| --- | --- |
|
|
157
147
|
| No shared-memory tools or `/knit` | Restart the client in the connected project. Check MCP and hook trust prompts, then run `doctor`. |
|
|
158
|
-
| No conversations in the picker | Confirm
|
|
159
|
-
| Client cannot show a selection form |
|
|
148
|
+
| No conversations in the picker | Confirm another coding agent has a local history for this repository or its worktrees. The current agent’s own chats are excluded. Try searching the source title. Remote account histories are not imported. |
|
|
149
|
+
| Client cannot show a selection form | The agent must invoke the application’s native question tool with Knitt’s returned options. A printed list is not the picker. If the question tool is unavailable, native selection is unavailable in that session. Remote web connectors may use a browser picker. |
|
|
160
150
|
| “No chat selected” | Open the picker and choose a conversation in this session before retrieving or saving context. |
|
|
161
151
|
| Missing startup session ID | Reload the project's memory connection and start a fresh session. Ordinary chat clients use `start_session`; do not invent an ID. |
|
|
162
152
|
| “Wrong repository” or “different conversation” | Open the intended project and choose its chat in the current session. |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tinchu0/knitt",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.5",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"engines": {
|
|
6
6
|
"node": ">=24"
|
|
@@ -34,11 +34,12 @@
|
|
|
34
34
|
"files": [
|
|
35
35
|
"dist/",
|
|
36
36
|
"README.md",
|
|
37
|
-
"docs/usage.md",
|
|
38
|
-
"docs/clients/support-matrix.md",
|
|
39
37
|
"docs/clients/connector-setup.md",
|
|
40
38
|
"docs/clients/npm-installation.md",
|
|
41
|
-
"LICENSE"
|
|
39
|
+
"LICENSE",
|
|
40
|
+
"docs/clients/local-agent-memory.md",
|
|
41
|
+
"docs/usage.md",
|
|
42
|
+
"docs/clients/support-matrix.md"
|
|
42
43
|
],
|
|
43
44
|
"repository": {
|
|
44
45
|
"type": "git",
|