bitsrun coding agent

The bitsrun coding agent works in your terminal, inside your project folder. You describe a task in plain words, and it reads your files, searches the code, proposes edits as diffs, runs commands such as your tests, and keeps going until the task is done or it needs you. It is free, and it is part of the same bitsrun program you use to deploy models.

What bitsrun can do

• Any model, your choice: BitsRun endpoints, 11 popular providers, many more from a catalog, any compatible URL, or Ollama, LM Studio, llama.cpp and vLLM on your computer. Models and providers
• Switch models mid-session with /model, and add one with /connect. Models and providers
• Reads, searches and edits your code with diffs you see first. Tools the agent has
• Runs commands such as tests and builds, including servers kept running in the background. Tools the agent has
• Four modes (Manual, Accept edits, Auto, Plan) decide what it does without asking. Modes and approvals
• Allow and deny rules per project, saved from a "don't ask again" answer or written in settings. Permission rules
• Protects credentials: risky commands, credential files and paths outside the project always ask, even in Auto. What always asks
• Project trust: instructions, rules, hooks and servers from a cloned repo are used only after you say yes. Project trust
• Project instructions in BITSRUN.md (or AGENTS.md), and # adds a line from the prompt. Project instructions
• @ file mentions with Tab completion, and images pasted with Ctrl+V or dragged in. Files and images
• ! runs a command yourself and shares its output with the model. The ! and # prefixes
• A prompt editor that works in every terminal: history, history search, multi-line input, word and line editing, $EDITOR. Editing your prompt
• Large pastes stay intact, shown as a short marker and sent byte for byte. Pasting
• The number pad works, with Num Lock on or off, in every tested terminal. The number pad
• Full-screen view with mouse selection that copies on release, even over SSH and tmux, or the classic view with --classic. Selecting and copying
• /copy puts the last answer on your clipboard as plain text. Selecting and copying
• Every key can be rebound in keybindings.json. Keybindings
• A status line that is never blank while it works: what it is doing, time, speed. The status line
• Subagents take a big search or a side job into their own fresh context and report back. Subagents
• Sessions are saved: continue with -c, pick one with -r or /resume, start fresh with /clear. Sessions
• Rewind and undo: go back to an earlier message with its files, or undo the last changes. Rewind and undo
• Automatic compaction keeps long conversations inside the model's memory, or run /compact. Compaction
• MCP servers add tools, over stdio or Streamable HTTP. MCP servers
• Hooks run your own scripts before and after its actions, and can block them. Hooks
• Custom slash commands from Markdown files in .bitsrun/commands/. Custom commands
• Headless runs for scripts and CI with -p, text or JSON output and an exit code. Headless runs
• Keeps your BitsRun endpoint awake while you work, for as long as you choose. Using a BitsRun endpoint
• Remote control: /remote (or /rc) lets you follow, prompt and approve from your phone or the dashboard, end-to-end encrypted. Remote control

Tools the agent has

These are the actions the model can ask for. Each one goes through the same approval check (see Modes and approvals).

Tools from MCP servers appear beside these, named mcp__<server>__<tool>.

Subagents

For a large search across the codebase or a separate piece of work, the agent can start a subagent with the task tool. A subagent has its own fresh conversation, the same tools and the same approvals, and returns only its final report, so the main conversation stays short. Subagents cannot start their own subagents, and each one stops after 30 steps. Remote control shows how many are running.

A safety stop

If the model takes 60 steps in a row without answering you, bitsrun pauses and asks whether to keep going. It also notices a model repeating the same call over and over.

Start it

1. Install bitsrun if you have not yet. See Install and sign in.

2. Open a terminal in your project folder and type:

   bashCopy

   bitsrun

3. The first time, bitsrun asks you to set up a model. You choose it; there is no default. Pick BitsRun to use one of your endpoints or deploy one, a server already running on your computer, or another provider with your own API key.

4. If the folder has files that steer the agent (such as BITSRUN.md or .bitsrun/settings.json), bitsrun lists them and asks whether to use them. Say yes only for projects you trust.

5. Type what you want done and press Enter.

> Add a --dry-run option to scripts/sync.ts and a test for it

While it works, the status line under the prompt always shows what is happening: what it is doing (for example Editing scripts/sync.ts), how long it has been working, the speed in tokens per second, and that Esc stops it.

Commands inside the agent

Type / to see this list with a hint for each, then use the arrow keys and Enter, or Tab to complete.

Press ? on an empty prompt to see every key. Keys, input and copying explains them.

Options when you start it

bitsrun code works too and accepts the same options. bitsrun code connect sets up a model without starting a session, and bitsrun code keytest shows exactly which keys your terminal sends.

Project instructions

Put notes for the agent in a BITSRUN.md file at the root of your project: how to run the tests, code style, folders to leave alone. bitsrun reads it at the start of every session, and also reads AGENTS.md if you already have one. To add a line without opening the file, start your prompt with #:

> #Run tests with npm test, never with npx jest

Using a BitsRun endpoint

When your model is a BitsRun endpoint, bitsrun wakes it as soon as the session opens, so it is usually ready by the time you finish typing. The first prompt waits while it starts (shown as Booting up), and that start-up time is never billed.

While you work, bitsrun keeps the endpoint awake so it does not fall asleep between prompts. After 15 minutes without activity it stops, and the endpoint sleeps after its own idle time. Time awake is billed per second as usual, so shorten the window with --keep-awake 5m, or set "keepAwake": "5m" in settings.json in the config folder. For long sessions, priority or always-on shortens or removes the wait.

Where bitsrun keeps its files

Set BITSRUN_CONFIG_DIR to use another config folder. Your prompts, code and answers go only to the model provider you chose; sessions stay on your computer.