brnrd

Local agents go brr. From anywhere.
A co-maintainer that lives on your machine: survives reboots, remembers who it is, works both your Claude and Codex subscriptions, and leaves receipts — commits, PRs, a card you can read.

_{Needs a machine that's on: a laptop that doesn't sleep, a Mac mini, a home server, or a $5 VPS (about ten minutes to set up).}

1,941 commits on main · 1,360 by the resident · 1,115 merged PRs · since March 2026 · as of 2026-09-06.
This repo is built with brnrd, by brnrd. The git log is the demo.

brnrd-demo-cut-v6-gh.mp4

---

Your coding agent already lives where the work is: your repo, your shell, your credentials, the odd test setup, and all the context nobody put in the ticket. brnrd gives it a doorbell, a memory, and a live line back to you.

Send the task from your phone. Watch the plan and progress card change while it works. Correct course without interrupting the run. Get a branch, a PR, or an answer back in the same thread.

brnrd is not another coding agent. It runs the CLI agents you already chose — locally, under your rules — and turns them into a repo-knowing coworker you can reach when you are away from the terminal.

How is this different from Claude Code's remote control or Codex cloud? Those give you a session you can reach. brnrd gives the repo a resident: one identity per project, with working memory, a playbook, and a standing agenda that outlive any single run — and any single model. When Codex hit its quota wall mid-conversation on 2026-09-05, the seat continued on Claude with the same memory and the same open work. The vendors are the medium; the resident is the thing that persists.

✦ What you get

	Capability	What it actually means
📟	A remote door	Fire off a task from Telegram, Slack, GitHub, or the dashboard. The agent runs at home; you drive from your pocket.
🧠	A resident, not a reset	Each repo gets a coworker with working memory, project knowledge, and a playbook. A new run is the same mind's next thought — not an amnesiac subprocess wearing yesterday's name tag.
💬	Interrupt-free interaction	Follow the live plan and progress card. Add a fact or change direction at runner boundaries, without killing the thought in flight.
🔀	The model is a medium	Pin Claude or Codex. Escalate a core for a hard pass, downshift for grunt work, and see quota posture before it becomes a surprise.
🏠	Local means local	Your checkout, .git, and run execution stay on your machine. The one caveat — what the managed dashboard mirrors — is spelled out under Trust & privacy.
🧾	Git-native receipts	Every run ends somewhere durable: a branch, a PR, or an answer in the thread. The diff is the proof.
📁	The seams are files	Gates and live controls speak a small file protocol. A new transport is not a new religion for the daemon.

✦ The loop

            you, from anywhere
Telegram · WhatsApp · Signal · Slack · GitHub · web
               │
               ▼
  brnrd daemon · your machine
               │
          ┌────┴────┐
          ▼         ▼
     Claude Code  Codex
          │         │
          └────┬────┘
               ▼
   progress · replies · git

The daemon does the boring, load-bearing work around the model: it assembles the current repo context, selects an execution environment, keeps conversation continuity across runs, exposes live control surfaces, preserves the work in git, and routes the result back through the gate.

✦ Quickstart

Install the command:

npm install -g brnrd         # if you have Node
# or: uv tool install brnrd
# or: pipx install brnrd
brnrd --version

Self-hosted gates and local execution are free — no brnrd account is needed. Then pick your door.

Self-hosted — bring your own gate	Managed — one account across repos
brnrd gate setup telegram # auth + bind the current repo brnrd daemon install Nothing leaves your machine but the messages you route.	brnrd account connect # pair + install + start (systemd/launchd) brnrd account add . # add another repo later Connect also creates the account home and separate knowledge repository, prepares .brnrd-kb/, and creates or adopts private GitHub backups for both. Use --local-memory only when you explicitly want those Git repositories to remain on this machine.

Now send a message from the other side:

review PR #84 for the auth regression; show me the risky bit before changing it

The npm package is not a JavaScript port

brnrd is a Python program; the npm package is a launcher for it. On first run it builds a private, durable virtualenv under ~/.local/share/brnrd, installs brnrd into it, and hands over — your system Python is untouched. npm install -g brnrd leaves you a real brnrd command; npx brnrd <command> runs the same thing without one, so every later command must be npx brnrd … too.

✦ What arrives in a wake

The resident does not begin with "please inspect the repo." brnrd mounts a compact orientation layer before the task, so the agent wakes up somewhere instead of nowhere:

• the repo contract and current run facts;
• the resident's own working memory and playbook;
• recent project activity and the pitfalls relevant to this task;
• live queue, quota, delivery, and branch posture;
• the original request and the conversation that led to it.

The rest stays pull-based. Project knowledge can live in a private account home, a repo-owned knowledge base, or ordinary docs; the injected slice just points the resident at the longer tail when it needs it.

That split is the whole trick: enough continuity to wake up as someone, not so much prompt that the agent spends the morning rereading its diary.

✦ Where it runs

Every project chooses an execution environment. They are honest about what they isolate — none of them is a cage for a hostile agent (see Trust & privacy):

Mode	What it isolates	Reach for it when
host	Nothing beyond your own shell. Edits hit your working tree immediately.	you trust the agent and want zero friction — the dogfooded default.
worktree	A separate worktree and branch, so your working tree stays clean. Shares your .git, credentials, network, and filesystem — not a security boundary.	you want runs off your working tree without container overhead.
docker	Dependencies and network, and it narrows the agent's host-filesystem view to the repo plus mounted credential dirs. Not a credential or containment boundary: the repo is mounted read-write, your model/GitHub/SSH credentials cross in, and the network is on by default.	you want a clean toolchain or network control (docker.network=none) — defense-in-depth over a trusted agent, not a sandbox.
solitary	Provider-only egress and per-run copies of the selected Shell's credentials, with no GitHub credential handed in. The repo is still read-write.	a collaborator or untrusted-tier sender triggers the run — it's the default hardened environment for that tier (trust.untrusted_env, trust.collaborator_env).

Full isolation matrix: SECURITY.md · semantics: Environments · scope tracked in #80.

✦ Trust & privacy

No "military-grade" paragraph. brnrd runs coding agents that execute commands and edit files with the authority you grant them — the runners are launched with their approval prompts bypassed, on purpose. So the honest posture is the product:

• The agent has your authority. host mode is the same trust boundary as launching the CLI yourself. Any text brnrd ingests — an issue body, a PR comment, a chat message — becomes instruction the agent may act on. Treat every gate you open as a door into your shell.
• Gates authorize senders before enqueue. GitHub is default-closed: the self-hosted gate verifies write, maintain, or admin permission; the managed webhook accepts GitHub's signed OWNER, MEMBER, or COLLABORATOR association; both also support an explicit login allowlist. Telegram accepts the paired user plus explicitly allowlisted user ids; anonymous admins and channel posts are denied. Slack remains channel-scoped, so every member of a configured Slack channel can submit work. Authorization decides who may speak to the agent, not whether their text is safe — keep allowlists tight and route collaborators through trust.collaborator_env=solitary when they should not inherit your normal execution authority.
• Local stays local — with one honest caveat. Your checkout, .git, and run execution stay on your machine; with brnrd account connect, dashboard publishing continuously mirrors derived project knowledge—including any code quoted there—to brnrd.dev, but it does not read your source tree. Remote messages travel through the transport you choose and, in managed mode, transit brnrd.dev on the way to your daemon.
• Never paste credentials into a task. Configure them through the runner or gate.

The full threat model, the per-gate authorization table, and the honest environment isolation matrix live in SECURITY.md. The review is tracked under #23; execution and environment contracts are inspectable in the execution map and environment guide.

✦ Docs

The full guide — prerequisites, install, connect, first task, concepts, troubleshooting, CLI reference — lives at hugimuni-labs.github.io/brnrd. The pages below are deeper, implementation-facing notes for the pieces that guide doesn't unpack:

Portals	live interaction and handoff surfaces
Conversations	how continuity is recovered across runs
Environments	host, worktree, and Docker semantics
Execution map	what happens between message and reply
Account daemon	multi-repo / multi-account topology
brnrd docs	the docs that ship inside the tool

✦ Current posture

brnrd is alpha software, already used to build itself (the numbers at the top are git log on this repo — re-measured at each release by scripts/receipt_line.py). The resident loop, local daemon, managed Telegram path, live dashboard, runner switching, worktree/Docker execution, and git handoff are real. The public docs, multi-project proving, managed billing/failover, and some operational polish are still release work.

If you want a quiet appliance, wait. If you want a local agent coworker with a remote door — and you are willing to report the sharp edges — welcome in.

Build it yourself

Python 3.10+ and git are required.

git clone https://github.com/hugimuni-labs/brnrd
cd brnrd
pip install -e ".[dev]"
pytest

The repo dogfoods brnrd. Run brnrd up --dev-reload while changing the daemon so the next task picks up the new code without a process ritual.

License

The local runtime in src/brr/ is MIT. The managed backend and dashboard in src/brnrd/ and src/frontend/ are AGPLv3. You can run the complete stack yourself; the split protects the hosted surface without closing the part that lives on your machine. See LICENSE-OVERVIEW.md.