BharatCode

Getting Started

Quick Start

From zero to your first edit in under a minute. Point BharatCode at a model, start the terminal UI, and type a prompt — or run a fully local session with Ollama where your code never leaves your machine.

This page assumes you already have the bharatcode binary on your PATH. If not, head to Installation first — one line with Homebrew, npm, or the install script. You can confirm the install at any time:

verify the installbash
bharatcode version

BharatCode needs a model to talk to. You have two ways to start: a hosted open-weight provider (one environment variable), or a fully local model with Ollama (no key, no network). Pick whichever fits — both reach a working session in the same number of steps.

Your first run with a hosted provider

Open-weight providers like DeepSeek are first-class in BharatCode. Each provider reads its API key from an environment variable, so the only setup is exporting one key. Using DeepSeek as the example:

set a provider keybash
export DEEPSEEK_API_KEY=sk-your-key-here

Now launch the interactive terminal UI. Running bharatcode with no subcommand starts the TUI in your current directory:

start the TUIbash
bharatcode

Type a request at the prompt and press Enter. BharatCode plans the work, calls its tools to read and edit real files, and shows you a diff before anything is written to disk:

bharatcode — ~/project
# in the TUI, type a prompt
add input validation to the signup handler
Reading internal/api/signup.go …
Proposing edit to internal/api/signup.go (review the diff)
✓ applied · DeepSeek · ₹0.42 this session

Switching models

Use the /model slash command inside the TUI to pick a different provider or model for the current session, or run bharatcode models to list everything configured. See Providers & Models for the full list and how to add your own.

A fully local run with Ollama

If you want your source code to never leave your machine, run against a local model. BharatCode supports Ollama and LM Studio as local providers — there is no API key and no outbound network call to a hosted endpoint. Start with Ollama running locally:

pull any local coding model, then serve it with Ollamabash
ollama pull qwen2.5-coderollama serve

With the Ollama provider configured (see Providers & Models), just start the TUI as before — no key needed:

start the TUIbash
bharatcode

Inside the session, use /model to select your local model, then work exactly as you would with a hosted provider. Every token is processed locally, so this is the path for air-gapped machines and code that must stay on-device.

Data stays in India — or on your machine

BharatCode never phones home. It connects only to the model endpoints you configure. A local provider keeps everything on your machine; a hosted open-weight or India-hosted provider keeps your data with a model you chose.

Headless mode for scripts and CI

Outside the TUI, bharatcode run executes a single prompt non-interactively and prints the result. This is the building block for scripts, git hooks, and CI jobs:

one-shot promptbash
bharatcode run "fix the failing test"

Structured events with --json

For automation, add --json to emit a stream of newline-delimited JSON (NDJSON) events instead of human-readable output. Each line is a complete JSON object, so you can pipe it straight into a log processor or parse it line by line:

NDJSON event stream for CIbash
bharatcode run --json "fix the failing test"

To capture just the agent's final answer to a file — handy for posting a summary back to a PR or storing a result — add --output-last-message:

write the final message to a filebash
bharatcode run --output-last-message result.txt "fix the failing test"

CI tip

Combine headless mode with permission modes and the INR budget gate so an automated run can only touch what you allow and can't blow past a monthly spend cap.

Resuming a session

BharatCode keeps your sessions, so you can pick up where you left off. The --continue flag resumes the most recent session with its full history intact:

resume the latest sessionbash
bharatcode --continue

Inside the TUI you can also browse and restore older sessions with the /sessions command, or branch the current one into a new line of work with /fork. See Sessions & Fork for the details.

A quick tour of the TUI

The interactive UI has three things to know: the chat transcript, the prompt input, and a footer that always shows your session cost in rupees. Everything else is driven by slash commands.

  • Chat transcript. Your messages, the agent's reasoning, tool calls, and proposed diffs scroll here. File edits are shown as diffs you can review before they land.
  • Prompt input. Type a request, or start a line with / to run a slash command.
  • INR cost footer. A running, rupee-denominated cost ledger for the session, so spend is always visible. Pair it with a monthly budget gate.
bharatcode — ~/project
you › refactor the auth middleware
bharatcode › editing internal/auth/middleware.go …
✓ 1 file changed · diff shown above
────────────────────────────────────────────
DeepSeek · read-only · session ₹1.27 / ₹500 budget

Slash commands

Slash commands run from the prompt and control the session itself. A few you'll reach for immediately:

  • /help — list every available command.
  • /model — switch the provider or model for this session.
  • /diff — review pending changes; /status — see session and context state.
  • /permissions — change the approval mode between read-only, auto, and full.
  • /goal — set and run an autonomous, bounded task loop; learn more.
  • /clear to reset the conversation, /save to persist it, and /quit to exit.

You can also define your own /<name> prompts as Markdown files in ~/.bharatcode/prompts/. The full list — including /agent, /fork, /budget, /yolo, and custom prompts — lives in TUI & Slash Commands.

Next steps