BharatCode

Usage

Sessions & Fork

Every conversation with BharatCode is a session, and every session is saved automatically to a local database on your machine. You never lose your place: resume where you left off, jump back into an older conversation, or branch a new line of exploration from a known-good point — all without losing the original.

Persistent sessions

Sessions in BharatCode are persistent by default. The moment you start talking to the agent — in the interactive TUI or via bharatcode run — a session is created and every turn of the conversation is written to a local SQLite database as it happens. There is no separate “save” step to remember: the history, the messages, the tool calls, and the edits are all recorded so that nothing is lost if you close the terminal or your machine restarts.

Because the store is SQLite, your sessions live entirely on your own machine as a single self-contained file — no server, no account, and no data leaving your laptop. That is the same data-stays-local principle that runs through the rest of BharatCode.

Local & private

Session history is stored locally in SQLite. It is yours: you can back it up, copy it between machines, or delete it like any other file. BharatCode does not sync your conversations anywhere.

Resume the latest session

The fastest way to pick up where you left off is to launch with --continue. It reopens the most recently active session in the current directory and drops you straight back into the conversation, with its full history intact.

terminalbash
bharatcode --continue

This is the right command for the common case: you were working on something, stepped away, and want to keep going. No need to find or name the session — --continue always takes the latest one.

Pick a past session

When the latest session is not the one you want, use /sessions from inside the TUI. It opens a picker listing your saved sessions so you can browse and restore any one of them, continuing that conversation exactly where it ended.

bharatcode TUItext
/sessions

Think of /sessions as the deliberate counterpart to --continue: instead of always taking the most recent session, you choose which one to reopen. It is also where you go to revisit an exploration you forked off earlier.

From the shell vs. in the TUI

Use bharatcode --continue when you know you want the latest session and want to skip the picker entirely. Use /sessions when you are already in the TUI, or when you want to choose an older conversation rather than the most recent one.

Branch an exploration with /fork

Forking is how you try something without putting your current conversation at risk. Running /fork creates a new session that copies the history of the current one up to this point, and switches you into it. The original session is left completely untouched — you can always go back to it with /sessions.

bharatcode TUItext
/fork

Because the fork starts as an exact copy, the agent keeps all the context it had built up — the files it has read, the decisions made so far — but anything you do next happens only in the branch. This makes /fork ideal for:

  • Trying a riskier or more aggressive change from a known-good point, with a clean way back if it does not pan out.
  • Exploring two approaches in parallel — fork once per approach and compare the results.
  • Asking a tangential question without polluting the main thread, then returning to the original to keep going.

Fork vs. clear

/fork keeps the conversation history and copies it into a new branch, so the agent retains its context. /clear is different: it starts a fresh context in place, dropping the prior conversation rather than branching from it.

List your sessions

To see your saved sessions from the shell — without opening the TUI — run the sessions subcommand:

terminalbash
bharatcode sessions

This lists the sessions BharatCode has on record, which is handy for getting an overview, scripting, or confirming that a session you expect is actually there. To reopen the most recent one, follow up with bharatcode --continue; to choose a specific one interactively, launch the TUI and use /sessions.

Where the database lives

All of your sessions live in a single SQLite database file in BharatCode's data directory, following the XDG base-directory spec:

session databasetext
~/.local/share/bharatcode/bharatcode.db # or, when $XDG_DATA_HOME is set:$XDG_DATA_HOME/bharatcode/bharatcode.db

Note that this is your data directory (~/.local/share/), which is separate from your config directory at ~/.config/bharatcode/ where config.json lives. Sessions, messages, the per-session file-change history, and the INR cost ledger all share this one database, so it is the complete record of everything BharatCode has done on your machine. It is opened with modernc.org/sqlite, a pure-Go driver, which is part of why BharatCode ships CGO-free.

If you want to confirm the exact location on your system — paths can differ by OS and by environment — run the doctor check, which reports where BharatCode is reading its state from:

terminalbash
bharatcode doctor

Treat it like real data

bharatcode.db is the record of every conversation. Deleting it removes that history permanently, so if you rely on being able to resume older sessions, include ~/.local/share/bharatcode/ in your backups. Since it is one self-contained file, copying it is all it takes to move your sessions to another machine.

See also

  • TUI & Slash Commands — the full list of in-TUI commands, including /sessions and /fork.
  • Config files — the ~/.config/bharatcode/ config directory, distinct from the data directory your sessions live in.
  • CLI Reference — sessions, --continue, and the other subcommands and flags.