kovence-cli 1.0.0 → 1.0.1

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 (2) hide show
  1. package/README.md +330 -45
  2. package/package.json +9 -2
package/README.md CHANGED
@@ -1,34 +1,130 @@
1
1
  # Kovence CLI
2
2
 
3
- Zero-dependency multi-step AI coding-agent CLI for Node.js (`>= 20.12.0`).
3
+ > **Zero-dependency, multi-step AI coding-agent CLI for Node.js ≥ 20.12**
4
+
5
+ [![npm version](https://img.shields.io/npm/v/kovence-cli.svg)](https://www.npmjs.com/package/kovence-cli)
6
+ [![npm downloads](https://img.shields.io/npm/dm/kovence-cli.svg)](https://www.npmjs.com/package/kovence-cli)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8
+ [![Node ≥ 20.12](https://img.shields.io/badge/node-%3E%3D20.12-brightgreen)](https://nodejs.org)
9
+
10
+ Kovence CLI is a powerful, **fully autonomous** AI coding-agent that runs entirely in your terminal. It supports any OpenAI-compatible or Anthropic endpoint, has zero runtime npm dependencies, and ships with a full-screen TUI, session management, background tasks, file checkpoints, and undo.
11
+
12
+ **Homepage:** <https://kovence-cli.kovence.com>
13
+
14
+ ---
15
+
16
+ ## Table of Contents
17
+
18
+ - [Installation](#installation)
19
+ - [Quick Start](#quick-start)
20
+ - [Provider Setup](#provider-setup)
21
+ - [Agent Modes](#agent-modes)
22
+ - [CLI Flags](#cli-flags)
23
+ - [Slash Commands](#slash-commands)
24
+ - [Keyboard Shortcuts](#keyboard-shortcuts)
25
+ - [File Mentions (@file)](#file-mentions-file)
26
+ - [Background Tasks](#background-tasks)
27
+ - [Session Management](#session-management)
28
+ - [Settings Reference](#settings-reference)
29
+ - [Environment Diagnostics](#environment-diagnostics)
30
+ - [License](#license)
31
+
32
+ ---
4
33
 
5
34
  ## Installation
6
35
 
36
+ ### Global install (recommended)
37
+
7
38
  ```bash
8
39
  npm install -g kovence-cli
9
40
  ```
10
41
 
11
- Or run directly from the repository:
42
+ After install, the `kovence` command is available system-wide:
43
+
44
+ ```bash
45
+ kovence # Launch interactive TUI
46
+ kovence --help # Show help
47
+ kovence doctor # Run diagnostics
48
+ ```
49
+
50
+ ### Try without installing
51
+
52
+ ```bash
53
+ npx kovence-cli@latest
54
+ ```
55
+
56
+ ### From source
12
57
 
13
58
  ```bash
14
- node nd.js --help
59
+ git clone https://github.com/kovence/kovence-cli.git
60
+ cd kovence-cli
61
+ npm install -g .
15
62
  ```
16
63
 
64
+ ---
65
+
17
66
  ## Quick Start
18
67
 
19
- 1. Launch interactive TUI:
68
+ 1. **Launch the TUI:**
20
69
  ```bash
21
70
  kovence
22
71
  ```
23
- 2. Add your AI provider and models inside the CLI using `/api add` (or `/models` -> `+ Add Custom Provider`).
24
- - Supports **OpenAI-compatible** and **Anthropic** endpoints.
25
- - For better secret hygiene, use `apiKeyEnv` (e.g. `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`) so the raw key is resolved from your environment instead of written to `~/.config/kovence/providers.json`.
26
- 3. Run diagnostics anytime:
27
- ```bash
28
- kovence doctor
72
+
73
+ 2. **Add an AI provider** — on first launch there is no default provider. Add one with:
29
74
  ```
75
+ /api add
76
+ ```
77
+ Or open **Models → + Add Custom Provider** inside the TUI.
78
+
79
+ 3. **Start chatting** — type your message and press `Enter`. The agent will plan, call tools, and iterate autonomously.
80
+
81
+ 4. **Switch modes** with `Shift+Tab` or `/mode`:
82
+ - `plan` → read-only research
83
+ - `auto` → fully autonomous, no approval prompts
84
+
85
+ ---
86
+
87
+ ## Provider Setup
88
+
89
+ Kovence supports any **OpenAI-compatible** endpoint and **Anthropic** natively.
90
+
91
+ ### Interactive wizard
92
+
93
+ ```
94
+ /api add
95
+ ```
96
+
97
+ This opens a step-by-step wizard to enter your base URL, API key, and models. Providers are saved to `~/.config/kovence/providers.json`.
30
98
 
31
- ## Permission Modes
99
+ ### Secret hygiene with `apiKeyEnv`
100
+
101
+ Instead of storing your raw API key on disk, you can point to an environment variable:
102
+
103
+ ```json
104
+ {
105
+ "name": "openai",
106
+ "type": "openai",
107
+ "baseURL": "https://api.openai.com/v1",
108
+ "apiKeyEnv": "OPENAI_API_KEY"
109
+ }
110
+ ```
111
+
112
+ Kovence will read the key from your shell environment at runtime — it is never written to the config file.
113
+
114
+ ### Popular endpoints
115
+
116
+ | Provider | Base URL |
117
+ |---|---|
118
+ | OpenAI | `https://api.openai.com/v1` |
119
+ | Anthropic | _(select "anthropic" type)_ |
120
+ | Groq | `https://api.groq.com/openai/v1` |
121
+ | DeepSeek | `https://api.deepseek.com/v1` |
122
+ | Ollama (local) | `http://localhost:11434/v1` |
123
+ | LiteLLM proxy | `http://localhost:4000` |
124
+
125
+ ---
126
+
127
+ ## Agent Modes
32
128
 
33
129
  Switch modes with `/mode` or `Shift+Tab`:
34
130
 
@@ -36,21 +132,30 @@ Switch modes with `/mode` or `Shift+Tab`:
36
132
  |---|---|
37
133
  | `default` | Confirms file edits, downloads, and shell commands per policy |
38
134
  | `accept-edits` | Auto-approves workspace file edits; confirms commands and downloads |
39
- | `plan` | Read-only research & planning mode; all mutating tools and non-readonly commands blocked |
40
- | `auto` | Autonomous execution without tool-approval prompts |
135
+ | `plan` | Read-only research & planning; all mutating tools are blocked |
136
+ | `auto` | **Fully autonomous** — no approval prompts for any tool call |
137
+
138
+ > **Auto mode** is designed for truly autonomous operation. The agent never asks for tool approval. Safety comes from the permission engine, audit log, file checkpoints, and undo — not from prompts.
139
+
140
+ ---
41
141
 
42
142
  ## CLI Flags
43
143
 
144
+ ```
145
+ kovence [options] [prompt]
146
+ kovence doctor
147
+ ```
148
+
44
149
  | Flag | Description |
45
150
  |---|---|
46
- | `--provider <name>` | Use configured OpenAI/Anthropic provider |
47
- | `-m, --model <name>` | Override active model |
48
- | `-p, --prompt <text>` | Non-interactive headless prompt |
49
- | `-s, --system <text>` | Override system prompt |
151
+ | `--provider <name>` | Use a configured provider by name |
152
+ | `-m, --model <name>` | Override the active model |
153
+ | `-p, --prompt <text>` | Non-interactive headless prompt (exits when done) |
154
+ | `-s, --system <text>` | Override the system prompt |
50
155
  | `--mode <mode>` | Agent mode: `default \| accept-edits \| plan \| auto` |
51
156
  | `-a, --auto` | Alias for `--mode auto` |
52
157
  | `--add-dir <path>` | Grant workspace access to an extra directory (repeatable) |
53
- | `--no-tools` | Disable tool calling (chat only) |
158
+ | `--no-tools` | Disable all tool calling (chat-only mode) |
54
159
  | `--no-summary` | Skip post-response session memory summarization |
55
160
  | `--plain` | Use plain scrollback REPL instead of full-screen TUI |
56
161
  | `--json` | Emit structured JSON result in `-p` headless mode |
@@ -58,45 +163,225 @@ Switch modes with `/mode` or `Shift+Tab`:
58
163
  | `--debug` | Enable verbose debug tracing |
59
164
  | `-t, --temp <num>` | Sampling temperature (`0.0` to `2.0`) |
60
165
  | `--max-tokens <num>` | Max completion tokens |
61
- | `--session <name>` | Resume/use a specific saved session |
166
+ | `--session <name>` | Resume or create a specific named session |
62
167
  | `-c, --continue` | Resume the most recent session |
63
- | `--new-session <name>` | Start a fresh session with given name |
64
- | `-v, --version` | Show version |
65
- | `-h, --help` | Show help |
168
+ | `--new-session <name>` | Start a fresh session with the given name |
169
+ | `-v, --version` | Show version and exit |
170
+ | `-h, --help` | Show help and exit |
66
171
  | `doctor` | Subcommand: check Node, tools, config, and provider reachability |
67
172
 
173
+ ### Headless / scripting example
174
+
175
+ ```bash
176
+ # Single-shot prompt, structured JSON output
177
+ kovence -p "summarize this file" --json
178
+
179
+ # Pipe output
180
+ echo "refactor this function" | kovence --plain --no-session
181
+ ```
182
+
183
+ ---
184
+
68
185
  ## Slash Commands
69
186
 
187
+ Type `/` in the composer to see autocomplete suggestions.
188
+
70
189
  | Command | Description |
71
190
  |---|---|
72
- | `/help` | Show all commands |
73
- | `/mode` | Switch agent mode (`default\|accept-edits\|plan\|auto`) |
191
+ | `/help` | Show all available commands |
192
+ | `/mode` | Switch agent mode (`default \| accept-edits \| plan \| auto`) |
74
193
  | `/settings` | Open interactive Settings panel (`Ctrl+,`) |
75
- | `/set` | Update persisted setting (`/set <key> <val>`) |
76
- | `/api` | Switch/add OpenAI or Anthropic custom APIs |
77
- | `/model` | Pick or switch active model (`/model [name]`) |
78
- | `/sessions` | Session picker / manage (`list\|new\|switch\|delete`) (`Ctrl+S`) |
194
+ | `/set <key> <val>` | Update a persisted setting directly |
195
+ | `/api` | Switch, add, or remove AI providers |
196
+ | `/model [name]` | Pick or switch the active model |
197
+ | `/sessions` | Session picker — list, switch, delete sessions (`Ctrl+S`) |
79
198
  | `/new` | Open a new isolated session (`Ctrl+N`) |
80
- | `/retry` | Retry the last failed/aborted user turn |
199
+ | `/rename <name>` | Rename the current session |
200
+ | `/fork [name]` | Fork current session into a new branch |
201
+ | `/export [md\|json] [path]` | Export session transcript to a file |
202
+ | `/retry` | Retry the last failed or aborted turn |
203
+ | `/edit-last` | Pop the last turn and restore your prompt for editing |
81
204
  | `/history` | Show session chat history |
82
- | `/memory` | Show/manage session & global memory |
83
- | `/todos` | Show current session multi-step todos |
84
- | `/compact` | Compact history into session summary |
85
- | `/stats` | Show full context size, speed & token stats |
86
- | `/copy` | Copy last AI response to clipboard (`Ctrl+Y`) |
87
- | `/select` | Toggle native terminal mouse select mode (`F2`) |
88
- | `/save` | Rename/save current session |
89
- | `/rename` | Rename current session |
90
- | `/fork` | Fork current session into a new branch |
91
- | `/export` | Export session transcript (`md\|json`) |
92
- | `/edit-last` | Pop last turn and restore prompt for editing |
93
- | `/undo` | Rollback the last file edit/write/delete checkpoint |
94
- | `/init` | Scan project & generate `KOVENCE.md` instructions |
95
- | `/tasks` | List, view logs, or stop background shell tasks |
205
+ | `/memory` | Show and manage session & global memory |
206
+ | `/todos` | Show current multi-step todo list |
207
+ | `/compact` | Compact history into a session summary |
208
+ | `/stats` | Show context size, speed, and token statistics |
96
209
  | `/cost` | Show estimated session token cost in USD |
97
- | `/clear` | Clear current session history & memory |
210
+ | `/copy` | Copy the last AI response to clipboard (`Ctrl+Y`) |
211
+ | `/select` | Toggle native terminal mouse-select mode (`F2`) |
212
+ | `/save` | Save/rename the current session |
213
+ | `/undo` | Roll back the last file edit/write/delete checkpoint |
214
+ | `/init` | Scan project and generate `KOVENCE.md` instructions |
215
+ | `/tasks [log <id> \| kill <id>]` | List, view logs, or stop background shell tasks |
216
+ | `/clear` | Clear current session history and memory |
98
217
  | `/exit` | Exit Kovence CLI |
99
218
 
219
+ ---
220
+
221
+ ## Keyboard Shortcuts
222
+
223
+ ### Composer (input area)
224
+
225
+ | Key | Action |
226
+ |---|---|
227
+ | `Enter` | Send message |
228
+ | `Shift+Enter` / `Alt+Enter` | Insert newline |
229
+ | `Tab` | Accept autocomplete suggestion (slash command / `@file`) |
230
+ | `↑` / `↓` | Scroll through input history or suggestions |
231
+ | `Ctrl+Left` / `Alt+B` | Move cursor one word left |
232
+ | `Ctrl+Right` / `Alt+F` | Move cursor one word right |
233
+ | `Ctrl+W` / `Alt+Backspace` | Delete word to the left |
234
+ | `Ctrl+C` _(busy)_ | Cancel the current agent turn |
235
+ | `Ctrl+C` _(idle)_ | Exit Kovence CLI |
236
+
237
+ ### TUI global shortcuts
238
+
239
+ | Key | Action |
240
+ |---|---|
241
+ | `Ctrl+,` | Open Settings panel |
242
+ | `Ctrl+S` | Open session picker |
243
+ | `Ctrl+N` | Start a new session |
244
+ | `Ctrl+Y` | Copy last AI response to clipboard |
245
+ | `Ctrl+L` | Clear and redraw the screen |
246
+ | `Ctrl+O` | Toggle last collapsible block (tool output) |
247
+ | `Shift+Tab` | Cycle agent mode |
248
+ | `F2` | Toggle mouse-select mode |
249
+
250
+ ---
251
+
252
+ ## File Mentions (@file)
253
+
254
+ You can mention files directly in your prompt using the `@` syntax. Kovence will read the file content and include it in context.
255
+
256
+ ```
257
+ @README.md what does this say about installation?
258
+
259
+ @src/agent/turn.js:L1-80 explain this section
260
+ ```
261
+
262
+ - `@filename` — include the entire file
263
+ - `@filename:L10-50` — include only lines 10–50
264
+
265
+ Autocomplete is available: type `@` and press `Tab` to browse files.
266
+
267
+ ---
268
+
269
+ ## Background Tasks
270
+
271
+ ### Direct shell escape
272
+
273
+ In plain REPL mode, prefix a command with `!` to run it directly in your shell:
274
+
275
+ ```
276
+ !git status
277
+ !npm test
278
+ ```
279
+
280
+ ### Agent background tasks
281
+
282
+ The agent can run shell commands as background tasks (`run_command` with `background: true`). Manage them with:
283
+
284
+ ```
285
+ /tasks # List all running background tasks
286
+ /tasks log <id> # Stream logs from a task
287
+ /tasks kill <id> # Terminate a background task
288
+ ```
289
+
290
+ Background tasks persist across turns and are shown in the status bar when active.
291
+
292
+ ---
293
+
294
+ ## Session Management
295
+
296
+ ### Auto-naming
297
+
298
+ Sessions are automatically named from your first prompt (slugified, e.g., `fix-auth-bug`). You can rename anytime:
299
+
300
+ ```
301
+ /rename my-feature-branch
302
+ ```
303
+
304
+ ### Date grouping
305
+
306
+ The session picker (`Ctrl+S`) groups sessions by date (Today, Yesterday, This Week, etc.) for easy navigation.
307
+
308
+ ### Fork & Export
309
+
310
+ ```
311
+ /fork # Fork into a new session (preserves history)
312
+ /fork my-fork-name # Fork with a specific name
313
+
314
+ /export md # Export transcript as Markdown
315
+ /export json # Export as JSON
316
+ /export md ~/Desktop/session.md # Export to a specific path
317
+ ```
318
+
319
+ ### Edit last turn
320
+
321
+ ```
322
+ /edit-last # Removes the last turn and restores your prompt for editing
323
+ ```
324
+
325
+ ### Undo file changes
326
+
327
+ ```
328
+ /undo # Roll back the last file write/edit/delete (checkpoint-based)
329
+ ```
330
+
331
+ ---
332
+
333
+ ## Settings Reference
334
+
335
+ Open the interactive settings panel with `Ctrl+,` or `/settings`. Settings are saved to `~/.config/kovence/settings.json`.
336
+
337
+ | Setting | Values | Description |
338
+ |---|---|---|
339
+ | `agentMode` | `default \| accept-edits \| plan \| auto` | Default agent mode on launch |
340
+ | `toolPermission` | `default \| auto` | Tool permission policy |
341
+ | `nonWorkspaceAccess` | `true \| false` | Allow reads outside workspace |
342
+ | `model` | string | Default model name |
343
+ | `provider` | string | Default provider name |
344
+ | `toolsEnabled` | `true \| false` | Enable/disable tool calling |
345
+ | `autoSummarize` | `true \| false` | Auto-compact history when context is full |
346
+ | `maxToolSteps` | number | Max tool-call iterations per turn |
347
+ | `maxHistoryMessages` | number | Max messages kept in context |
348
+ | `contextWindow` | number | Context window size (tokens) |
349
+ | `temperature` | `0.0`–`2.0` | Sampling temperature |
350
+ | `maxTokens` | number | Max completion tokens |
351
+ | `verbosity` | `low \| normal \| high` | Tool output verbosity in TUI |
352
+ | `language` | `english \| banglish \| bangla` | Preferred response language |
353
+ | `renderingMode` | `fullscreen \| inline` | TUI layout mode |
354
+ | `queuedMessages` | `queue \| interrupt` | Behavior when a message arrives during a turn |
355
+ | `showTips` | `true \| false` | Show contextual tips in TUI |
356
+ | `showActiveTasks` | `true \| false` | Show background task count in status bar |
357
+ | `notifications` | `true \| false` | Desktop notifications on turn completion |
358
+ | `colorScheme` | `amber \| dark \| light \| terminal` | TUI color theme |
359
+
360
+ You can also set any value directly:
361
+
362
+ ```bash
363
+ # In the TUI composer:
364
+ /set agentMode auto
365
+ /set colorScheme dark
366
+ /set temperature 0.7
367
+ ```
368
+
369
+ ---
370
+
371
+ ## Environment Diagnostics
372
+
373
+ ```bash
374
+ kovence doctor
375
+ ```
376
+
377
+ Checks and reports on:
378
+ - Node.js version compatibility
379
+ - Required system tools (`git`, `curl`, etc.)
380
+ - Config and provider file validity
381
+ - Provider API reachability (live ping)
382
+
383
+ ---
384
+
100
385
  ## License
101
386
 
102
- MIT
387
+ MIT © Kovence
package/package.json CHANGED
@@ -1,9 +1,16 @@
1
1
  {
2
2
  "name": "kovence-cli",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Kovence CLI — Fast zero-dependency multi-step AI coding-agent CLI harness",
5
5
  "license": "MIT",
6
- "homepage": "https://kovence.com",
6
+ "homepage": "https://github.com/MillatSakib/kovence-cli#readme",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/MillatSakib/kovence-cli.git"
10
+ },
11
+ "bugs": {
12
+ "url": "https://github.com/MillatSakib/kovence-cli/issues"
13
+ },
7
14
  "keywords": [
8
15
  "cli",
9
16
  "ai",