askii-cli 0.3.0 → 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.
Files changed (3) hide show
  1. package/README.md +230 -64
  2. package/dist/index.js +561 -355
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # ASKII CLI ( •\_•)>⌐■-■ (⌐■_■)
2
2
 
3
- AI code assistant for your terminal. Powered by Ollama, LM Studio, OpenAI, Anthropic, or opencode Go.
3
+ AI code assistant for your terminal. Powered by Ollama, LM Studio, OpenAI, Anthropic, opencode Go, or ASKII Cloud.
4
4
 
5
5
  ## Install
6
6
 
@@ -14,6 +14,79 @@ Or run without installing:
14
14
  npx askii-cli <command>
15
15
  ```
16
16
 
17
+ ## Interactive Mode
18
+
19
+ Run `askii` with no arguments to start an interactive REPL session:
20
+
21
+ ```bash
22
+ askii
23
+ askii --platform anthropic # start with a specific platform
24
+ ```
25
+
26
+ ```
27
+ ASKII ( •_•)>⌐■-■ (⌐■_■) — interactive mode
28
+
29
+ Platform : ollama (gemma4:e4b)
30
+ Workspace: /your/project
31
+ Wiki : off
32
+
33
+ Type a message to chat, /help for commands, /exit to quit.
34
+
35
+ > what does a closure do in JavaScript?
36
+
37
+ ASKII: A closure is a function that retains access to variables
38
+ from its enclosing scope even after that scope has finished...
39
+
40
+ > can you give me an example?
41
+
42
+ ASKII: Sure! Here's a classic counter example...
43
+
44
+ > /platform anthropic
45
+ Platform → anthropic (claude-sonnet-4-6)
46
+
47
+ > /do add a .gitignore for a Node.js project
48
+ [Round 1/5]
49
+ ...
50
+
51
+ > /exit
52
+ Bye! ( •_•)>⌐■-■ (⌐■_■)
53
+ ```
54
+
55
+ Bare text input maintains a **persistent chat history** across turns — follow-up questions remember the full conversation. Use `/clear` to start fresh.
56
+
57
+ ### REPL slash-commands
58
+
59
+ | Command | Description |
60
+ | ----------------------------- | ---------------------------------------------------------------------------- |
61
+ | `/help` | Show all available commands |
62
+ | `/ask <question>` | Explicit ask (same as bare text) |
63
+ | `/do <task> [flags]` | Run the Do agent (`--max-rounds N`, `--yes`) |
64
+ | `/generate <type> <base>` | Generate a file (`test` / `doc` / `json`) — agentic, can search & ask |
65
+ | `/commit` | Generate a commit message from staged/working-tree diff |
66
+ | `/note <subcommand>` | Notes / tasks / reminders (`add`, `list`, `search`, `done`, `delete`, `due`) |
67
+ | `/edit --file <path> <instr>` | Edit a file in place |
68
+ | `/explain <text>` | Explain a line of code |
69
+ | `/wiki-reload` | Rebuild the docs wiki index |
70
+ | `/platform <name>` | Switch platform for the session (also updates default model) |
71
+ | `/model <name>` | Switch model for the session |
72
+ | `/config` | Show current session config (keys redacted) |
73
+ | `/clear` | Clear chat history and start a fresh conversation |
74
+ | `/exit`, `/quit` | Exit interactive mode |
75
+
76
+ Tab-complete any `/` command by pressing Tab. Up/down arrows cycle through input history.
77
+
78
+ **Config overrides** — bare `--` flags at the prompt update session config without restarting:
79
+
80
+ ```
81
+ > --platform openai --model gpt-4-turbo
82
+ > --max-rounds 10
83
+ > --mode helpful
84
+ ```
85
+
86
+ Ctrl+C during `/do` or `/control` cancels only that agent and returns to the `>` prompt. Ctrl+C at the idle prompt exits.
87
+
88
+ ---
89
+
17
90
  ## Commands
18
91
 
19
92
  ### `ask` — Ask a question about code
@@ -100,23 +173,64 @@ askii do --dir .\my-project "refactor index.ts"
100
173
 
101
174
  The agent can use the following actions each round:
102
175
 
103
- | Action | Description | Requires confirmation |
104
- | ------------- | ---------------------------------------------------------------- | --------------------- |
105
- | `list` | List files in a folder (`[file]` / `[folder]` labels) | No |
106
- | `view` | Read a file's contents | No |
107
- | `search` | Grep workspace files for a pattern | No |
108
- | `wiki_search` | BM25 search over indexed `.md` docs (requires `--use-wiki`) | No |
109
- | `code_search` | BM25 search over indexed code files (requires `--use-code-wiki`) | No |
110
- | `create` | Create a new file | Yes |
111
- | `modify` | Replace text in an existing file | Yes |
112
- | `rename` | Rename or move a file | Yes |
113
- | `delete` | Delete a file | Yes |
114
- | `run` | Run a shell command | Yes (always) |
176
+ | Action | Description | Requires confirmation |
177
+ | ------------- | ----------------------------------------------------------- | --------------------- |
178
+ | `list` | List files in a folder (`[file]` / `[folder]` labels) | No |
179
+ | `view` | Read a file's contents | No |
180
+ | `search` | Grep workspace files for a pattern | No |
181
+ | `wiki_search` | BM25 search over indexed `.md` docs (requires `--use-wiki`) | No |
182
+ | `create` | Create a new file | Yes |
183
+ | `modify` | Replace text in an existing file | Yes |
184
+ | `rename` | Rename or move a file | Yes |
185
+ | `delete` | Delete a file | Yes |
186
+ | `run` | Run a shell command | Yes (always) |
115
187
 
116
188
  The loop continues after every round — not only after reads — until the AI returns `[]` or the round limit is hit.
117
189
 
118
190
  ---
119
191
 
192
+ ### `generate` — Agentic file generator
193
+
194
+ Picks a file type (Test / Doc / Json) and a base name, then runs a Do-style loop that searches the workspace, asks clarifying questions when needed, and creates the generated file. The agent decides the full path and extension based on workspace conventions.
195
+
196
+ **bash**
197
+
198
+ ```bash
199
+ askii generate test utils --file src/utils.ts --instruction "use Jest"
200
+ askii generate doc api --dir ./my-project
201
+ askii generate json schema --file package.json
202
+ askii generate test utils --yes # auto-confirm (no clarifications prompted)
203
+ ```
204
+
205
+ **PowerShell**
206
+
207
+ ```powershell
208
+ askii generate test utils --file src/utils.ts --instruction "use Jest"
209
+ askii generate doc api --dir .\my-project
210
+ askii generate json schema --file package.json
211
+ askii generate test utils --yes
212
+ ```
213
+
214
+ Each round the agent can use:
215
+
216
+ | Action | Description | Prompts you? |
217
+ | ------------- | --------------------------------------------------------------------- | ------------ |
218
+ | `list` | List files in a folder (`[file]` / `[folder]` labels) | No |
219
+ | `view` | Read a file's contents | No |
220
+ | `search` | Grep workspace files for a pattern | No |
221
+ | `wiki_search` | BM25 search over indexed `.md` docs (requires `--use-wiki`) | No |
222
+ | `clarify` | Ask you a clarifying question (type your answer at the prompt) | Yes |
223
+ | `create` | Create the generated file (written directly; Undo offered at the end) | No |
224
+
225
+ Optional flags:
226
+
227
+ - `--file <path>` — read this file as context (acts as the "current tab")
228
+ - `--instruction <text>` — extra instructions for the generator
229
+ - `--dir <path>` — working directory (default: cwd)
230
+ - `--yes` — auto-confirm (skips clarification prompts)
231
+
232
+ ---
233
+
120
234
  ### `control` — Screen control agent
121
235
 
122
236
  Takes a screenshot, sends it to the AI, and executes the returned mouse/keyboard action. Repeats until the AI returns `DONE` or `--max-rounds` is reached. Requires a **vision-capable model** (e.g. `llava`, `moondream2`).
@@ -191,44 +305,74 @@ askii do --wiki-path .\docs --use-wiki "implement the auth flow described in the
191
305
 
192
306
  ---
193
307
 
194
- ### `code-wiki-reload` — Index workspace code files
195
-
196
- Walks all supported code files in a directory (TypeScript, Python, Go, Rust, C/C++, and more), splits them into 60-line overlapping chunks, builds a [MiniSearch](https://github.com/lucaong/minisearch) BM25 index, and saves it as `.askii-code-wiki-index.json` in the target directory. Run this once against your codebase and again whenever the code changes significantly.
308
+ ### `commit` — Generate a commit message
197
309
 
198
- Skips: `node_modules`, `dist`, `out`, `build`, `target`, `bin`, `obj`, `coverage`, `__pycache__`, `venv`, and files over 200 KB.
310
+ Reads the staged diff (or, if nothing is staged, the working-tree diff) plus the list of changed files, asks the LLM to write a well-formed Git commit message, and prints it to **stdout**. Pipe-friendly — use it with `git commit`:
199
311
 
200
312
  **bash**
201
313
 
202
314
  ```bash
203
- askii code-wiki-reload # indexes current directory
204
- askii code-wiki-reload --code-wiki-path ./src # indexes a specific directory
315
+ git commit -m "$(askii commit)"
316
+ askii commit --dir ./my-project
205
317
  ```
206
318
 
207
319
  **PowerShell**
208
320
 
209
321
  ```powershell
210
- askii code-wiki-reload
211
- askii code-wiki-reload --code-wiki-path .\src
322
+ git commit -m "$(askii commit)"
323
+ askii commit --dir ..\my-project
212
324
  ```
213
325
 
214
- After indexing, pass `--code-wiki-path` and `--use-code-wiki` to any `ask`, `edit`, or `do` command to inject the top matching code chunks as context:
326
+ The diff is capped at 12,000 characters to keep context tight. The output is cleaned of markdown fences, quotes, and `Commit message:` labels, so it's ready to pass straight to `git commit -m`.
327
+
328
+ ---
329
+
330
+ ### `note` — Notes / tasks / reminders
331
+
332
+ Type free text and the AI auto-classifies it into a **note**, **task** (with `low` / `medium` / `high` priority), or **reminder** (with a due time). Entries are stored globally at `~/.askii/notes.json`, tagged by workspace, and full-text searchable everywhere.
215
333
 
216
334
  **bash**
217
335
 
218
336
  ```bash
219
- askii ask --use-code-wiki "where is the wiki index built?"
220
- askii ask --use-code-wiki "how does the debounce work in the inline completer?"
221
- cat src/commands.ts | askii edit --use-code-wiki "add code wiki context to the ask command"
222
- askii do --use-code-wiki "refactor the provider functions to share a common helper"
337
+ askii note add "the API rate limit is 100 req/min"
338
+ askii note add "task: fix the login bug, high priority"
339
+ askii note add "remind me to check the build in 30 minutes"
340
+ askii note add --shot "remember this screen state" # attach a full-screen screenshot
341
+ askii note list # list all entries (most-recent first)
342
+ askii note list "login" # filter by full-text query
343
+ askii note search "login" # full-text search
344
+ askii note done abc12345 # toggle a task's done state
345
+ askii note delete abc12345 # delete an entry
346
+ askii note due # list reminders that are due now
223
347
  ```
224
348
 
225
349
  **PowerShell**
226
350
 
227
351
  ```powershell
228
- askii ask --use-code-wiki "where is the wiki index built?"
229
- Get-Content src\commands.ts | askii edit --use-code-wiki "add code wiki context to the ask command"
230
- askii do --use-code-wiki "refactor the provider functions to share a common helper"
231
- ```
352
+ askii note add "the API rate limit is 100 req/min"
353
+ askii note add "task: fix the login bug, high priority"
354
+ askii note add "remind me to check the build in 30 minutes"
355
+ askii note add --shot "remember this screen state"
356
+ askii note list
357
+ askii note search "login"
358
+ askii note done abc12345
359
+ askii note delete abc12345
360
+ askii note due
361
+ ```
362
+
363
+ Subcommands:
364
+
365
+ | Subcommand | Description |
366
+ | --------------------- | -------------------------------------------------- |
367
+ | `add "<text>"` | Add a note / task / reminder (AI auto-classifies) |
368
+ | `add --shot "<text>"` | Attach a full-screen screenshot to the entry |
369
+ | `list [query]` | List all entries, or filter by full-text query |
370
+ | `search "<query>"` | Full-text search across all entries |
371
+ | `done <id>` | Toggle a task's done state |
372
+ | `delete <id>` | Delete an entry |
373
+ | `due` | List reminders that are due now (marks them fired) |
374
+
375
+ > **Reminders**: the CLI has no background scheduler, so reminders don't fire automatically. Run `askii note due` to see what's overdue — it prints the due entries and marks them fired. In the interactive REPL, `/note add` will ask a clarifying question if the reminder time is ambiguous.
232
376
 
233
377
  ---
234
378
 
@@ -278,32 +422,34 @@ Without `--yes`, each proposed action is shown with its reasoning and requires `
278
422
 
279
423
  ## Options
280
424
 
281
- | Flag | Short | Description | Default |
282
- | ------------------- | ----- | ---------------------------------------------------------------------------------- | ------------------------ |
283
- | `--platform` | `-p` | LLM platform: `ollama`, `lmstudio`, `openai`, `anthropic`, `opencodego` | `ollama` |
284
- | `--ollama-url` | | Ollama server URL | `http://localhost:11434` |
285
- | `--lmstudio-url` | | LM Studio server URL | `ws://localhost:1234` |
286
- | `--ollama-model` | | Ollama model | `gemma4:e4b` |
287
- | `--lmstudio-model` | | LM Studio model | `qwen/qwen3-coder-30b` |
288
- | `--openai-key` | | OpenAI API key (env: `ASKII_OPENAI_KEY`) | |
289
- | `--openai-model` | | OpenAI model | `gpt-5-mini` |
290
- | `--openai-url` | | OpenAI-compatible base URL (env: `ASKII_OPENAI_URL`) | |
291
- | `--anthropic-key` | | Anthropic API key (env: `ASKII_ANTHROPIC_KEY`) | |
292
- | `--anthropic-model` | | Anthropic model (env: `ASKII_ANTHROPIC_MODEL`) | `claude-sonnet-4-6` |
293
- | `--opencodego-key` | | opencode Go API key (env: `ASKII_OPENCODEGO_KEY`) | |
294
- | `--opencodego-model`| | opencode Go model (env: `ASKII_OPENCODEGO_MODEL`) | `glm-5.2` |
295
- | `--opencodego-url` | | opencode Go base URL (env: `ASKII_OPENCODEGO_URL`) | `https://opencode.ai/zen/go/v1` |
296
- | `--mode` | | Response style: `helpful`, `funny` | `funny` |
297
- | `--max-rounds` | | Max agent rounds for `do` / `control` / `browse` | `5` |
298
- | `--dir` | | Working directory for `do` | cwd |
299
- | `--code` | `-c` | Code input (alternative to stdin) | |
300
- | `--yes` | `-y` | Auto-confirm all actions | |
301
- | `--headless` | | Run Puppeteer headlessly for `browse` | `false` (visible) |
302
- | `--chrome-path` | | Path to Chrome/Chromium executable for `browse` | |
303
- | `--wiki-path` | | Path to folder with `.md` docs for wiki RAG (env: `ASKII_WIKI_PATH`) | |
304
- | `--use-wiki` | | Inject wiki context into `ask` / `edit` / `do` (env: `ASKII_USE_WIKI=1`) | |
305
- | `--code-wiki-path` | | Path to codebase root to index / search (env: `ASKII_CODE_WIKI_PATH`) | cwd |
306
- | `--use-code-wiki` | | Inject code wiki context into `ask` / `edit` / `do` (env: `ASKII_USE_CODE_WIKI=1`) | |
425
+ | Flag | Short | Description | Default |
426
+ | -------------------- | ----- | ------------------------------------------------------------------------------------- | ------------------------------- |
427
+ | `--platform` | `-p` | LLM platform: `ollama`, `lmstudio`, `openai`, `anthropic`, `opencodego`, `askiicloud` | `ollama` |
428
+ | `--ollama-url` | | Ollama server URL | `http://localhost:11434` |
429
+ | `--lmstudio-url` | | LM Studio server URL | `ws://localhost:1234` |
430
+ | `--ollama-model` | | Ollama model | `gemma4:e4b` |
431
+ | `--lmstudio-model` | | LM Studio model | `qwen/qwen3-coder-30b` |
432
+ | `--openai-key` | | OpenAI API key (env: `ASKII_OPENAI_KEY`) | |
433
+ | `--openai-model` | | OpenAI model | `gpt-5-mini` |
434
+ | `--openai-url` | | OpenAI-compatible base URL (env: `ASKII_OPENAI_URL`) | |
435
+ | `--anthropic-key` | | Anthropic API key (env: `ASKII_ANTHROPIC_KEY`) | |
436
+ | `--anthropic-model` | | Anthropic model (env: `ASKII_ANTHROPIC_MODEL`) | `claude-sonnet-4-6` |
437
+ | `--opencodego-key` | | opencode Go API key (env: `ASKII_OPENCODEGO_KEY`) | |
438
+ | `--opencodego-model` | | opencode Go model (env: `ASKII_OPENCODEGO_MODEL`) | `glm-5.2` |
439
+ | `--opencodego-url` | | opencode Go base URL (env: `ASKII_OPENCODEGO_URL`) | `https://opencode.ai/zen/go/v1` |
440
+ | `--askiicloud-key` | | ASKII Cloud API key (env: `ASKII_CLOUD_KEY`) | |
441
+ | `--askiicloud-model` | | ASKII Cloud model (env: `ASKII_CLOUD_MODEL`) | `askii-default` |
442
+ | `--mode` | | Response style: `helpful`, `funny` | `funny` |
443
+ | `--max-rounds` | | Max agent rounds for `do` / `generate` / `control` / `browse` | `5` |
444
+ | `--dir` | | Working directory for `do` / `generate` | cwd |
445
+ | `--code` | `-c` | Code input (alternative to stdin) | |
446
+ | `--file` | | Filename of the code (e.g. src/utils.ts) — also context file for `generate` | |
447
+ | `--instruction` | `-i` | Extra instruction for `generate` | |
448
+ | `--yes` | `-y` | Auto-confirm all actions | |
449
+ | `--headless` | | Run Puppeteer headlessly for `browse` | `false` (visible) |
450
+ | `--chrome-path` | | Path to Chrome/Chromium executable for `browse` | |
451
+ | `--wiki-path` | | Path to folder with `.md` docs for wiki RAG (env: `ASKII_WIKI_PATH`) | |
452
+ | `--use-wiki` | | Inject wiki context into `ask` / `edit` / `do` (env: `ASKII_USE_WIKI=1`) | |
307
453
 
308
454
  ## Environment Variables
309
455
 
@@ -334,6 +480,10 @@ export ASKII_OPENCODEGO_KEY=...
334
480
  export ASKII_OPENCODEGO_MODEL=glm-5.2
335
481
  export ASKII_OPENCODEGO_URL=https://opencode.ai/zen/go/v1
336
482
 
483
+ # ASKII Cloud
484
+ export ASKII_CLOUD_KEY=...
485
+ export ASKII_CLOUD_MODEL=askii-default
486
+
337
487
  # Shared
338
488
  export ASKII_MODE=funny
339
489
  export ASKII_MAX_ROUNDS=5
@@ -342,10 +492,6 @@ export ASKII_CHROME_PATH=/usr/bin/chromium
342
492
  # Docs wiki RAG
343
493
  export ASKII_WIKI_PATH=./docs
344
494
  export ASKII_USE_WIKI=1
345
-
346
- # Code wiki RAG
347
- export ASKII_CODE_WIKI_PATH=./src # defaults to cwd
348
- export ASKII_USE_CODE_WIKI=1
349
495
  ```
350
496
 
351
497
  **PowerShell**
@@ -375,6 +521,10 @@ $env:ASKII_OPENCODEGO_KEY = "..."
375
521
  $env:ASKII_OPENCODEGO_MODEL = "glm-5.2"
376
522
  $env:ASKII_OPENCODEGO_URL = "https://opencode.ai/zen/go/v1"
377
523
 
524
+ # ASKII Cloud
525
+ $env:ASKII_CLOUD_KEY = "..."
526
+ $env:ASKII_CLOUD_MODEL = "askii-default"
527
+
378
528
  # Shared
379
529
  $env:ASKII_MODE = "funny"
380
530
  $env:ASKII_MAX_ROUNDS = "5"
@@ -383,10 +533,6 @@ $env:ASKII_CHROME_PATH = "C:\Program Files\Google\Chrome\Application\chrome.exe"
383
533
  # Docs wiki RAG
384
534
  $env:ASKII_WIKI_PATH = ".\docs"
385
535
  $env:ASKII_USE_WIKI = "1"
386
-
387
- # Code wiki RAG
388
- $env:ASKII_CODE_WIKI_PATH = ".\src" # defaults to cwd
389
- $env:ASKII_USE_CODE_WIKI = "1"
390
536
  ```
391
537
 
392
538
  ## Platforms
@@ -482,3 +628,23 @@ askii -p opencodego --opencodego-key ... ask "what does this do?"
482
628
  askii -p opencodego --opencodego-key ... --opencodego-model kimi-k2.7-code do "add error handling"
483
629
  askii -p opencodego --opencodego-key ... --opencodego-model qwen3.7-max explain "arr.reduce((a, b) => a + b, 0)"
484
630
  ```
631
+
632
+ ### ASKII Cloud
633
+
634
+ An in-house, OpenAI-compatible inference service ([api.askii.dev](https://api.askii.dev)). All it needs is an API key — the base URL is fixed to `https://api.askii.dev/v1`.
635
+
636
+ **bash**
637
+
638
+ ```bash
639
+ askii -p askiicloud --askiicloud-key ... ask "what does this do?"
640
+ askii -p askiicloud --askiicloud-key ... --askiicloud-model askii-default do "add error handling"
641
+ askii -p askiicloud --askiicloud-key ... explain "arr.reduce((a, b) => a + b, 0)"
642
+ ```
643
+
644
+ **PowerShell**
645
+
646
+ ```powershell
647
+ askii -p askiicloud --askiicloud-key ... ask "what does this do?"
648
+ askii -p askiicloud --askiicloud-key ... --askiicloud-model askii-default do "add error handling"
649
+ askii -p askiicloud --askiicloud-key ... explain "arr.reduce((a, b) => a + b, 0)"
650
+ ```