bonkers

A small CLI that assembles Bonkers-style prompts for code agents. By default it emits JSON only: system text, user messages, tool declarations, and metadata. It can also run that prompt through OpenAI, Ollama, or Codex.

Install

npm install -g @choas/bonkers

Bonkers is Bun-based, so bun must be available on PATH when the bonkers executable runs.

Usage

bun run bin/bonkers review --base main --head HEAD
bun run bin/bonkers ask --question "How does authentication work?" --paths "src/auth/**" "docs/**"
bun run bin/bonkers plan --task "Move profile reads from REST to GraphQL"
bun run bin/bonkers ask --question "Summarize this repo" --run --text
bun run bin/bonkers ask --question "Summarize this repo" --provider ollama --model <installed-model>
bun run bin/bonkers ask --question "Inspect this repo with Codex tools" --provider codex --text --verbose
OPENAI_API_KEY=... bun run bin/bonkers review --provider openai --model <openai-model>

Use --pretty for formatted output. All commands write JSON to stdout and errors to stderr. Context warnings are included in the JSON metadata so stdout remains pipe-friendly.

Commands

• review: builds a PR/local-diff review prompt from --base, --head, title/description, diff, and selected context files.
• ask: builds a repository Q&A prompt from --question and context hints.
• plan: builds a planning and implementation prompt from --task, constraints, and context hints.

Add --run to execute with the configured provider/model, or pass --provider openai, --provider ollama, or --provider codex to override the provider. Provider runs return JSON with output_text, tool_calls, stop_reason, and prompt metadata by default. Add --text to print only the final model text, or --json / --full-json to request the full JSON response explicitly.

OpenAI uses the Responses API and OPENAI_API_KEY by default. Ollama uses the configured ollama_host, OLLAMA_HOST, or http://localhost:11434. Codex uses codex exec, captures the final answer with --output-last-message, and delegates file/shell tool calls to Codex itself.

Use --verbose with --run or --provider to log LLM rounds and tool calls to stderr while keeping stdout reserved for the text or JSON result. Codex web-search logs include the query and a domain summary when domains can be inferred from Codex events or the final answer.

Local tools

When OpenAI or Ollama asks for a tool call, the CLI handles these tools locally:

• read_file: reads a repository-relative UTF-8 text file.
• search: searches text files by literal query or regex.
• run_tests: runs the requested command, or the configured repo.test_command if omitted.
• run_command: runs a repository command for build/lint/inspection.

File tools reject absolute paths and paths that escape the repository root. Shell tools run from the repository root and use configurable limits:

--max-tool-rounds 6
--tool-timeout-ms 120000
--max-tool-output-bytes 60000

Configuration

Optional config is loaded from bonkers.config.json, bonkers.config.yaml, or bonkers.config.yml in the current directory. Legacy bonk.config.* files are still accepted. You can also pass --config <path>.

{
  "persona": {
    "name": "Bonkers",
    "style": {
      "strictness": "medium",
      "tone": "direct",
      "prefers_bullets": true
    }
  },
  "repo": {
    "language": "typescript",
    "test_command": "pnpm test",
    "build_command": "pnpm build"
  },
  "llm": {
    "provider": "ollama",
    "model": "gemma4:31b-cloud",
    "ollama_host": "http://localhost:11434",
    "api_key_env": "OPENAI_API_KEY",
    "codex_path": "codex",
    "codex_sandbox": "workspace-write"
  },
  "tools": {
    "read_file": true,
    "search": true,
    "run_tests": true,
    "run_command": true
  }
}

The project is intended to run with Bun. Runtime dependencies are intentionally small and pinned exactly: Valibot validates provider API responses, and Micromatch handles glob matching.