antigravity-plugin-context-mode 1.3.1 → 1.3.2
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/CHANGELOG.md +6 -0
- package/README.md +77 -161
- package/package.json +1 -1
- package/plugin.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to `antigravity-plugin-context-mode` will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## [1.3.2] - 2026-11-17
|
|
6
|
+
|
|
7
|
+
### Documentation
|
|
8
|
+
- **User-Friendly Documentation**: Streamlined `README.md` to focus on end-user benefits, 1-click `npx` installation (global & workspace modes), real-world token savings benchmarks, and interactive sidecar controls.
|
|
9
|
+
- **Synchronized Manifest Version**: Updated `plugin.json` version to match release tag.
|
|
10
|
+
|
|
5
11
|
## [1.3.1] - 2026-11-16
|
|
6
12
|
|
|
7
13
|
### Added
|
package/README.md
CHANGED
|
@@ -1,77 +1,81 @@
|
|
|
1
1
|
# Antigravity Context Mode
|
|
2
2
|
|
|
3
|
-
> **Stop context bloat. Save 90%+ of your prompt tokens. Keep your agent fast, focused, and
|
|
3
|
+
> **Stop context bloat. Save 90%+ of your prompt tokens. Keep your agent fast, focused, and sharp.**
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/antigravity-plugin-context-mode)
|
|
6
|
-
[](https://domush.github.io/antigravity-plugin-context-mode/)
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
[]()
|
|
9
9
|
[]()
|
|
10
10
|
|
|
11
|
-
**Antigravity Context Mode** is a free, local-first plugin built specifically for the **Google Antigravity App**. It prevents terminal commands, build
|
|
11
|
+
**Antigravity Context Mode** is a free, local-first plugin built specifically for the **Google Antigravity App**. It prevents terminal commands, build logs, and multi-megabyte source files from flooding your conversation history — saving thousands of tokens per turn and stopping "agent amnesia" in its tracks.
|
|
12
12
|
|
|
13
|
-
> 🌐 **Live
|
|
13
|
+
> 🌐 **Interactive Live Simulator & Documentation:** [domush.github.io/antigravity-plugin-context-mode](https://domush.github.io/antigravity-plugin-context-mode/)
|
|
14
|
+
|
|
15
|
+
<img width="846" height="503" alt="image" src="https://github.com/user-attachments/assets/2b89e947-4b53-42a6-a0ad-ea744de96c41" />
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Quick Install (10 Seconds)
|
|
19
|
+
|
|
20
|
+
Install directly into Google Antigravity using `npx`:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
# Global install (available across all Antigravity chats)
|
|
24
|
+
npx antigravity-plugin-context-mode install
|
|
25
|
+
|
|
26
|
+
# Or per-project install (scoped to current workspace only)
|
|
27
|
+
npx antigravity-plugin-context-mode install --workspace
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Restart or open the **Google Antigravity App**, and Context Mode is active immediately.
|
|
14
31
|
|
|
15
32
|
---
|
|
16
|
-
<img width="817" height="690" alt="Antigravity Context Mode Dashboard" src="https://github.com/user-attachments/assets/dbf6d666-58d0-48f3-bc02-9783acf3fb37" />
|
|
17
33
|
|
|
18
34
|
## The Problem: Context Window Bloat
|
|
19
35
|
|
|
20
|
-
When an AI coding agent
|
|
36
|
+
When an AI coding agent executes tools, standard workflows dump everything directly into your conversation context:
|
|
21
37
|
|
|
22
38
|
* Running `Get-Content Logs/Editor.log` dumps **65 KB (~16,000 tokens)** into your prompt.
|
|
23
39
|
* Running test suites, compiler outputs, or git diffs dumps **100+ KB** of repetitive text.
|
|
24
|
-
* Reading large
|
|
40
|
+
* Reading large files or documentation dumps **thousands of lines** of irrelevant boilerplate.
|
|
25
41
|
|
|
26
42
|
### Why this hurts:
|
|
27
|
-
1. **Agent Amnesia**: Important system instructions, user constraints, and earlier architectural decisions get drowned out
|
|
28
|
-
2. **Slower Responses**:
|
|
29
|
-
3. **Burned Quota
|
|
43
|
+
1. **Agent Amnesia**: Important system instructions, user constraints, and earlier architectural decisions get drowned out.
|
|
44
|
+
2. **Slower Responses**: Generation times climb as the context window fills up with raw text.
|
|
45
|
+
3. **Burned Quota**: You hit model context ceilings and rate limits after only a few turns.
|
|
30
46
|
|
|
31
47
|
---
|
|
32
48
|
|
|
33
|
-
##
|
|
49
|
+
## How It Works
|
|
34
50
|
|
|
35
51
|
```text
|
|
36
|
-
|
|
37
|
-
│
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
│
|
|
44
|
-
│
|
|
45
|
-
│
|
|
46
|
-
│
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
│ 2. SQLite FTS5 Indexing │
|
|
57
|
-
│ 3. BM25 + Trigram RRF Search │
|
|
58
|
-
└───────────────────────────────────┘
|
|
59
|
-
│
|
|
60
|
-
▼
|
|
61
|
-
Returns only the filtered,
|
|
62
|
-
relevant answer to the chat!
|
|
52
|
+
┌────────────────────────────────────────────────────────┐
|
|
53
|
+
│ 1. Agent attempts to read a large file or command │
|
|
54
|
+
│ (e.g. 5,000-line build log or 40 KB source file) │
|
|
55
|
+
└───────────────────────────┬────────────────────────────┘
|
|
56
|
+
│
|
|
57
|
+
▼
|
|
58
|
+
┌────────────────────────────────────────────────────────┐
|
|
59
|
+
│ 2. Pre-Tool Lifecycle Hook Intercepts Unbounded Dumps │
|
|
60
|
+
│ • Files under 8 KB pass through normally │
|
|
61
|
+
│ • Un-paged dumps over 8 KB are safely intercepted │
|
|
62
|
+
│ • Images, docs, and chat attachments are exempted │
|
|
63
|
+
└───────────────────────────┬────────────────────────────┘
|
|
64
|
+
│
|
|
65
|
+
▼
|
|
66
|
+
┌────────────────────────────────────────────────────────┐
|
|
67
|
+
│ 3. Sandboxed Execution ("Thinking in Code") │
|
|
68
|
+
│ • Agent filters data locally using Node/Python │
|
|
69
|
+
│ • Indexes text into local SQLite FTS5 BM25 database │
|
|
70
|
+
│ • Returns only the exact answer or error to chat! │
|
|
71
|
+
└────────────────────────────────────────────────────────┘
|
|
63
72
|
```
|
|
64
73
|
|
|
65
|
-
1. **Smart Lifecycle Gating (`hooks.json`)**: Before a command or file read executes, Context Mode checks if it will cause a context flood. Applied identically to primary agents and subagents, the hook intercepts un-paged reads exceeding the active cutoff (default 8 KB) and unbounded dumps, guiding agents to query or sandbox the data instead.
|
|
66
|
-
2. **"Thinking in Code" (`ctx_execute`)**: Instead of reading a 5,000-line log into memory, the agent executes a concise local script (Node.js, Python, or PowerShell). The script filters the data in **50 ms** and returns *only* the specific answer or error to the conversation.
|
|
67
|
-
3. **Local SQLite FTS5 Storage (`ctx_search`, `ctx_index`)**: Raw outputs and indexed files are saved safely on your local disk in `~/.context-mode/context.db`. The agent uses reciprocal rank fusion search to fetch only the exact snippets it needs.
|
|
68
|
-
4. **Live Sidecar Dashboard**: A native side pane right inside the Antigravity App that displays real-time context savings across primary agents and subagents, lets you toggle file categories on the fly, and search indexed data with a click.
|
|
69
|
-
|
|
70
74
|
---
|
|
71
75
|
|
|
72
76
|
## Proven Results
|
|
73
77
|
|
|
74
|
-
Tested live on real-world build logs
|
|
78
|
+
Tested live on real-world build logs and source files in the Antigravity App:
|
|
75
79
|
|
|
76
80
|
| Operation | Without Context Mode | With Context Mode | Savings |
|
|
77
81
|
| :--- | :---: | :---: | :---: |
|
|
@@ -81,141 +85,53 @@ Tested live on real-world build logs, source files, and datasets in the Antigrav
|
|
|
81
85
|
|
|
82
86
|
---
|
|
83
87
|
|
|
84
|
-
##
|
|
88
|
+
## Key Features
|
|
85
89
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
This automatically detects your operating system, unpacks the latest release into `~/.gemini/config/plugins/antigravity-plugin-context-mode`, and activates hooks and MCP tools. Restart the Antigravity App to activate!
|
|
94
|
-
|
|
95
|
-
> **Workspace-only install:** To install only for the current project, add `--workspace`:
|
|
96
|
-
> ```bash
|
|
97
|
-
> npx antigravity-plugin-context-mode install --workspace
|
|
98
|
-
> ```
|
|
99
|
-
|
|
100
|
-
---
|
|
101
|
-
|
|
102
|
-
### Method 2: Git Clone (Ideal for Easy Updates)
|
|
103
|
-
If you prefer managing the plugin via Git for easy `git pull` updates:
|
|
104
|
-
|
|
105
|
-
**Windows (PowerShell):**
|
|
106
|
-
```powershell
|
|
107
|
-
git clone https://github.com/Domush/antigravity-plugin-context-mode.git "$env:USERPROFILE\.gemini\config\plugins\antigravity-plugin-context-mode"
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
**macOS / Linux:**
|
|
111
|
-
```bash
|
|
112
|
-
git clone https://github.com/Domush/antigravity-plugin-context-mode.git ~/.gemini/config/plugins/antigravity-plugin-context-mode
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
**To update later:**
|
|
116
|
-
```bash
|
|
117
|
-
cd ~/.gemini/config/plugins/antigravity-plugin-context-mode && git pull
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
---
|
|
121
|
-
|
|
122
|
-
## Live Auxiliary Sidecar Dashboard
|
|
123
|
-
|
|
124
|
-
Context Mode includes a native web dashboard that opens directly in Antigravity's **Auxiliary (Side) Pane**:
|
|
125
|
-
|
|
126
|
-
* **One-Click Open Pill:** Click `[Open Context Mode Dashboard](sidecar://antigravity-plugin-context-mode/dashboard/)` in chat anytime.
|
|
127
|
-
* **Active / Paused Toggle:** Click the status pill in the top header to instantly pause protection when you intentionally need un-gated operations, and click again to re-activate.
|
|
128
|
-
* **Dynamic Version Badge:** Automatically reflects the active plugin version in the top-right header.
|
|
129
|
-
* **Context Saved Progress Bar:** Visual indicator displaying the exact percentage of context window preserved.
|
|
130
|
-
* **3-Way Scope Toggle:** Seamlessly inspect telemetry at three distinct levels:
|
|
131
|
-
* **Conversation**: Metrics strictly for the active chat; clean slate on new conversations. Subagent actions within the conversation feed directly into this view.
|
|
132
|
-
* **Session**: Metrics aggregated across all conversations since the app restarted. Automatically resets transient overrides on app reboot.
|
|
133
|
-
* **Lifetime**: All-time cumulative database metrics and persistent totals. Changing the cutoff in Lifetime updates the baseline defaults for all new sessions and new conversations.
|
|
134
|
-
* **Shared Subagent Feed:** Interceptions triggered by subagents (`researcher`, `browser`, etc.) are badged by role and displayed alongside primary agent events in the same conversation feed.
|
|
135
|
-
* **File Category Toggles:** Clean, one-click pills for grouping exemptions without reading massive lists:
|
|
136
|
-
* **Images** (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`, `.bmp`, `.ico`, `.tiff`, `.psd`) — *Enabled by default*
|
|
137
|
-
* **Documents** (`.pdf`, `.docx`, `.doc`, `.xlsx`, `.xls`, `.pptx`, `.ppt`, `.odt`, `.rtf`) — *Enabled by default*
|
|
138
|
-
* **3D Models** (`.blend`, `.fbx`, `.obj`, `.gltf`, `.glb`, `.stl`, `.dae`, `.3ds`, `.step`, `.iges`) — *Enabled by default*
|
|
139
|
-
* **Music** (`.mp3`, `.wav`, `.ogg`, `.flac`, `.aac`, `.m4a`, `.wma`, `.midi`) — *Enabled by default*
|
|
140
|
-
* **Video** (`.mp4`, `.mov`, `.avi`, `.mkv`, `.webm`, `.flv`, `.wmv`, `.m4v`) — *Enabled by default*
|
|
141
|
-
* **Archives** (`.zip`, `.tar`, `.gz`, `.7z`, `.rar`, `.wasm`) — *Enabled by default*
|
|
142
|
-
* **Source Code** (`.js`, `.ts`, `.py`, `.rs`, `.go`, `.java`, `.c`, `.cpp`, `.cs`, `.html`, `.css`, etc.) — *Disabled by default to protect context*
|
|
143
|
-
* **Custom File Extensions:** Dedicated section displaying only user-added file extensions (e.g. `.csv`, `.parquet`, `.log`) with instant removal.
|
|
144
|
-
* **Chat Attachment Exemption:** Files attached directly in chat messages (`@` mentions and drag-and-drops) always bypass size cutoffs so the agent can inspect them in full.
|
|
145
|
-
* **Interactive Cutoff Dropdown:** Switch size cutoffs on the fly (`2 KB`, `4 KB`, `8 KB`, `16 KB`, `32 KB`, `64 KB`, or `none`). Line slice limits scale dynamically (2 KB: ≤ 50 lines, 8 KB: ≤ 200 lines, 32 KB: ≤ 800 lines).
|
|
146
|
-
* **Interactive FTS5 Search Inspector:** Search your indexed logs and files directly from the UI to inspect what the agent has indexed.
|
|
147
|
-
* **1-Click Session Purge:** Wipe session indexes and reset counters whenever you start a fresh task.
|
|
90
|
+
* 🛡️ **Automated Interception**: Blocks unbounded file dumps and commands before they bloat your context window.
|
|
91
|
+
* ⚡ **Thinking in Code**: Filters multi-thousand-line outputs in 50 ms via local sandboxed scripts.
|
|
92
|
+
* 🔍 **Local SQLite FTS5 Search**: Indexes files and logs locally on your machine with BM25 keyword matching and trigram search.
|
|
93
|
+
* 📊 **Built-In Sidecar Dashboard**: Real-time stats pane inside Antigravity showing tokens kept out of context.
|
|
94
|
+
* 🔒 **100% Local & Private**: All indexed data stays on your machine in `~/.context-mode/context.db`. Zero network calls.
|
|
95
|
+
* 📦 **Zero Dependencies**: Pure native Node.js (`node:sqlite`). No native builds, no `node-gyp`.
|
|
148
96
|
|
|
149
97
|
---
|
|
150
98
|
|
|
151
99
|
## Available MCP Tools
|
|
152
100
|
|
|
153
|
-
Once installed,
|
|
101
|
+
Once installed, Context Mode provides 8 specialized tools for your agent:
|
|
154
102
|
|
|
155
|
-
| Tool | What It Does |
|
|
156
|
-
| :--- | :--- |
|
|
157
|
-
| **`ctx_execute`** | Runs sandboxed Node.js, Python, or PowerShell scripts
|
|
158
|
-
| **`ctx_search`** | Searches
|
|
159
|
-
| **`ctx_index`** | Indexes local files
|
|
160
|
-
| **`ctx_batch`** | Runs multiple
|
|
161
|
-
| **`ctx_stats`** | Displays a formatted savings report and token metrics. |
|
|
162
|
-
| **`ctx_resume`** | Returns recent indexed sources and state pointers
|
|
163
|
-
| **`ctx_doctor`** | Checks SQLite database health, WAL mode, and
|
|
164
|
-
| **`ctx_purge`** | Clears stored sources and events from SQLite. |
|
|
103
|
+
| Tool | What It Does |
|
|
104
|
+
| :--- | :--- |
|
|
105
|
+
| **`ctx_execute`** | Runs sandboxed Node.js, Python, or PowerShell scripts to inspect files and extract answers without context dumps. |
|
|
106
|
+
| **`ctx_search`** | Searches indexed logs and documentation using local SQLite FTS5 BM25 stemming. |
|
|
107
|
+
| **`ctx_index`** | Indexes local files or documentation into searchable chunks for the agent. |
|
|
108
|
+
| **`ctx_batch`** | Runs multiple terminal commands in batch and indexes the combined output. |
|
|
109
|
+
| **`ctx_stats`** | Displays a formatted context savings report and token metrics. |
|
|
110
|
+
| **`ctx_resume`** | Returns recent indexed sources and state pointers after context compactions. |
|
|
111
|
+
| **`ctx_doctor`** | Checks SQLite database health, WAL mode, and platform runtimes. |
|
|
112
|
+
| **`ctx_purge`** | Clears stored sources and events from SQLite. |
|
|
165
113
|
|
|
166
114
|
---
|
|
167
115
|
|
|
168
|
-
##
|
|
116
|
+
## Managing the Plugin
|
|
169
117
|
|
|
170
|
-
|
|
118
|
+
### Enable / Disable Anytime
|
|
119
|
+
Open the **Google Antigravity App** → **Customizations** → **Plugins**, and toggle **Context Mode** on or off with one click.
|
|
171
120
|
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
| `CONTEXT_MODE_MAX_READ_BYTES` | `8192` (8 KB) | Size threshold beyond which un-paged file reads are rejected. Set `0` to disable. |
|
|
175
|
-
| `CONTEXT_MODE_MAX_LINE_RANGE` | *Dynamic* (or `200`) | Maximum allowable line slice range before pagination rejection (scales with cutoff). |
|
|
176
|
-
| `CONTEXT_MODE_MAX_OUTPUT_BYTES` | *Dynamic* (or `16384`) | Maximum raw preview bytes returned by `ctx_execute` (defaults to 2x cutoff). |
|
|
177
|
-
| `CONTEXT_MODE_TIMEOUT_MS` | `30000` (30s) | Execution timeout for sandboxed code snippets. |
|
|
121
|
+
### Adjust Cutoffs
|
|
122
|
+
You can adjust the file read cutoff directly in the sidecar dashboard dropdown (`2 KB`, `4 KB`, `8 KB`, `16 KB`, `32 KB`, `64 KB`, or `none`).
|
|
178
123
|
|
|
179
|
-
###
|
|
180
|
-
|
|
181
|
-
$env:CONTEXT_MODE_MAX_READ_BYTES = "4096" # Enforce strict 4 KB cutoff
|
|
182
|
-
```
|
|
124
|
+
### Uninstall
|
|
125
|
+
To remove the plugin from your system:
|
|
183
126
|
|
|
184
|
-
### How to set on macOS / Linux:
|
|
185
127
|
```bash
|
|
186
|
-
|
|
187
|
-
|
|
128
|
+
# Remove global plugin
|
|
129
|
+
npx antigravity-plugin-context-mode uninstall
|
|
188
130
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
## Privacy & Zero Dependencies
|
|
192
|
-
|
|
193
|
-
* **100% Local**: All indexed data lives on your machine in `~/.context-mode/context.db`. Zero network calls are made.
|
|
194
|
-
* **Zero 3rd-Party Dependencies**: Built exclusively on native Node.js (`node:sqlite` / `DatabaseSync`, `child_process`, and `http`). No native C++ builds, no `node-gyp`, and no dependency security vulnerabilities.
|
|
195
|
-
* **Safe Sandboxing**: Process execution in `ctx_execute` enforces strict execution timeouts and output caps to prevent runaway processes.
|
|
196
|
-
|
|
197
|
-
---
|
|
198
|
-
|
|
199
|
-
## Running Tests
|
|
200
|
-
|
|
201
|
-
Context Mode ships with a complete test suite using Node's native test runner:
|
|
202
|
-
|
|
203
|
-
```bash
|
|
204
|
-
npm test
|
|
131
|
+
# Remove per-project plugin
|
|
132
|
+
npx antigravity-plugin-context-mode uninstall --workspace
|
|
205
133
|
```
|
|
206
134
|
|
|
207
|
-
Verifies:
|
|
208
|
-
* SQLite FTS5 schema initialization, chunking, Porter BM25, and Trigram search.
|
|
209
|
-
* Reciprocal Rank Fusion (RRF) ranking.
|
|
210
|
-
* Sandbox execution and process timeout termination.
|
|
211
|
-
* `PreToolUse` and `SessionStart` lifecycle hook gating for primary agents and subagents.
|
|
212
|
-
* Shared conversation dashboard linking and subagent interception event journal.
|
|
213
|
-
* Lifetime cutoff inheritance across new sessions and new conversations.
|
|
214
|
-
* Mathematically accurate context savings calculations without double-counting.
|
|
215
|
-
* File category toggles and custom extension management.
|
|
216
|
-
* Active / Paused state toggle and bypass logic.
|
|
217
|
-
* MCP stdio JSON-RPC protocol compliance.
|
|
218
|
-
|
|
219
135
|
---
|
|
220
136
|
|
|
221
137
|
## License
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "antigravity-plugin-context-mode",
|
|
3
|
-
"version": "1.3.
|
|
3
|
+
"version": "1.3.2",
|
|
4
4
|
"description": "Native Antigravity plugin for context-mode: SQLite FTS5 indexing, sandboxed execution, and lifecycle hook protection against context window bloat",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
package/plugin.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"name": "antigravity-plugin-context-mode",
|
|
3
3
|
"displayName": "Context Mode",
|
|
4
4
|
"description": "Context window protection for Antigravity: local SQLite FTS5 search, sandboxed execution, and lifecycle hook gating against token bloat.",
|
|
5
|
-
"version": "1.3.
|
|
5
|
+
"version": "1.3.2",
|
|
6
6
|
"author": "Phillip Webber <github@webbsense.com>",
|
|
7
7
|
"repository": {
|
|
8
8
|
"type": "git",
|