brnrd

https://github.com/user-attachments/assets/2357758c-fa35-47ba-92b1-f02d51c338e3

---

Your CLI agents can already work in your repositories, shells, and local tooling. What they don't have by default is a continuing place on your machine. brnrd gives them 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 gives you a persistent resident you can reach when you are away from the terminal, including when work spans repositories.

How is this different from Claude Code's remote control or Codex cloud? Those give you a session you can reach. brnrd gives your machine a resident: a continuing identity with working memory, a playbook, and a standing agenda that outlive any single run, repository, or 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	A resident persists on your machine with working memory and a playbook; repository context is brought in for the work at hand. 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, Codex, or Grok. 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    Codex    Grok
      │        │        │
      └────────┼────────┘
               ▼
   progress · replies · git

The daemon does the boring, load-bearing work around the model: it routes incoming events, assembles the context relevant to a run (including repository context when needed), selects an execution environment, maintains continuity across runs, exposes live control surfaces, and routes results back through the gate. Git provides durable work receipts where appropriate.

✦ What problems does it solve?

• Keep Claude Code or Codex reachable after the terminal session ends. A daemon on a machine you control receives work through supported gates and launches CLI runners. The machine still needs to be powered on.
• Work across projects without resetting the resident. The resident's continuity is not defined by a single repository; individual tasks can still select repositories and execution environments.
• Use existing CLI-agent subscriptions. brnrd invokes supported CLI harnesses rather than requiring a separate LLM inference API key. Provider subscriptions, quotas, and account terms still apply.
• Follow and redirect long-running work. Chat gates and the dashboard expose progress; interactions are coordinated at runner boundaries, not injected into an arbitrary running model token stream.

For the architectural distinction between machine residency, repository context, and individual sessions, see Machine residency.

✦ Quickstart

Install the command:

curl -LsSf https://hugimuni-labs.github.io/brnrd/install.sh | sh
# or: npm install -g brnrd         # if you have Node
# or: uv tool install brnrd
# or: pipx install brnrd
brnrd --version

Then start the loom, brnrd's runtime, as a login service:

brnrd loom install       # launchd or systemd --user; prints what it installed

Install → Run the loom has the rest. The earlier runtime, the daemon, still works; you need only one. Self-hosted gates and local execution are free — no brnrd account is needed. For the daemon, pick your door.

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

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

Each run uses an execution environment. These environments 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
Machine residency	why a resident is not a repo, model, or session
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.

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.