CODE-BRO_CLI

A dependency-free Node.js CLI that turns local or cloud LLMs into a coding agent. It can inspect a project, create or edit files, run safe commands, read failures, and iterate from one prompt through an opencode-style terminal interface.

CODE-BRO_CLI runs tasks through a coworker-style orchestrator: it classifies the prompt, lets the agent act, verifies the result, and runs one repair pass when the result does not match reality.

Requirements

• Node.js 18 or newer
• For local models: Ollama running locally and a pulled model, for example:

ollama pull llama3.1

• For cloud models: an OpenAI-compatible API key such as OPENAI_API_KEY or OPENROUTER_API_KEY.

Usage

Install globally after publishing to npm:

npm install -g code-bro-cli
code-bro
code-bro run "explain this repo"

Or install from a local package tarball:

npm pack
npm install -g ./code-bro-cli-0.1.0.tgz
code-bro

Run from this folder while developing:

node ./bin/ollama-agent.js
node ./bin/ollama-agent.js run "explain this repo"
node ./bin/ollama-agent.js run "create a todo app with local storage"
node ./bin/ollama-agent.js explain this repo

Use a cloud model through an OpenAI-compatible provider:

$env:OPENROUTER_API_KEY="your-key"
node ./bin/ollama-agent.js run "explain this repo" --provider openrouter -m openai/gpt-4o-mini

Claude-family models can be used through OpenRouter when your account exposes them. List available IDs with CODE-BRO_CLI models openrouter, then switch with /model openrouter/<model-id> or pass -m openrouter/<model-id>.

Or with OpenAI:

$env:OPENAI_API_KEY="your-key"
node ./bin/ollama-agent.js run "create a todo app" -m openai/gpt-4o-mini

Run the offline smoke path without Ollama:

node ./bin/ollama-agent.js run "create smoke file" --mock
npm test

Or link it globally:

npm link
code-bro
code-bro run "explain this repo"
code-bro create a portfolio site
code-bro changes
code-bro preview path/to/site

Legacy aliases remain available:

CODE-BRO_CLI
ollama-cli
oagent
ollama-agent

Inside the interactive CLI, type /models to open an arrow-key model picker for the active provider. Use Up/Down to move through the list and Enter to select the highlighted model. Use /models ollama, /models openai, or /models openrouter to switch provider lists before selecting. Ollama shows installed local models first, then suggested Ollama candidates you can test. OpenAI shows live models only when an API key is configured. OpenRouter shows live models with an API key, otherwise only explicitly free suggested models. You can still switch directly with /model ollama/gemma4:31b-cloud.

While a task is running in the interactive CLI, press Esc to cancel it and return to the prompt.

You do not need to choose a mode. Type the request naturally: explain/read-only prompts run safely, create/build/add prompts can write files, and fix/debug/error prompts use the repair flow.

Use where is context.md, /where context.md, or find context.md in the interactive CLI to locate a file in the project folders and preview it immediately.

Use /tree to show a compact project tree, and /open file.md to locate, preview, and open a file in the OS editor. Runs are saved in .code-bro/sessions/; use /sessions to list them, /session <id> to load one in the TUI, --session <id> to load one from a command, or --continue/-c to include the last session summary and changes in the next request.

Use /changes or CODE-BRO_CLI changes to show the files from the last saved session with full paths. Use /open-created or CODE-BRO_CLI open-created to open the first created file or folder from the last session.

For static HTML/CSS/JS projects, use /preview [path] in the interactive CLI or CODE-BRO_CLI preview [path] from a terminal. The command serves the file or folder locally and prints a http://127.0.0.1:... URL.

When the agent writes a file, the write tool verifies the file exists on disk before reporting success. Change summaries include the workspace path and byte counts when available, so it is easier to see exactly where output landed.

The orchestrator also verifies recorded file changes after each task. For fix/test prompts, it detects project scripts such as npm run check and npm test, runs them, and sends failures back through one repair attempt.

Optional config files are supported at the project root:

{
  "provider": "ollama",
  "model": "gemma4:31b-cloud",
  "autoApprove": false
}

Options

-m, --model <provider/model>  Model selector, for example ollama/gemma4:31b-cloud
-p, --provider <name>         ollama, openai, or openrouter. Default: ollama
--host <url>                  Ollama host. Default: OLLAMA_HOST or http://127.0.0.1:11434
--timeout <seconds>           Per-model response timeout. Ollama cloud-like models default to 45.
--base-url <url>              Cloud OpenAI-compatible base URL
--api-key-env <name>          Environment variable containing the cloud API key
--prompt <message>            Initial prompt for interactive mode
--continue, -c                Continue with the last saved session context
--session, -s <id>            Load a specific saved session context
-r, --root <path>             Project root. Default: current directory
--steps <number>              Optional max tool/reasoning steps. Default: unlimited
-y, --yes                     Auto-approve shell commands marked risky
--dry-run                     Show intended writes without changing files
--mock                        Use a deterministic offline model for smoke tests

Tools

The agent can use:

• list_files
• read_file
• write_file
• create_file
• replace_in_file
• patch_file
• apply_patch
• delete_file
• delete_directory
• move_file
• rename_file
• make_directory
• search_files
• run_command

Shell commands are guarded by a safety layer. Common build/test/read commands are allowed by default. Risky commands are blocked unless you pass --yes.

Current Scope

This is an MVP agent loop. It uses plain JSON messages instead of native tool calling so it works across Ollama and OpenAI-compatible cloud providers. Stronger models will follow the JSON tool protocol more reliably.

Ollama cloud-like models such as gemma4:31b-cloud can be slow or fail to respond. The CLI uses a shorter default timeout for those models so the terminal does not wait for two minutes. Pass --timeout 120 if you explicitly want to wait longer.