brnrd 0.2.1

Structured guardrails for AI agent work, managed from a chat

brnrd

Local agents go brr. From anywhere.
Claude Code and Codex on your machine — reachable from Telegram, Slack, GitHub, and the web.

---

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.

✦ 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; 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.
🧾	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 · Telegram / Slack / GitHub / dashboard
                         │
                         ▼
                  a small gate
                         │
                         ▼
        brnrd daemon · your machine · your repo
                         │
                 ┌───────┴───────┐
                 ▼               ▼
            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:

uv tool install brnrd        # recommended when uv is already present
# or: pipx install brnrd
# or: npx brnrd init         # bootstraps the Python package; leaves your system Python alone

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

Managed — one account across repos	Self-hosted — bring your own gate
brnrd account connect # pair + install + start (systemd/launchd) # via npx: npx brnrd account connect — bootstraps too, in one line brnrd account add . # add another repo later	brnrd gate setup telegram # auth + bind the current repo brnrd daemon install

Now send a message from the other side:

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

The first end-to-end demo is being recorded against the real product, not mocked into a terminal — follow #28.

npx brnrd is not a JavaScript port

It is a bootstrapper for the Python package. It keeps its own environment and leaves your system Python alone — a convenience for people who live in an npm-shaped world, nothing more.

✦ 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.

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

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 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.