npm package: @kimbho/kimbho-cli
Description: Kimbho CLI is a terminal-native coding agent for planning, execution, and verification.
Latest version: 0.1.36

# Kimbho CLI

Kimbho CLI is a terminal-native coding agent for planning, execution, and verification.

## Install

From npm after publication:

```bash
npm install -g @kimbho/kimbho-cli
```

From a local checkout:

```bash
npm install
npm run build
npm install -g ./packages/cli
```

From a packed tarball:

```bash
npm run pack:cli
npm install -g ./kimbho-kimbho-cli-<version>.tgz
```

## Usage

```bash
kimbho
kimbho shell
kimbho "explain this repo"
kimbho exec --json "explain this repo"
kimbho completion bash
kimbho --help
kimbho init
kimbho plan "build a coding agent"
kimbho fork --last
kimbho resume --list
kimbho -c 'approvalMode="auto"' -c 'brains.coder.providerId="echo"' "hello"
kimbho /models openrouter --search claude --limit 10
```

Bare `kimbho` opens the interactive shell. Within that shell, plain build/change prompts are routed into the agent runtime by default, while `/ask` keeps a plain chat path to the active model. Slash commands like `/plan`, `/run`, `/models`, and `/brains` are supported too. Provider and model selections apply to all agent roles by default.

Useful shell commands:

```bash
/status
/ask say hello from lm studio
/ask explain this codebase
/providers
/providers add openrouter
/providers use openrouter-main
/brain coder
/models claude
/select 1
/model
/plan build a coding agent
/run scaffold a SaaS starter
/resume --execute --max-auto-tasks 2 --max-repair-attempts 2
/approve
/deny
/review
/quit
```

Example direct execution prompt:

```bash
build a landing page for a small storefront
```

That prompt now runs through the agent execution path, streams live task and tool activity while it executes, and then prints the saved session summary instead of returning a plain chat answer.
During an active shell run, `Ctrl+C` now requests a pause instead of killing the shell; use `/resume` to continue the saved session.
Shell runs now also show a compact live run board with active tasks, budgets, token usage, and the latest runtime note while execution is in flight.
When a run pauses for an approval-required action, use `/approve` or `/deny` to resolve the pending request and continue the saved session.

LM Studio example:

```bash
/providers add lmstudio lmstudio-lan --base-url http://192.168.0.70:1234
/models
/select 1
```

`run` now auto-executes the supported ready-task frontier and persists session events. Specialist tasks are executed through a bounded model-driven tool loop that can list files, search source contents, read files, write files, apply patches, inspect git diff, run verification commands, and emit resumable transcripts. `resume --execute` continues that frontier from the latest session snapshot.
Kimbho also has repo intelligence tools (`repo.index`, `repo.query`) so agents can reason over symbols, routes, schemas, packages, and import edges instead of relying only on raw file reads.
For empty workspaces, Kimbho now has deterministic scaffold presets for `static-landing`, `node-cli-typescript`, `next-prisma-postgres`, and `kimbho-cli-monorepo`, so the scaffold task can generate a real starter app without needing preexisting repo state or a prior `.kimbho/config.toml`.
For existing repositories, specialists now preload deterministic repo context before the first model action: `repo.index`, `repo.query`, and a small set of repo-defining file reads are injected automatically into the transcript and prompt context.
When resuming the current saved session, that saved session context is also injected into the next specialist run so the model does not restart from zero.
After the agent changes workspace state, it now has to pass a verification step before the task can finish.
If verification fails, Kimbho forces a repair pass before the next rerun and blocks the task after the configured repair budget is exhausted.
If a non-debugger specialist burns through that budget, Kimbho automatically hands the task to `test-debugger` and keeps the same task id/dependency chain intact.
The tool layer now enforces the configured sandbox and approval policy for high-risk actions: read-only sandboxes reject mutating tools, and destructive shell commands like `rm -rf` or `git reset --hard` are blocked under manual approval mode.
When the workspace is a git repository with a valid `HEAD`, specialist tasks now run in isolated git worktrees and Kimbho reapplies the resulting diff back to the main workspace.
If multiple specialist tasks are ready at the same time, Kimbho now schedules them concurrently in separate worktrees and surfaces their diff integration live in the shell.
Those concurrent integrations are now serialized, so overlapping edits do not race generic patch application anymore.
If a direct integration fails, Kimbho now replays the specialist diff on top of the latest workspace snapshot in a retry sandbox, reapplies a refreshed patch when that drift is mergeable, and preserves the original patch artifact when it is not.
When the replay path still cannot land, Kimbho now writes an integration-conflict bundle with the relevant patch paths, conflicting files, failure output, and operator next steps.
If that failure originates from a specialist task, Kimbho now rewrites the task into an `integrator` handoff instead of leaving it as a raw blocked patch failure.
Kimbho also has managed background process tools and live HTTP verification: `process.start`, `process.list`, `process.logs`, `process.stop`, and `http.fetch`.
Kimbho now also has browser-session tools for headless Chrome verification: `browser.open`, `browser.inspect`, `browser.click`, `browser.fill`, `browser.list`, and `browser.close`.
Shell runs now surface model-usage telemetry when the provider returns token counts.
If a specialist starts a managed process inside an isolated worktree, Kimbho now stops it automatically before cleaning that worktree up.

Useful tuning flags:

```bash
kimbho run "fix the failing test suite" --max-agent-steps 10 --max-repair-attempts 3
kimbho resume --execute --max-auto-tasks 2 --max-repair-attempts 3
```

Useful parity-oriented flags:

```bash
kimbho --profile local-dev "summarize this repo"
kimbho -c 'sandboxMode="read-only"' exec --output-format json "explain the current diff"
kimbho --add-dir ../shared-lib --full-auto run "wire the shared package into this app"
```

## Notes

- The published CLI bundles the internal Kimbho packages so installation does not depend on the monorepo layout.
- Brain and provider configuration is stored in `.kimbho/config.toml` with optional `.kimbho/config.local.toml` overrides.
- Use `kimbho models use <model> --provider <id> --set-default` to select a provider model for the whole system.
- Use `kimbho brains assign --role <role> ...` only when you intentionally want an advanced per-role override.