Modes and approvals

Every file change, command, web fetch and MCP tool the agent wants goes through one check. Depending on the mode and your rules, it runs, asks you first, or is refused.

The four modes

Press Shift+Tab to cycle through them. The status line shows the current mode in its own color.

In every mode, reading files inside the project and running read-only commands (such as ls, git status or cat) never ask.

In Plan mode the agent looks around and writes a plan. When it is done, bitsrun asks Carry out this plan? and lets you choose the mode to continue in, or No, keep planning.

bitsrun remembers the last mode you chose for each folder, whether you chose it in the terminal, the dashboard or a phone. Start a single session in another mode with --mode:

bitsrun --mode plan

Answering an approval

When the agent asks, the status line shows Waiting for you and the question offers:

• Yes: do it this once.
• Yes, and accept edits from now on (for a file edit): switch to Accept edits mode.
• Yes, and don't ask again for ... (for a command, fetch or tool): saves an allow rule for this project, such as shell(npm test*). It is stored in your config folder, never in the repository.
• No (or Esc): the agent stops and waits for your next message instead of trying another way.

With remote control on, the same question appears on your phone, and you can answer it there. See Remote control.

What always asks

Some actions ask you even in Auto mode, and even when an allow rule would cover them:

• Credential files: reading or writing files such as .env, .npmrc, .netrc, private keys (id_rsa, *.pem, *.key) and anything in ~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, ~/.docker and similar folders. Example files like .env.example do not count.
• Paths outside the project folder.
• Risky commands, with the reason shown in the question. For example, commands that:
  • run as another user (sudo)
  • pipe downloaded or generated text into a shell or interpreter
  • read secrets or print the environment
  • push, force-reset or delete git history and branches
  • publish packages or images, or delete cloud resources
  • change the system (disks, services, scheduled jobs, passwords)
  • delete files outside the project, the whole project, or many files at once

A deny rule always wins over everything else.

Permission rules

Rules let you decide in advance. Write them in settings.json in your config folder (yours, for every project) or in .bitsrun/settings.json in a project (shared with your team, used only once you trust the project):

{
  "permissions": {
    "allow": ["shell(npm test*)", "shell(npm run lint)", "edit(src/**)", "fetch(domain:docs.python.org)"],
    "deny": ["read(secrets/**)", "shell(git push*)", "mcp(github__delete_repo)"]
  }
}

A rule without parentheses, like shell, matches every action of that kind.

Project trust

A repository you clone could carry instructions or allow rules meant to steer the agent, so bitsrun treats these files as untrusted until you say yes:

• BITSRUN.md and AGENTS.md (project instructions)
• .bitsrun/settings.json (rules, hooks and MCP servers)
• .bitsrun/commands/ (custom commands)

The first time you open such a folder, bitsrun lists the files, shows any allow rules, the exact commands its hooks would run and its MCP servers, then asks Use them? Only say yes for projects you trust. If you say no, the session runs without them; deny rules still apply. If any of those files change later, bitsrun asks again.

Headless runs cannot ask, so they use a project's files only if you trusted them before, or when you pass --trust-project. See Headless runs.

Files the agent changed by itself are undoable

Before the agent first changes a file in a turn, bitsrun keeps a copy. That is what makes Auto mode safe to try: any turn can be rewound. Changes made by shell commands are not tracked. See Sessions, rewind and undo.