kbcode Documentation

1 Installation

Paste one line into PowerShell or cmd.exe — no Python, no admin rights, no clone needed:

powershell -NoProfile -ExecutionPolicy Bypass -Command "[Net.ServicePointManager]::SecurityProtocol='Tls12'; Invoke-Expression (Invoke-RestMethod -UseBasicParsing https://kbcode.dev/install.ps1)"

PowerShell • works in cmd.exe too — just paste and press Enter

cmd.exe (Command Prompt — no PowerShell):

curl -fsSL https://kbcode.dev/install.bat -o "%TEMP%\kbi.bat" && "%TEMP%\kbi.bat"

2 Chrome Extension

kbcode drives your real Chrome — your profile, your logins, your sessions. The extension is the bridge that makes that possible, and there is no Playwright/Selenium fallback by design.

The extension is published in the Chrome Web Store — install it in one click and Chrome keeps it updated automatically:

kb extension

Running kb extension opens the store page for you. (Or install it directly: extension page →.)

Why an extension, and not Playwright?

Every other agent launches a separate, logged-out browser: you re-login on every site, 2FA fires every time, and anything behind a session simply fails. The extension makes kbcode act inside the Chrome you already use — your profile, your cookies, your open tabs. That is why there is no Playwright/Selenium fallback: falling back would silently throw away the one thing that makes it work.

How it fits together

Multiple profiles stay connected at the same time. Nothing is closed or switched: each command names the profile it should run in, and the others keep their tabs and sessions.

The three commands

What kbcode can do in the browser

25 browser tools. You never call them by name — you describe the task and the agent picks — but this is the actual reach:

Try it

kb extension        # once
kb

open github, go to my notifications, and summarise the unread ones

Save and restore a whole browser state — tabs plus cookies, encrypted and local only — with /session save <name> and /session restore.

When it does not work

3 Sign In

Register at kbcode.dev/register with email+password or Google. Then authenticate in the terminal — kb login asks you to choose:

kb login

1. Browser login — opens https://kbcode.dev/login; the token is sent back to your terminal automatically via a localhost callback.
2. Paste a token — copy your token from the dashboard (Copy token button) and paste it in the terminal. No browser needed.

Check your status: kb whoami • Sign out: kb logout

4 Model Setup

Run the interactive wizard to pick your provider and model:

kb model

Choose from 15+ providers — Anthropic Claude, OpenAI, Google Gemini, xAI Grok, DeepSeek, Moonshot, OpenRouter, Mistral, Groq, Together, Qwen, Ollama (local), or any OpenAI-compatible API via Custom.

Your API key is Fernet-encrypted and machine-bound in ~/.kbcode/config.json — it goes to your provider and nowhere else.

5 Your First Task

Installed and signed in? Here is the whole loop, start to finish.

1. Teach kbcode your project — once

cd C:\path\to\your-project
kb init

This creates AGENT.md (your standing instructions, read every session) and kb/ (short notes about your code). Then start the chat with kb and type /init — kbcode reads the project and writes those notes.

Why it matters: without kb/, an agent re-reads your repo every session and you pay for it in tokens and time. With it, kbcode answers from notes and opens only the files a task actually touches. Session two is cheaper than session one.

2. Ask for something small and verifiable

add a --verbose flag to the CLI and a test for it

It states what it will do, reads the relevant files, asks permission before each edit or command, then runs the tests and reports the real result.

3. Do not like it? Undo

/undo

Every edit is checkpointed first, so undo always works. /diff shows exactly what changed before you decide.

4. Make it remember

/learn      # turn what we just did into a reusable skill
/kb         # read or refresh the project knowledge base
/memory     # durable facts across every session

A skill you teach once runs later in any session with /<name>.

6 Recipes

Complete workflows for real jobs — copy, paste, adapt.

Review a branch before you push

git diff origin/main... | kb "review this diff — correctness, edge cases, tests"

Piped input becomes context (50k cap, secrets redacted). Gotcha: plain git diff shows only unstaged work.

Understand code without risking edits

/mode ask
how does session resume work, end to end?

In ask mode the write tools are not offered to the model at all — it cannot change anything while explaining.

Plan before building

/mode architect
we need multi-tenant support — what are the options and trade-offs?

Then: write the chosen approach into kb/ as a note. Next session starts already knowing the decision.

Start something brand new

/mode driven
I want to build a CLI that syncs my notes to S3

driven asks you the requirements first instead of guessing and building the wrong thing.

Run a whole task unattended

kb -y "update every deprecated API call and run the tests"

Exit codes: 0 completed · 1 did not complete · 2 usage error / not activated · 130 interrupted. Gotcha: -y means full shell approval — do not use it on code you have not read.

Automate a site with your real logins

kb extension       # one time
kb

open github, go to my notifications, and summarise the unread ones

kbcode drives your Chrome — your profile, your sessions. Nothing to log into again.

Use a cheap model for grunt work

KBCODE_MODEL_TIERS={"planning":"claude-sonnet-4-5","editing":"deepseek-chat"}

Planning on a strong model, editing on a cheap one. Most agents lock you to one vendor; this is kbcode's biggest cost lever.

Run risky work in the background

/bg refactor the payment module to use the new API

Background tasks run in their own git worktree and land as a branch — your working tree is untouched. /tasks lists them.

7 Common Mistakes

8 Terminal Commands

Piping context:

git diff | kb "review this change for bugs"

9 Slash Commands (In Chat)

Type /help inside the chat to see all 96 commands. Here are the most-used ones — the full commands reference explains what each one does, why you would use it, and how.

10 Keyboard Shortcuts

11 Modes

Switch modes with /mode <name> to apply tool guardrails. Each mode gets only the tools it needs:

Full details: Modes reference page with all guardrails per mode.

12 Configuration & Precedence

Configure via .env in your project or global ~/.kbcode/.env:

KBCODE_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
KBCODE_MODEL=claude-sonnet-4-5

Precedence (highest to lowest):

1. Project .kbcode/config.json — overrides everything for this project
2. Environment variables — .env in the project root or launch folder
3. Global ~/.kbcode/config.json — your defaults across all projects
4. Built-in defaults — fallback when nothing else is set

13 MCP Tool Servers

Connect any stdio MCP server — its tools become built-in commands inside kbcode:

kb mcp-add my-server -- python -m my_mcp_server
kb mcp-remove my-server

MCP servers are configured per-project (.kbcode/settings.json) or globally (~/.kbcode/settings.json). kbcode also auto-detects installed servers (like ai-knowledgebase) at startup — no manual config needed.

14 Safety & Privacy

• Checkpoints: Automated git snapshot before every edit. /undo reverts the last turn instantly — nothing is lost.
• Key Encryption: API keys are Fernet-encrypted and machine-bound in ~/.kbcode/config.json. They go only to your provider.
• Secret Redaction: Logs, prompts, and feedback automatically strip API keys and credentials before touching disk or network.
• Untrusted Envelope: External web content (search results, fetched pages) is wrapped to block prompt-injection attacks.
• Tool Approval: Dangerous operations (writing files, running commands) require your explicit approval — kbcode never runs them silently unless you enable auto mode.

15 Troubleshooting / FAQ

'kb' is not recognized as an internal or external command?

PATH changes require a new terminal window. Open a fresh terminal and try again. If still stuck:

python -m kbcode fixpath

Or manually add %LOCALAPPDATA%\kbcode to your user PATH via System Properties → Environment Variables.

Do I need Python installed?

No. The installer sets up everything kbcode needs — Python is completely optional.

"Activation required" — what does this mean?

You need to sign in first. Run kb login and sign in with the account you registered at kbcode.dev/register. Only --version, login, logout, and doctor work without activation.

Login timeout — browser didn't open or timed out?

Visit kbcode.dev/dashboard in any browser, sign in, and copy your JWT token. Then paste it in the terminal:

kb login --token eyJh...

This works anywhere — SSH, headless servers, or when the localhost callback can't reach your terminal.

Browser automation isn't working?

Install the kbcode Chrome extension from the Chrome Web Store — run kb extension and it opens the store page for you. Then check kb extension doctor to verify Chrome loaded it and the bridge is connected.

How do I switch models mid-session?

Type /model inside the chat — it re-runs the model picker without losing your session context.