Khive is an opinionated toolbox that keeps multi-language agent projects fast, consistent, and boring-in-a-good-way. One command -
khive- wraps all the little scripts you inevitably write for formatting, CI gating, Git hygiene and doc scaffolding, then gives them a coherent UX that works the same on your laptop and inside CI.
- Core Philosophy
- Quick Start
- Setup
- Command Catalogue
- Usage Examples
- Configuration
- Prerequisites
- Project Layout
- Contributing
- Single entry-point →
khive <command> - Convention over config → sensible defaults, TOML for the rest
- CI/local parity → the CLI and the GH workflow run the same code
- Idempotent helpers → safe to run repeatedly; exit 0 on "nothing to do"
- No lock-in → wraps existing ecosystem tools instead of reinventing them
# 1 · clone & install
$ git clone https://github.com/khive-ai/khive.d.git
$ cd khive
$ uv pip install -e . # editable install - puts `khive` on your PATH
# 2 · bootstrap repo (node deps, rust fmt, git hooks, …)
$ khive init -v
# 3 · hack happily
$ khive fmt --check # smoke-test formatting
$ khive ci --check # quick pre-commit gateTo use the information retrieval and LLM consultation features, you'll need to set up the following API keys:
- PERPLEXITY_API_KEY and EXA_API_KEY for
khive info searchto work - OPENROUTER_API_KEY for
khive info consultto work
You can set these as environment variables or add them to a .env file in your
project root.
For document reading capabilities:
# Install reader dependencies
$ pip install "khive[reader]"
# Or install all optional dependencies
$ pip install "khive[all]"| Command | What it does (TL;DR) |
|---|---|
khive init |
Verifies toolchain, installs JS & Python deps, runs cargo check, wires Husky hooks. |
khive fmt |
Opinionated multi-stack formatter (ruff + black, cargo fmt, deno fmt, markdown). |
khive commit |
Stages → (optional patch-select) → conventional commit → (optional) push. |
khive pr |
Pushes branch & opens/creates GitHub PR (uses gh). |
khive ci |
Local CI gate - lints, tests, coverage, template checks. Mirrors GH Actions. |
khive clean |
Deletes a finished branch locally & remotely - never nukes default branch. |
khive new-doc |
Scaffolds markdown docs (ADR, RFC, IP…) from templates with front-matter placeholders. |
khive reader |
Opens/reads arbitrary docs via docling; returns JSON over stdout. |
khive info |
Information service for web search (info search) and LLM consultation (info consult). |
Run khive <command> --help for full flag reference.
# format *everything*, fixing files in-place
khive fmt
# format only Rust & docs, check-only
khive fmt --stack rust,docs --check
# staged patch commit, no push (good for WIP)
khive commit "feat(ui): dark-mode toggle" --patch --no-push
# open PR in browser as draft
khive pr --draft --web
# run the same CI suite GH will run
khive ci
# delete old feature branch safely
khive clean feature/old-experiment --dry-run
# spin up a new RFC doc: docs/rfcs/RFC-001-streaming-api.md
khive new-doc RFC 001-streaming-api
# open a PDF & read slice 0-500 chars
DOC=$(khive reader open --source paper.pdf | jq -r .doc_id)
khive reader read --doc "$DOC" --end 500
# search the web using Exa
khive info search --provider exa --query "Latest developments in rust programming language"
# consult multiple LLMs
khive info consult --question "Compare Python vs Rust for system programming" --models openai/gpt-o4-mini,anthropic/claude-3.7-sonnetKhive reads TOML from your project root. All keys are optional - keep the file minimal and override only what you need.
[tool.khive fmt]
# enable/disable stacks globally
enable = ["python", "rust", "docs", "deno"]
[tool.khive fmt.stacks.python]
cmd = "ruff format {files}" # custom formatter
check_cmd = "ruff format --check {files}"
include = ["*.py"]
exclude = ["*_generated.py"][tool.khive-init]
# selective steps
steps = ["check_tools", "install_python", "install_js", "cargo_check"]
# extra custom step - runs after built-ins
[[tool.khive-init.extra]]
name = "docs-build"
cmd = "pnpm run docs:build"Khive helps you install tooling but cannot conjure it from thin air. Make sure
these binaries are reachable via PATH:
- Python 3.11+ &
uv - Rust toolchain -
cargo,rustc,rustfmt, optionalcargo-tarpaulin - Node + pnpm - for JS/TS stacks & Husky hooks
- Deno ≥ 1.42 - used for Markdown & TS fmt
- Git + GitHub CLI
gh- Git ops & PR automation - jq - report post-processing, coverage merging
Run khive init --check to verify everything at once.
The khive project is organized into several key directories:
khive/
├── src/khive/ # Main source code
│ ├── cli/ # CLI entry points and command implementations
│ ├── commands/ # Command adapters and business logic
│ ├── services/ # Core services (info, reader, etc.)
│ │ ├── info/ # Information service (search, consult)
│ │ └── reader/ # Document reader service
│ ├── connections/ # API connection handling
│ ├── providers/ # Provider-specific implementations
│ ├── protocols/ # Interface definitions
│ ├── prompts/ # Templates and prompts
│ └── third_party/ # Third-party integrations
├── docs/ # Documentation
│ ├── commands/ # Command-specific documentation
│ └── ... # General documentation
├── tests/ # Test suite
└── ... # Configuration files, etc.
The architecture follows a modular design where:
cli/contains the command-line interfacescommands/contains the business logic for each commandservices/contains the core services that power the commands- Each command exposes a
cli_entry()function that serves as its entry point
- Fork → branch (
feat/…) → hack khive fmt && khive ci --checkuntil greenkhive commit "feat(x): …"+khive pr- Address review comments → squash-merge ☑️
We follow Conventional Commits and semantic-release tagging.
For more detailed contribution guidelines, see CONTRIBUTING.md.