✨ Why KOB CLI

Most AI chat tools are passive: you paste code, you get text back. KOB CLI is active — it understands your project, decides which tools to call, and shows you exactly what it changed, with diffs and undo support.

It is designed to feel like a disciplined pair programmer inside your terminal:

• 🔍 Reads first — the engine injects your file tree into context, so the model knows what you have before suggesting changes.
• 🛠 Acts, not just answers — read_file, str_replace, write_file, and shell commands are first-class tool calls, not hidden magic.
• 🎨 Colored diffs, visible progress — every read, replacement, file write, and command run is reported inline as it happens.
• ↩️ /undo is real undo — every file mutation in the last turn can be reverted, no Git ceremony required.
• 🛡 Safe by default — destructive shell commands are flagged in red and require explicit Y confirmation.
• 💾 Remembers your project — per-project session history means reopening kob in the same repo picks up where you left off.
• 🌍 Bilingual — status banners, help text, and prompts in English and ไทย.

🚀 Quick start

# 1. Install globally from npm
npm i -g kob-cli

# 2. Configure — the program creates .env for you, just answer the prompts
kob config
#   API key : kob_xxx:token         (paste from https://www.kob-ai.dev)
#   Model   : deepseek/deepseek-v4-flash   (or pick from /models)
#   Base URL: https://www.kob-ai.dev       (default, just press Enter)

# 3. Launch the REPL
kob

That's it. No git clone, no bun install, no manual .env editing.

Inside the REPL, type a plain request — the agent does the rest.

❯ add a healthcheck endpoint to src/server.ts and write a test

Press Tab to switch between Ask, Plan, and Code modes. Press R to retry if the network blips. Type ? to see all key bindings.

📦 Installation

Recommended: from npm

npm i -g kob-cli
kob --version            # smoke test → e.g. 2.0.3

Works on macOS, Linux, and Windows. The kob binary is added to your PATH automatically.

From source (for contributors)

git clone https://github.com/thekaroe-thailand/kobcli.git
cd kobcli
bun install
bun link                  # exposes the local `kob` on your PATH
bun run dev               # live REPL against the source

bun link creates a symlink in your global bin pointing at this checkout, so any edit here is immediately reflected when you run kob.

Update

# npm install
npm update -g kob-cli

# from source
cd kobcli && git pull && bun install && bun link

Uninstall

npm uninstall -g kob-cli
rm -rf ~/.kob-cli            # wipes persisted sessions

⚙️ Configuration

You do not edit .env by hand. Run kob config (or /config from inside the REPL) and the program creates the file for you, pre-filled with the values you entered.

kob config

  ┌  KOB CLI configuration
  │
  ◇  API key (kob_xxx:token) — leave blank to keep current
  │  kob_xxxxxxxxxxxxxxxxxxxxxxxx
  │
  ◇  Default model id
  │  deepseek/deepseek-v4-flash
  │
  ◇  API base URL
  │  https://www.kob-ai.dev
  │
  └  ✓ Configuration saved

The form writes a project-local .env that looks like this — you only ever see it because you asked to look, you never need to touch it:

KOB_API_BASE_URL=https://www.kob-ai.dev
KOB_API_KEY=kob_your_api_key_here
KOB_MODEL_ID=deepseek/deepseek-v4-flash
KOB_MAX_TOKENS=16384
KOB_AUTO_APPROVE_READONLY=true

Config keys

Switching config later

The same form is available at any time — inside the REPL just type /config:

❯ /config

Edit one field, press Enter, the file is rewritten and the REPL reloads. Your session and history are preserved.

🧑‍💻 Usage

CLI commands

kob                       # launch interactive REPL (default)
kob chat                  # same as above, explicit
kob ask "…"               # one-shot question, no REPL
kob ask "…" -m gpt-4o     # override model for one request
kob models                # list available models from backend
kob config                # edit .env interactively
kob --version             # show version
kob --help                # full CLI help

Modes

Press Tab to cycle, or 1/2/3 to jump:

The mode colours the system prompt, the rail around the conversation, and the prompt icon. Code is the default.

Slash commands

Type / to open the autocomplete menu, or type the command directly:

Direct shell commands

Any input starting with $ or > is run as a shell command in your project root:

❯ $ 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

🧠 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 .env.local (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

docs/ holds a deeper design log (00-overview → 17-legacy-and-migration-notes) if you want to understand why a thing is the way it is.

🛠 Development

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:

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:

Authentication is a Bearer token. The KobApiClient (see 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/ first — most architectural questions are answered there. The codebase is small enough that you can read it in an afternoon.

📄 License

MIT · © Kob AI · www.kob-ai.dev