` in one or all files |
| `/open` | Open a file and read it with line numbers |
| `/project:create` | Create a new project bookmark (prompts for name and path) |
| `/project:list` | List saved projects and switch to one (changes cwd) |
| `/project:delete` | Remove a project bookmark from the list |
| `/clear` | Clear the in-memory session |
| `/reset` | Clear + reload model from config |
| `/help` | Show all slash commands |
| `/exit` | Quit (`/quit` works too) |
### Direct shell commands
Any input starting with `$` or `>` is run as a shell command in your project root:
```text
β― $ npm test
β $ npm test
> my-project@1.0.0 test
> jest
PASS src/sum.test.ts
exit 0 Β· 4.1s
```
Read-only commands (`ls`, `cat`, `git status`, β¦) run with auto-approval when `KOB_AUTO_APPROVE_READONLY=true`. Mutating ones ask once. Dangerous ones (`rm -rf`, `git reset --hard`, `curl β¦ | sh`, β¦) are flagged in red and always require explicit `Y`.
### Special keys
| Key | Action |
| -------- | --------------------------------------------------------- |
| `Tab` | Cycle mode (Ask β Plan β Code) |
| `1`/`2`/`3` | Jump to mode |
| `β` / `β` | Walk through your last 100 prompts |
| `Esc` | Abort the current generation (during streaming) |
| `Ctrl+C` | Quit |
| `Ctrl+V` | Paste an image (vision-capable models only) |
| `y` | Copy the last assistant response to your clipboard |
| `R` | When shown "Press R to retry" β re-send the last request |
---
## π§ How the agent works
The runtime is a small, explicit pipeline β no hidden orchestration, no opaque plugin system.
```
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β USER INPUT β
β "add a healthcheck endpoint to src/server.ts" β
ββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ENGINE (src/core/engine.ts) β
β β’ load session history (scoped to cwd) β
β β’ inject file tree into the system prompt β
β β’ send to KOB AI /api/v2/chat/completions (streaming) β
ββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PARSER (src/tools/parser.ts) β
β β’ extract ```ts:path fenced blocks β write_file β
β β’ extract ```bash fenced blocks β run_shell β
β β’ extract tool_call JSON β str_replace / read_fileβ
ββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β EXECUTOR β
β β’ sandbox path: must be inside project root β
β β’ show inline: read Β· str_replace Β· write Β· command output β
β β’ destructive commands β red confirmation banner β
β β’ every mutation pushed to the undo stack β
ββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β RENDER (src/ui/render.ts) β
β β’ colored diffs of changed files β
β β’ command output (first 8 lines + exit code + duration) β
β β’ markdown assistant reply with syntax tint β
β β’ "β Done" round close β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
A single user request can produce **multiple rounds**: the model reads a file, decides to edit, applies a `str_replace`, runs a test, sees the failure, and fixes it β all inside one turn.
### Network resilience
- Up to **5 automatic retries** on transient failures (DNS, TCP, TLS, fetch aborted) with exponential backoff + jitter (0.5s β 1s β 2s β 4s, capped at 5s).
- HTTP 4xx/5xx are **not retried** β they bubble up immediately with the server's message.
- User aborts (`Esc`) are **not retried** β they propagate instantly.
- On final failure the REPL prints `Press R to retry, any other key to continue.` β one keypress, no retyping.
---
## π Project layout
```
src/
βββ index.ts CLI entry + non-interactive subcommands
βββ repl.ts interactive REPL loop, command routing, Esc interrupt
βββ core/
β βββ api.ts streaming OpenAI-compatible client + retry logic
β βββ engine.ts agentic multi-round loop
β βββ modes.ts chat / ask / plan / code prompts
β βββ config.ts env loading + validation
β βββ env-file.ts read/write ~/.kob-cli/config.env (comment-preserving)
β βββ history.ts per-project session persistence
β βββ types.ts
βββ tools/
β βββ parser.ts extract file blocks, tool calls, shell commands
β βββ files.ts sandboxed read/write/str_replace + file tree
β βββ shell.ts run commands, read-only & danger classifiers
β βββ git.ts branch / dirty / ahead-behind
β βββ diff.ts LCS line diff + compact hunks
β βββ clipboard.ts
βββ ui/
β βββ banner.ts the KOB header
β βββ gradient.ts dependency-free hex gradient
β βββ markdown.ts Markdown β ANSI with syntax tint
β βββ render.ts status bar, diffs, help, results
β βββ spinner.ts interleaving single-line spinner
β βββ prompts.ts model picker, config form, approvals
β βββ theme.ts palette + helpers
βββ scripts/
βββ release.ts bump + build + publish + push + tag
```
---
## π Development
```bash
bun run dev # bun run src/index.ts β live REPL
bun run typecheck # tsc --noEmit, no compile
bun run build # compile to a single native binary
bun run build:only # bun build src/index.ts --compile --outfile kob-cli
```
### Releasing a new version
The release script (`src/scripts/release.ts`) bumps `package.json`, runs the typecheck, rebuilds the binary, and commits in one step:
```bash
bun run release:patch # 2.0.0 β 2.0.1
bun run release:minor # 2.0.0 β 2.1.0
bun run release:major # 2.0.0 β 3.0.0
```
### Style
- TypeScript, strict, ESM modules
- async/await everywhere β no `.then` chains
- single responsibility per file under `src/tools/`, `src/ui/`
- prefer editing existing files; only create new ones when there is no good host
- run `bun run typecheck` before opening a PR
---
## π Backend contract
KOB CLI speaks the OpenAI streaming protocol to `KOB_API_BASE_URL`. Minimum the backend must support:
| Endpoint | Method | Purpose |
| ---------------------------- | ------ | ----------------------------- |
| `/api/v2/chat/completions` | POST | streaming chat (SSE) |
| `/api/ai/models` | POST | model catalog (primary) |
| `/api/models` | POST | model catalog (fallback) |
| `/api/v2/models` | GET | model catalog (fallback) |
Authentication is a Bearer token. The `KobApiClient` (see [src/core/api.ts](src/core/api.ts)) tries the catalog endpoints in order, so older backends stay compatible.
---
## πΊ Roadmap
In priority order, not promised:
- [ ] Conversation export to Markdown / JSON
- [ ] Multi-profile `.env` switching
- [ ] Plugin hooks (pre/post tool execution)
- [ ] Background "watch this file" agents
- [ ] In-terminal Markdown preview pane
- [ ] Built-in token cost estimator
Out of scope, intentionally: editor plugin, GUI client, global cross-project memory store.
---
## π Troubleshooting
**`Connection failed. Please check your network and try again.`**
The backend was unreachable for 5 retries. Check `KOB_API_BASE_URL`, your network, or just press `R` to retry.
**`This model does not support the requested operation.`**
You tried to paste an image into a text-only model, or called a vision tool on a model that has no `vl` in its id. Run `/models` to switch.
**`No API key configured. Exiting.`**
Run `kob config` and paste your `kob_xxx:token` key.
**`β Permission denied` on shell commands**
Mutating shell commands require an explicit `Y` at the prompt. Destructive ones are flagged in red β type `Y` only if you mean it.
---
## π€ Contributing
Issues and PRs are welcome. Please read the design log under [docs/](docs/README.md) first β most architectural questions are answered there. The codebase is small enough that you can read it in an afternoon.
---
## π License
[MIT](LICENSE) Β· Β© Kob AI Β· [www.kob-ai.dev](https://www.kob-ai.dev)
---
**ΰΈΰΉΰΈ²ΰΈΰΈΰΈ ΰΈΰΈ²ΰΈΰΈΰΈ β ΰΈΰΈ΅ΰΉ GitHub ΰΉΰΈ«ΰΉΰΈΰΉΰΈ§ΰΈ’ΰΈΰΈ°ΰΈΰΈ£ΰΈ±ΰΈ πΉπ**
If you like it, drop a β on GitHub.