Agentic coding from the command line. Created by Suhas Bhairav.

Bhairav Code

A Python-first coding agent CLI built for real project work: model switching, plugin-style skills, custom agents, multi-agent orchestration, guarded file tools, shell execution, an API server, and a live UI mockup viewer.

Read documentation View GitHub

OpenAI, OpenRouter, Ollama, Anthropic-ready

Skills, tools, and agents as replaceable plugins

Live terminal activity feed with file edits and tests

Real-time design viewer for UI mockups

Animated Bhairav Code terminal interface showing live agent activity, model routing, files edited, and parallel project work

live terminal

$ bhairav-code --model gpt-5-nano --provider openai

scanReading pyproject.toml, app routes, tests, docs, and repository structure

thinkChoosing the model adapter and planning safe workspace edits

agentPlanner, Builder, Reviewer, and UI agents are assigned scoped work

editsrc/bhairav_code/core/config.py -> applying Bhairav Code env namespace

editREADME.md -> updating CLI, workspace, plugin, and model instructions

testpytest, ruff, docs build, and generated Python project E2E verification

doneCreated project, ran tests, summarized changes, and kept the user in the loop

OpenAI ready

OpenRouter ready

Ollama ready

Open-source product foundation

A command-line workspace that shows its work.

Bhairav Code is built in the spirit of modern coding agents such as Cursor, Claude Code, and OpenCode, but focuses on a Python-native terminal workflow where the user can see each planning step, active agent, file edit, shell command, validation pass, and project artifact as it happens.

Bhairav Code is an open-source terminal coding agent created by Suhas Bhairav. It lets developers create new Python projects, edit existing repositories, switch between model providers, define reusable skills, create custom agents, run multi-agent workflows, launch a mockup viewer, and verify work from the command line.

Terminal coding agent

Interactive chat mode and one-shot task mode with a branded rich terminal interface, markdown rendering, activity events, model context, workspace context, and tool summaries.

Replaceable plugin architecture

Models, providers, tool registry, skills, agents, terminal UI, API routes, and mockup viewer can be replaced or extended without rewriting the whole runtime.

Parallel multi-agent execution

Create specialized agents for planning, building, reviewing, testing, refactoring, UI design, documentation, and release work, then run them together and synthesize outputs.

Real-time UI mockup viewer

Launch a local browser studio with HTML and CSS editors, instant iframe preview, desktop/tablet/mobile modes, and saved mockups inside the project workspace.

Guarded workspace tools

Agents can inspect trees, list files, read files, write files, replace exact text, search repositories, run allowlisted commands, and stay inside the configured workspace.

Deterministic Python project generator

Create a tested Python package with pyproject.toml, source files, CLI entry point, operations module, README, and tests without relying on model randomness.

Parallel project execution

Live agents can run project work side by side.

mapping

Planner

Reads the repository, identifies constraints, chooses tools, and breaks the request into safe work units.

editing

Builder

Applies file edits, writes new modules, updates docs, and keeps changes scoped to the active workspace.

validating

Reviewer

Checks regressions, missing tests, command output, naming consistency, and production-readiness gaps.

Any-model routing

Use OpenAI, OpenRouter, Ollama, and Claude-style routes.

.env example

OPENAI_API_KEY=sk-...

OPENROUTER_API_KEY=sk-or-...

BHAIRAV_CODE_MODEL=gpt-5-nano

BHAIRAV_CODE_BASE_URL=https://api.openai.com/v1

BHAIRAV_CODE_OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

BHAIRAV_CODE_OLLAMA_BASE_URL=http://127.0.0.1:11434/v1

BHAIRAV_CODE_WORKSPACE=.

BHAIRAV_CODE_MAX_TOOL_ROUNDS=12

BHAIRAV_CODE_ALLOW_SHELL=false

OpenAI

OPENAI_API_KEYBHAIRAV_CODE_API_KEYBHAIRAV_CODE_MODELBHAIRAV_CODE_BASE_URL

Use GPT models for fast coding, planning, test writing, repo review, and OpenAI-compatible endpoints.

gpt-5-nanogpt-4.1gpt-4.1-minigpt-4o

OpenRouter

BHAIRAV_CODE_OPENROUTER_API_KEYOPENROUTER_API_KEYBHAIRAV_CODE_OPENROUTER_BASE_URL

Route to many hosted coding and reasoning models behind one OpenAI-compatible provider.

openrouter/anthropic/claude-sonnet-4openrouter/openai/gpt-5-nanoopenrouter/deepseek/deepseek-chat

Ollama

BHAIRAV_CODE_OLLAMA_BASE_URL

Run local models for private, offline, low-cost, or experimental coding workflows.

ollama/qwen2.5-coder:7bollama/llama3.1:8bollama/codellama:13b

Anthropic-ready

BHAIRAV_CODE_ANTHROPIC_API_KEY

Use the Anthropic provider slot for Claude-style model routes and future Claude-compatible adapters.

claude-sonnet-4claude-opus-4.1

Plugins, skills, agents

Skills and agents are filesystem plugins.

Bhairav Code stores reusable project behavior inside the target workspace, which makes teams able to version custom instructions, role definitions, and project-specific automation alongside code.

Skill .bhairav-code/plugins/*.json

Reusable instruction packs such as Python refactoring discipline, frontend review, documentation writing, security review, or release preparation.

Agent .bhairav-code/agents/*.json

Named coding roles with their own model, system prompt, attached skills, and shell policy.

Mockup .bhairav-code/mockups/*.json

Saved HTML/CSS design states rendered through the local UI mockup viewer.

Start chat in the current repository

bhairav-code chat --workspace .

Run a one-shot coding task

bhairav-code ask "Add tests for this module and run them" --workspace . --shell

Switch to OpenRouter

bhairav-code ask "Review this repository" --model openrouter/anthropic/claude-sonnet-4 --workspace .

Switch to Ollama

ollama pull qwen2.5-coder:7b

ollama serve

bhairav-code ask "Review this project" --model ollama/qwen2.5-coder:7b --workspace .

Launch the mockup viewer

bhairav-code mockups --workspace .

open http://127.0.0.1:8765/mockups

Create and test a Python project

bhairav-code projects create-python --workspace /tmp/bhairav-code-e2e --package-name calc_service

cd /tmp/bhairav-code-e2e

pytest

python -m calc_service multiply 6 7

Architecture and verification

Structured like a product, tested like a tool people can run.

CLI shell

Typer commands for chat, ask, models, skills, agents, mockups, server, and project generation.

Session engine

Agent runner controls planning rounds, tool calls, messages, events, and final responses.

Model router

Provider factory dispatches OpenAI-compatible, OpenRouter, Ollama, local fallback, and Anthropic routes.

Tool registry

Workspace-safe functions for file inspection, patching, searching, shell execution, and deterministic generators.

Skill loader

Plugin manager loads reusable skill prompts from workspace JSON manifests.

Agent graph

Multi-agent runner executes named agents and can synthesize raw outputs into a final answer.

Terminal UI

Rich-powered panels, status animations, live activity rows, command summaries, and branded copy.

Viewer bridge

FastAPI and static UI assets power the real-time browser mockup studio.

The project was tested end to end with linting, unit tests, Docusaurus docs build, and a generated Python package verification.

ruff check . -> all checks passed

pytest -> 16 passed

docs-site npm run build -> generated static docs successfully

bhairav-code projects create-python -> wrote pyproject, README, src package, CLI, operations module, and tests

generated project pytest -> 6 passed

python -m calc_service multiply 6 7 -> 42.0

calc-service subtract 9 4 -> 5.0

AEO and FAQ

Clear answers for people and answer engines.

What is Bhairav Code?

Bhairav Code is an open-source Python command-line coding agent for creating projects, editing existing repositories, running tests, switching model providers, and orchestrating multiple specialist agents.

How do I use Bhairav Code with an existing project?

Run bhairav-code from any directory and pass --workspace with the target path, or cd into the repository and run bhairav-code chat --workspace .

Can Bhairav Code use OpenAI, OpenRouter, and Ollama?

Yes. Bhairav Code has provider routing for OpenAI-compatible models, OpenRouter-hosted models, and local Ollama models configured through BHAIRAV_CODE_* and standard provider environment variables.

Does Bhairav Code support plugins and skills?

Yes. Skills, tools, agents, and model adapters are structured as replaceable modules so teams can add domain-specific behavior without rewriting the core runtime.

Does Bhairav Code include a UI mockup viewer?

Yes. The CLI can launch a Python-served UI design studio with live HTML and CSS editors, instant preview, desktop/tablet/mobile modes, and saved mockups.

Build with Bhairav Code

Clone it, run it, extend it, and make the terminal feel alive.

README Issues Suhas Bhairav