sapper-iq 1.1.39 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +255 -149
  2. package/package.json +7 -3
  3. package/sapper-ui.mjs +1577 -1863
  4. package/sapper.mjs +2974 -508
package/README.md CHANGED
@@ -1,73 +1,94 @@
1
+ <div align="center">
2
+
1
3
  # Sapper
2
4
 
3
- [![npm version](https://img.shields.io/npm/v/sapper-iq.svg?style=flat-square)](https://www.npmjs.com/package/sapper-iq)
4
- [![Node.js](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen?style=flat-square)](https://nodejs.org)
5
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
6
- [![npm downloads](https://img.shields.io/npm/dm/sapper-iq?style=flat-square)](https://www.npmjs.com/package/sapper-iq)
5
+ **Terminal-first AI coding assistant powered by local Ollama models.**
6
+
7
+ [![npm version](https://img.shields.io/npm/v/sapper-iq.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/sapper-iq)
8
+ [![npm downloads](https://img.shields.io/npm/dm/sapper-iq?style=flat-square&color=cb3837)](https://www.npmjs.com/package/sapper-iq)
9
+ [![Node.js](https://img.shields.io/badge/node-%E2%89%A516-brightgreen?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
10
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
11
+ [![Local-first](https://img.shields.io/badge/local--first-100%25-success?style=flat-square)](#)
12
+
13
+ [Install](#installation) · [Quick Start](#quick-start) · [Commands](#commands) · [Tools](#tool-catalog) · [Voice](#voice--whisper) · [Config](#configuration)
14
+
15
+ </div>
7
16
 
8
- **Terminal-first AI coding assistant for real developer workflows.**
17
+ ---
18
+
19
+ Sapper is a Node.js CLI that pairs with locally-running Ollama models to act as an autonomous development agent. It reads and writes files, runs shell commands, manages git, browses the web, and now transcribes your voice — all from a single conversational loop in your terminal.
9
20
 
10
- Sapper is a Node.js CLI that connects to locally running Ollama models and acts as an autonomous development agent — reading, writing, searching, running shell commands, managing git, and browsing the web, all from a single conversational interface in your terminal.
21
+ > **100% local. 100% private. Zero telemetry.** Your code, prompts, and audio never leave your machine.
11
22
 
12
23
  ---
13
24
 
14
25
  ## Table of Contents
15
26
 
16
- - [Terminal Interface](#terminal-interface)
17
- - [Architecture](#architecture)
18
- - [Features](#features)
19
- - [Prerequisites](#prerequisites)
27
+ - [Highlights](#highlights)
28
+ - [Screens](#screens)
20
29
  - [Installation](#installation)
21
30
  - [Quick Start](#quick-start)
22
31
  - [How It Works](#how-it-works)
23
32
  - [Commands](#commands)
24
33
  - [Tool Catalog](#tool-catalog)
25
- - [Agents and Skills](#agents-and-skills)
34
+ - [Voice / Whisper](#voice--whisper)
35
+ - [Agents & Skills](#agents--skills)
26
36
  - [Configuration](#configuration)
27
37
  - [Session Memory](#session-memory)
38
+ - [Project Layout](#project-layout)
28
39
  - [Development](#development)
29
40
  - [License](#license)
30
41
 
31
42
  ---
32
43
 
33
- ## Terminal Interface
44
+ ## Highlights
34
45
 
35
- Sapper presents three distinct screens during a session, each with a focused purpose.
46
+ | | |
47
+ |---|---|
48
+ | **Local-first** | Connects to any Ollama model on your machine — no API keys, no cloud calls |
49
+ | **28+ built-in tools** | Files, shell, git, web, AST symbols, embeddings |
50
+ | **Native tool calling** | First-class support for Ollama's function-calling API, with a legacy text-marker fallback |
51
+ | **Voice input** | Talk to Sapper with Whisper (`/v live`) — interactive model picker, archive, push-to-stop, Arabic + multilingual |
52
+ | **Auto-summarization** | Compresses old turns when the context window fills, transparently |
53
+ | **Custom agents & skills** | Drop a Markdown file in `.sapper/agents/` or `.sapper/skills/` and it's live |
54
+ | **Background shell** | Long-running commands hand off to tracked background sessions you can read/stop |
55
+ | **Approval gate** | Inline approval prompts with feedback for shell and write operations |
56
+ | **Semantic memory** | Embedding-based recall surfaces relevant past context automatically |
57
+ | **Per-project state** | Everything lives in `.sapper/` — clean, portable, gitignore-friendly |
36
58
 
37
- ### Startup — Session Dashboard
59
+ ---
38
60
 
39
- When Sapper launches it immediately displays the full state of the current working directory before asking for any input.
61
+ ## Screens
62
+
63
+ ### Startup Dashboard
64
+
65
+ On launch, Sapper shows the full state of your workspace before asking for input.
40
66
 
41
67
  ```
42
- Sapper terminal workspace
68
+ Sapper terminal coding workspace
43
69
  Local models, live tools, and focused coding in one loop
44
- /your/project · v1.1.38
70
+ /your/project · v1.1.40
45
71
 
46
- Quick start @file attach · /help commands · /agents modes
72
+ Quick start @file attach · /commands palette · /agents modes
47
73
 
48
74
  ┌──────────────────────────────────────────────────────────────┐
49
75
  │ [workspace] 5 files · 0 symbols · indexed 36103m ago │
50
76
  │ [memory] .sapper/ · auto-attach on │
51
- │ [prompt] default prompt │
52
- │ [thinking] mode auto │
53
- │ [tools] limit 40 rounds │
77
+ │ [prompt] default prompt │
78
+ │ [thinking] mode auto │
79
+ │ [tools] limit 40 rounds │
54
80
  │ [shell] stream on · bg auto · 0 active │
55
- │ [stream] heartbeat on · phases on │
56
- │ [summary] phases on · trigger 65% │
57
- │ [agents] 3 · [skills] 2 │
81
+ │ [stream] heartbeat on · phases on │
82
+ │ [summary] phases on · trigger 65% │
83
+ │ [voice] whisper-cli · archive on │
84
+ │ [agents] 3 · [skills] 2 │
58
85
  └──────────────────────────────────────────────────────────────┘
59
86
 
60
87
  Previous session found in .sapper/context.json
61
88
  Resume session? [y/N]
62
89
  ```
63
90
 
64
- The dashboard shows workspace indexing state, memory configuration, active agents and skills count, shell mode, and context summarization trigger. If a previous session exists, Sapper offers to resume it.
65
-
66
- ---
67
-
68
- ### Model Selection — Interactive Picker
69
-
70
- Before each session, Sapper reads the locally available Ollama models and presents an interactive picker. Models are listed with their disk footprint and last-used time.
91
+ ### Model Picker
71
92
 
72
93
  ```
73
94
  Model selection use ↑↓ or j/k, enter to confirm
@@ -82,21 +103,11 @@ Preview
82
103
  Selected gemma4:e4b-mlx-bf16
83
104
  Footprint 14.9 GB
84
105
  Updated 54m ago
85
- Profile safetensors
86
- Quant default
87
106
  ```
88
107
 
89
- Keyboard controls: `↑` `↓` or `j` / `k` to navigate, `Enter` to confirm. A live preview panel shows model metadata before committing.
90
-
91
- ---
92
-
93
- ### Active Session — Context Bar
94
-
95
- Once a model is selected the prompt loop begins. A persistent context bar at the bottom of each turn shows token consumption against the configured limit.
108
+ ### Live Session
96
109
 
97
110
  ```
98
- Session
99
-
100
111
  [model] gemma4:e4b-mlx-bf16
101
112
  [tools] native tool calling
102
113
  [context] 35,000 tokens (custom limit, model: 131,072)
@@ -106,83 +117,38 @@ Session
106
117
  >
107
118
  ```
108
119
 
109
- The bar updates after every turn. When usage approaches the configured `summarizeTriggerPercent` threshold, Sapper automatically compresses older turns into a summary and continues without interruption.
110
-
111
- ---
112
-
113
- ### .sapper/ Data Folder
114
-
115
- All persistent state is isolated inside `.sapper/` at the root of each project, keeping your workspace clean.
116
-
117
- ```
118
- .sapper/
119
- ├── config.json runtime configuration (hot-reload)
120
- ├── context.json conversation history for session resume
121
- ├── embeddings.json semantic vector memory, cosine similarity recall
122
- ├── workspace.json file index and dependency graph
123
- ├── agents/ custom agent definitions (.md + YAML frontmatter)
124
- ├── skills/ reusable instruction blocks (.md + YAML frontmatter)
125
- └── logs/ per-session activity audit logs (.md)
126
- ```
120
+ The context bar updates after every turn. When usage approaches the `summarizeTriggerPercent` threshold, Sapper compresses older turns into a summary and continues — no interruption.
127
121
 
128
122
  ---
129
123
 
130
124
  ## Architecture
131
125
 
132
126
  ```
133
- ┌─────────────────────────────────────────────────────────────┐
134
- │ SAPPER CLI │
135
- │ │
136
- │ User Input ──► Prompt Builder ──► Ollama API │
137
- │ │ │ │
138
- │ Context / Memory Streaming │
139
- │ Embeddings Response │
140
- │ Agent / Skills │ │
141
- │ │ ▼ │
142
- │ Tool Parser ◄──── AI Response │
143
- │ │ │
144
- │ ┌───────────────┼───────────────────┐ │
145
- │ ▼ ▼ ▼ │
146
- │ File System Shell Git / Web │
147
- │ READ WRITE PATCH SHELL SHELL(bg) COMMIT PUSH FETCH │
148
- └─────────────────────────────────────────────────────────────┘
127
+ ┌────────────────────────────────────────────────────────────────┐
128
+ │ SAPPER CLI │
129
+ │ │
130
+ │ User Input ──► Prompt Builder ──► Ollama (local) │
131
+ │ ▲ │ │ │
132
+ │ │ Context / Memory Streaming │
133
+ │ │ Embeddings Response │
134
+ │ │ Agent / Skills │ │
135
+ │ │ │ ▼ │
136
+ │ └──── Tool Parser ◄──── AI Response (native or text) │
137
+ │ │ │
138
+ │ ┌─────────┼──────────┬──────────┬────────────┐ │
139
+ │ ▼ ▼ ▼ ▼ ▼ │
140
+ │ File System Shell Git / Web Voice AST / Memory │
141
+ │ READ WRITE SHELL PUSH FETCH WHISPER SYMBOL RECALL │
142
+ └────────────────────────────────────────────────────────────────┘
149
143
  ```
150
144
 
151
- ```
152
- .sapper/
153
- ├── config.json ← Runtime configuration
154
- ├── context.json ← Conversation history
155
- ├── embeddings.json ← Vector memory store
156
- ├── workspace.json ← Project dependency graph
157
- ├── agents/ ← Custom agent definitions (.md)
158
- ├── skills/ ← Reusable skill definitions (.md)
159
- └── logs/ ← Per-session activity logs (.md)
160
- ```
161
-
162
- ---
163
-
164
- ## Features
165
-
166
- | Area | Capability |
167
- |---|---|
168
- | AI Integration | Connects to any local Ollama model; model picker on startup |
169
- | Tool Execution | 28 built-in tools covering files, shell, git, and web |
170
- | Context Management | Auto-summarization when context window approaches limit |
171
- | Session Memory | Embedding-based semantic memory with cosine similarity recall |
172
- | Agents & Skills | Custom `.md` agent files with YAML frontmatter and tool restrictions |
173
- | Background Shell | Long-running commands hand off to tracked background sessions |
174
- | Approval Gate | Prompted approval with inline feedback for shell and write operations |
175
- | Activity Logging | Every tool call and AI turn is logged to `.sapper/logs/` |
176
- | AST Parsing | Symbol extraction (functions, classes) with `/symbol` search |
177
- | Streaming | Live token-by-token output with heartbeat and phase status |
178
-
179
145
  ---
180
146
 
181
147
  ## Prerequisites
182
148
 
183
- - [Node.js](https://nodejs.org) >= 16.0.0
184
- - [Ollama](https://ollama.ai) installed and running locally
185
- - At least one model pulled, for example:
149
+ - **[Node.js](https://nodejs.org)** ≥ 16.0.0
150
+ - **[Ollama](https://ollama.ai)** installed and running locally with at least one model
151
+ - *(optional, for voice)* **[whisper.cpp](https://github.com/ggerganov/whisper.cpp)** and **ffmpeg** — see [Voice / Whisper](#voice--whisper)
186
152
 
187
153
  ```bash
188
154
  ollama pull llama3
@@ -196,26 +162,39 @@ ollama pull llama3
196
162
  npm install -g sapper-iq
197
163
  ```
198
164
 
165
+ Or run it without installing:
166
+
167
+ ```bash
168
+ npx sapper-iq
169
+ ```
170
+
199
171
  ---
200
172
 
201
173
  ## Quick Start
202
174
 
203
175
  ```bash
176
+ cd /path/to/your/project
204
177
  sapper
205
178
  ```
206
179
 
207
- Sapper will prompt you to select a model, then you can start conversing immediately.
180
+ Pick a model, then start talking:
208
181
 
209
182
  ```
210
- Model: llama3
211
- Working directory: /your/project
212
-
213
- > analyze this project and list what it does
183
+ > analyze this project and tell me what it does
214
184
  > add a REST endpoint for user authentication
215
185
  > run the tests and fix any failures
216
186
  > commit the changes with a descriptive message
217
187
  ```
218
188
 
189
+ Or use your voice:
190
+
191
+ ```
192
+ > /v lang en
193
+ > /v live
194
+ 🔴 Live preview — press any key to stop.
195
+ > [you speak] → transcript is sent to the AI
196
+ ```
197
+
219
198
  ---
220
199
 
221
200
  ## How It Works
@@ -260,29 +239,64 @@ User prompt
260
239
 
261
240
  ## Commands
262
241
 
263
- Run these inside Sapper at the prompt:
242
+ Run these inside Sapper at the prompt. Press `Tab` for slash-command autocomplete.
243
+
244
+ ### Session
264
245
 
265
246
  | Command | Description |
266
247
  |---|---|
267
- | `/help` | Show all available commands |
268
- | `/reset` | Start a new conversation session |
269
- | `/clear-session` | Alias for `/reset` |
248
+ | `/help`, `/commands` | Show the full command palette |
249
+ | `/reset`, `/clear-session` | Start a new conversation session |
270
250
  | `/session-info` | Display current session metadata |
271
- | `/summary` | View or change auto-summarization settings |
272
- | `/summary phases off` | Hide summarization step list |
273
- | `/summary trigger 60` | Set summarization trigger to 60 % of context |
274
- | `/shell` | Inspect shell config and list tracked background sessions |
275
- | `/shell read <id>` | Read buffered output from a background session |
276
- | `/shell stop <id>` | Stop a tracked background shell session |
277
- | `/step` | Toggle step-by-step tool approval mode |
278
- | `/tools` | Browse the built-in tool catalog |
279
- | `/git` | Inspect repository state and git shortcuts |
280
- | `/symbol <name>` | Search for a code symbol via AST index |
281
- | `/recall <query>` | Search semantic memory for past context |
282
251
  | `/log` | View the current session activity log |
283
252
  | `/attach <file>` | Attach a file to the next prompt |
253
+ | `//text` | Send literal text that starts with `/` |
284
254
  | `exit` | Exit Sapper |
285
255
 
256
+ ### Model & Tools
257
+
258
+ | Command | Description |
259
+ |---|---|
260
+ | `/model` | Switch the active Ollama model mid-session |
261
+ | `/tools` | Browse the built-in tool catalog |
262
+ | `/step` | Toggle step-by-step tool approval mode |
263
+ | `/symbol <name>` | Search for a code symbol via the AST index |
264
+
265
+ ### Memory
266
+
267
+ | Command | Description |
268
+ |---|---|
269
+ | `/recall <query>` | Search semantic embeddings for past context |
270
+ | `/memory` | Inspect markdown long-memory notes |
271
+ | `/memory add <title> ::: <note> ::: <tags>` | Save a durable project note |
272
+ | `/memory search <query>` | Search markdown long-memory notes |
273
+
274
+ ### Voice
275
+
276
+ | Command | Description |
277
+ |---|---|
278
+ | `/v`, `/voice` | Show voice status and settings |
279
+ | `/v live`, `/v stream` | Live preview while you speak, clean final transcript on stop |
280
+ | `/v record [seconds]` | Record from mic (push-to-stop, or fixed duration) |
281
+ | `/v talk` | Alias for push-to-stop recording |
282
+ | `/v file <path>` | Transcribe an existing audio file |
283
+ | `/v model` | Interactive picker — list available Whisper models |
284
+ | `/v lang <code>` | Lock language (e.g. `en`, `ar`, `auto`) |
285
+ | `/v archive on\|off\|open` | Toggle or reveal the recordings archive |
286
+
287
+ ### Shell, UI & Summary
288
+
289
+ | Command | Description |
290
+ |---|---|
291
+ | `/shell` | Inspect shell config and tracked background sessions |
292
+ | `/shell read <id>` | Read buffered output from a background session |
293
+ | `/shell stop <id>` | Stop a tracked background shell session |
294
+ | `/git` | Inspect repository state and git shortcuts |
295
+ | `/summary` | View or change auto-summarization settings |
296
+ | `/summary trigger 60` | Set summarization trigger to 60 % of context |
297
+ | `/ui style sapper\|clean\|ultra` | Switch the frontend style |
298
+ | `/ui compact auto\|on\|off` | Responsive compact rendering |
299
+
286
300
  ---
287
301
 
288
302
  ## Tool Catalog
@@ -341,7 +355,56 @@ Run these inside Sapper at the prompt:
341
355
 
342
356
  ---
343
357
 
344
- ## Agents and Skills
358
+ ## Voice / Whisper
359
+
360
+ Sapper can transcribe your voice using local [whisper.cpp](https://github.com/ggerganov/whisper.cpp). Nothing is sent to the cloud — audio and transcripts stay on your machine.
361
+
362
+ ### Setup (macOS)
363
+
364
+ ```bash
365
+ brew install whisper-cpp ffmpeg
366
+ mkdir -p ~/models
367
+ curl -L -o ~/models/ggml-large-v3-turbo.bin \
368
+ https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin
369
+ ```
370
+
371
+ Then in Sapper:
372
+
373
+ ```
374
+ /v model # pick from auto-detected models
375
+ /v lang ar # lock language for best quality (or 'en', 'auto', etc.)
376
+ /v live # press any key to stop, transcript goes to AI
377
+ ```
378
+
379
+ ### Modes
380
+
381
+ | Mode | What it does |
382
+ |---|---|
383
+ | `/v live` | Streams a live preview as you speak, then runs one clean pass on the full WAV for the final transcript |
384
+ | `/v record` | Push-to-stop recording with live ticker |
385
+ | `/v record 8` | Fixed N-second capture |
386
+ | `/v file <path>` | Transcribe an existing audio file |
387
+
388
+ ### Archive
389
+
390
+ Every recording is saved (when archive is on) to:
391
+
392
+ ```
393
+ <project>/.sapper/voice/YYYY-MM-DD/HHMMSS-<mode>.{wav,txt}
394
+ ```
395
+
396
+ Use `/v archive open` to reveal it in Finder, `/v archive off` to disable.
397
+
398
+ ### Quality tips
399
+
400
+ - **Lock the language** with `/v lang <code>` — `auto` works but per-chunk detection can bleed between languages
401
+ - Use **`ggml-large-v3-turbo`** for the best speed/quality trade-off (~1.5 GB)
402
+ - `large-v3` is slower but slightly more accurate (~2.9 GB)
403
+ - Sapper auto-strips common silence hallucinations (`[BLANK_AUDIO]`, `"you"`, `"Thank you."`, subtitle credits, etc.)
404
+
405
+ ---
406
+
407
+ ## Agents & Skills
345
408
 
346
409
  Sapper supports custom agents and reusable skills defined as Markdown files with YAML frontmatter, stored in `.sapper/agents/` and `.sapper/skills/`.
347
410
 
@@ -373,7 +436,7 @@ Skills follow the same format and are injected into the system prompt as reusabl
373
436
 
374
437
  ## Configuration
375
438
 
376
- Sapper writes `.sapper/config.json` on first run. All fields are optional; missing values use the defaults shown below.
439
+ Sapper writes `.sapper/config.json` on first run. The file supports JSON-style comments (`//` and `/* ... */`). All fields are optional; missing values use the defaults shown below.
377
440
 
378
441
  ```json
379
442
  {
@@ -396,10 +459,30 @@ Sapper writes `.sapper/config.json` on first run. All fields are optional; missi
396
459
  "showHeartbeat": true,
397
460
  "idleNoticeSeconds": 4
398
461
  },
462
+ "ui": {
463
+ "compactMode": "auto",
464
+ "style": "sapper"
465
+ },
399
466
  "prompt": {
400
467
  "prepend": "",
401
468
  "append": "",
402
- "coreOverride": ""
469
+ "coreOverride": "",
470
+ "system": {
471
+ "core": "...",
472
+ "nativeTools": "...",
473
+ "legacyTools": "...",
474
+ "importantContext": "..."
475
+ },
476
+ "ui": {
477
+ "bannerTitle": "Sapper",
478
+ "bannerSubtitle": "terminal coding workspace",
479
+ "bannerTagline": "Model selection, live tools, and focused sessions in one loop"
480
+ },
481
+ "questions": {
482
+ "resumeSession": "Resume session",
483
+ "agentName": "\\nAgent name (lowercase, no spaces): ",
484
+ "skillName": "\\nSkill name (lowercase, no spaces): "
485
+ }
403
486
  }
404
487
  }
405
488
  ```
@@ -419,33 +502,48 @@ Sapper writes `.sapper/config.json` on first run. All fields are optional; missi
419
502
  | `streaming.showPhaseStatus` | `true` | Show status lines during tool execution and model turns |
420
503
  | `streaming.showHeartbeat` | `true` | Update progress line during quiet streaming phases |
421
504
  | `streaming.idleNoticeSeconds` | `4` | Print an idle notice after N seconds of no visible output |
505
+ | `ui.compactMode` | `"auto"` | `auto` / `on` / `off` — compact layout for smaller terminals |
506
+ | `ui.style` | `"sapper"` | `sapper` / `clean` / `ultra` — default style, clean minimal, or ultra-clean single-line frontend |
422
507
  | `prompt.prepend` | `""` | Inject custom instructions before the default system prompt |
423
508
  | `prompt.append` | `""` | Inject custom instructions after the default system prompt |
424
509
  | `prompt.coreOverride` | `""` | Replace the core prompt block entirely (tool and context sections are preserved) |
510
+ | `prompt.system.*` | built-in text | Full system prompt sections, including core behavior, tool instructions, agent wrapper, and skill wrapper |
511
+ | `prompt.ui.*` | built-in text | Startup banner, model picker labels, unknown-command title, and other UI labels |
512
+ | `prompt.questions.*` | built-in text | Interactive confirmations and questions shown during approval, attach, agent creation, skill creation, and step mode |
425
513
 
426
- Configuration is hot-reloaded — edit the file while Sapper is running and changes take effect on the next prompt turn.
514
+ Configuration is hot-reloaded — edit the file while Sapper is running and changes take effect on the next prompt turn. Prompt text is now managed from config, so you can inspect and customize the major system, UI, and question prompts directly in `.sapper/config.json`. Sapper preserves and regenerates built-in explanatory comments when it rewrites the file.
427
515
 
428
516
  ---
429
517
 
430
518
  ## Session Memory
431
519
 
432
- Sapper maintains two layers of memory per project:
520
+ Sapper maintains three layers of memory per project — all stored locally under `.sapper/`:
521
+
522
+ | Layer | File | Purpose |
523
+ |---|---|---|
524
+ | **Short-term** | `.sapper/context.json` | Full conversation history; auto-summarized as the context window fills |
525
+ | **Semantic** | `.sapper/embeddings.json` | Chunked text with cosine-similarity recall; auto-surfaced on relevant prompts. Search with `/recall <query>` |
526
+ | **Durable** | `.sapper/long-memory.md` | Markdown project patterns, decisions, fixes. Managed with `/memory add` / `/memory search` |
527
+
528
+ Every tool call and AI turn is also logged to `.sapper/logs/session-<timestamp>.md` for auditing.
529
+
530
+ ---
531
+
532
+ ## Project Layout
433
533
 
434
534
  ```
435
- ┌─────────────────────────────────────────────────────┐
436
- │ Short-term → .sapper/context.json │
437
- │ Full conversation history for the current session │
438
- │ Auto-summarized as the context window fills up │
439
- ├─────────────────────────────────────────────────────┤
440
- │ Long-term → .sapper/embeddings.json │
441
- │ Chunked text embedded with cosine similarity │
442
- │ Recalled automatically on relevant prompts │
443
- │ Searchable manually with /recall <query> │
444
- └─────────────────────────────────────────────────────┘
535
+ .sapper/
536
+ ├── config.json runtime configuration (hot-reload, JSONC)
537
+ ├── context.json conversation history for session resume
538
+ ├── embeddings.json semantic vector memory
539
+ ├── workspace.json file index and dependency graph
540
+ ├── long-memory.md durable project notes
541
+ ├── voice/ audio + transcript archive (YYYY-MM-DD/)
542
+ ├── agents/ custom agents (.md + YAML frontmatter)
543
+ ├── skills/ reusable skill blocks (.md + YAML frontmatter)
544
+ └── logs/ per-session activity audit logs
445
545
  ```
446
546
 
447
- All activity is also written to `.sapper/logs/session-<timestamp>.md` for auditing.
448
-
449
547
  ---
450
548
 
451
549
  ## Development
@@ -458,16 +556,24 @@ chmod +x sapper.mjs
458
556
  node sapper.mjs
459
557
  ```
460
558
 
461
- CI runs automatically on push to `main` across Node.js 16, 18, and 20.
559
+ CI runs on push to `main` across Node.js 16, 18, and 20.
560
+
561
+ ### Releasing
562
+
563
+ See [PUBLISHING.md](PUBLISHING.md) for the full npm release flow.
462
564
 
463
565
  ---
464
566
 
465
567
  ## License
466
568
 
467
- MIT — see [LICENSE](LICENSE)
569
+ MIT — see [LICENSE](LICENSE).
468
570
 
469
571
  ---
470
572
 
471
- **Author:** Ibrahim Ihsan
472
- **Package:** [sapper-iq on npm](https://www.npmjs.com/package/sapper-iq)
473
- **Repository:** [github.com/aledanee/sapper](https://github.com/aledanee/sapper)
573
+ <div align="center">
574
+
575
+ **Built by [Ibrahim Ihsan](https://github.com/aledanee)** · [npm](https://www.npmjs.com/package/sapper-iq) · [GitHub](https://github.com/aledanee/sapper) · [Issues](https://github.com/aledanee/sapper/issues)
576
+
577
+ <sub>If Sapper saves you time, a ⭐ on GitHub means a lot.</sub>
578
+
579
+ </div>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sapper-iq",
3
- "version": "1.1.39",
3
+ "version": "1.2.0",
4
4
  "description": "AI-powered development assistant that executes commands and builds projects",
5
5
  "main": "sapper.mjs",
6
6
  "bin": {
@@ -14,7 +14,9 @@
14
14
  ],
15
15
  "type": "module",
16
16
  "scripts": {
17
- "start": "node sapper.mjs"
17
+ "start": "node sapper.mjs",
18
+ "ui": "node sapper-ui.mjs",
19
+ "postinstall": "node -e \"try{require('fs').chmodSync(require('path').join(require.resolve('node-pty/package.json'),'..','prebuilds','darwin-arm64','spawn-helper'),0o755)}catch(e){};try{require('fs').chmodSync(require('path').join(require.resolve('node-pty/package.json'),'..','prebuilds','darwin-x64','spawn-helper'),0o755)}catch(e){}\""
18
20
  },
19
21
  "dependencies": {
20
22
  "acorn": "^8.15.0",
@@ -22,8 +24,10 @@
22
24
  "cli-highlight": "^2.1.11",
23
25
  "marked": "^15.0.12",
24
26
  "marked-terminal": "^7.3.0",
27
+ "node-pty": "^1.1.0",
25
28
  "ollama": "^0.5.0",
26
- "ora": "^8.0.1"
29
+ "ora": "^8.0.1",
30
+ "ws": "^8.21.0"
27
31
  },
28
32
  "engines": {
29
33
  "node": ">=16.0.0"