brnrd 0.1.0__tar.gz

brnrd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 brr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

brnrd-0.1.0/LICENSE-OVERVIEW.md

@@ -0,0 +1,27 @@
+# License overview
+
+This repository is a monorepo whose sub-packages ship under different
+licenses, aligned with the package boundaries below.
+
+| Path | Component | License |
+|------|-----------|---------|
+| repo root `LICENSE` | the brnrd distribution's daemon core | MIT |
+| `src/brr/` (`src/brr/LICENSE`) | daemon core | MIT |
+| `src/brnrd/` (`src/brnrd/LICENSE`) | brnrd backend (`brnrd[backend]` extra) | AGPLv3 |
+| `src/brnrd_web/` (`src/brnrd_web/LICENSE`) | dashboard | AGPLv3 |
+
+What this means in practice:
+
+- The wheel contains all three import packages; extras select their runtime
+  dependencies, not which licensed source files are present.
+- `pip install brnrd` installs the dependencies needed by the MIT-licensed
+  daemon core.
+- `pip install brnrd[backend]` additionally installs the dependencies needed
+  to run the AGPLv3-licensed backend and dashboard. Running a modified backend
+  as a network service triggers the AGPL's source-availability
+  obligation; the permissive daemon core is unaffected.
+
+The split is intentional: the package boundaries make the
+license boundary unambiguous, and the AGPL on the backend is the
+competitive-defense posture that makes shipping it as open
+source defensible against managed-service competitors.

brnrd-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+prune src/frontend

brnrd-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: brnrd
+Version: 0.1.0
+Summary: Structured guardrails for AI agent work, managed from a chat
+Author: HugiMuni
+License-Expression: MIT AND AGPL-3.0-only
+Project-URL: Homepage, https://brnrd.dev
+Project-URL: Repository, https://github.com/Gurio/brr
+Project-URL: Issues, https://github.com/Gurio/brr/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSE-OVERVIEW.md
+License-File: src/brr/LICENSE
+License-File: src/brnrd/LICENSE
+License-File: src/brnrd_web/LICENSE
+Requires-Dist: requests<3,>=2.31
+Provides-Extra: backend
+Requires-Dist: fastapi>=0.110; extra == "backend"
+Requires-Dist: uvicorn>=0.27; extra == "backend"
+Requires-Dist: sqlalchemy>=2.0; extra == "backend"
+Requires-Dist: httpx>=0.27; extra == "backend"
+Requires-Dist: jinja2>=3.1; extra == "backend"
+Requires-Dist: python-multipart>=0.0.9; extra == "backend"
+Requires-Dist: PyJWT[crypto]<3,>=2.8; extra == "backend"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: brnrd[backend]; extra == "dev"
+Dynamic: license-file
+
+# brnrd
+
+![brnrd](https://github.com/Gurio/brr/raw/main/media/brr-logo.gif)
+
+Structured AI agent playbook with persistent knowledge base and remote execution.
+
+brnrd produces `AGENTS.md` — a playbook that encodes your project's conventions,
+workflow, and guardrails.  Any AI tool that reads it (Claude Code, Cursor, Codex,
+Gemini) gets the same behavior.  brnrd adds a remote execution layer: a daemon that
+accepts tasks from Telegram, Slack, GitHub (issue labels and PR / issue
+mentions), or anything that writes a file.
+
+**Two layers of value:**
+
+1. **Playbook only** — `AGENTS.md` + `kb/` work with any AI tool, no brnrd needed.
+   Copy the conventions, use them everywhere.
+2. **Full tool** — the brnrd daemon handles remote execution, gate I/O, knowledge
+   persistence, and git push.
+
+Execution stays local. The optional managed service relays remote events and
+hosts the dashboard without moving agent work off your machine.
+
+## Install
+
+```bash
+pip install brnrd
+```
+
+Or run from a local checkout while developing or customizing brnrd itself:
+
+```bash
+git clone https://github.com/Gurio/brr
+/path/to/brr/brnrd init
+```
+
+For an editable install:
+
+```bash
+pip install -e /path/to/brr
+```
+
+Forks work with normal Python packaging too:
+
+```bash
+pip install git+https://github.com/Gurio/brr.git
+```
+
+## Quick start
+
+```bash
+brnrd init                          # detect runner, create AGENTS.md + kb/
+brnrd run "fix the failing tests"   # run a task through the configured environment
+
+brnrd bind . telegram               # configure a repo-local remote input
+brnrd up                            # start the daemon in the foreground
+brnrd daemon install                # install the native user service
+```
+
+From Telegram (or Slack, or a task file):
+
+```
+> fix the failing tests in auth/
+> research caching strategies for the API layer
+> review the latest PR for security issues
+```
+
+## What brnrd creates
+
+`brnrd init` sets up:
+
+- **`AGENTS.md`** — playbook with workflow, kb conventions, commit protocol,
+  artifact rules, guardrails, self-review instructions.
+- **`kb/`** — persistent knowledge base committed to the repo.  Compounds
+  across sessions.
+- **`.brr/`** — runtime directory (gitignored): inbox, responses, config,
+  gate state.
+
+## Architecture
+
+```
+AGENTS.md + kb/         universal: works with any AI tool
+  │
+  ├── Claude Code reads it
+  ├── Cursor reads it
+  ├── Codex reads it
+  │
+  └── brnrd adds remote execution:
+
+  ┌─────────┐    .brr/inbox/    ┌────────┐    runner    ┌──────────┐
+  │  Gates  │───────────────────│ Daemon │──────────────│  Runner  │
+  │ tg/slack│    .brr/responses │        │  subprocess  │ (AI CLI) │
+  │ gh/any  │◄──────────────────│        │◄─────────────│          │
+  └─────────┘                   └────────┘   git push   └──────────┘
+```
+
+Gates are transport adapters — they create event files and deliver responses.
+The daemon scans the inbox and runs workers.  The runner is whatever AI CLI
+you have installed.
+
+Telegram works with just a bot token.  Once the daemon is running, send the
+bot a message; brnrd records the chat ID from each message and replies there.
+
+## CLI
+
+| Command                | What it does                          |
+|------------------------|---------------------------------------|
+| `brnrd init [url]`       | Create AGENTS.md + kb/, detect runner |
+| `brnrd run "<task>"`     | Run a task via the configured runner  |
+| `brnrd bind <repo> <gate>` | Bind a repo-local gate               |
+| `brnrd connect [url]`    | Connect this daemon to brnrd service  |
+| `brnrd add <repo>`       | Add a repo to the connected account home |
+| `brnrd kb "<query>"`     | Search home/repo knowledge            |
+| `brnrd up`               | Start the daemon (foreground)         |
+| `brnrd down`             | Stop the foreground daemon            |
+| `brnrd daemon up`        | Start the installed daemon service, or foreground daemon if no service is installed |
+| `brnrd daemon down`      | Stop the installed daemon service, or foreground daemon if no service is installed |
+| `brnrd daemon status`    | Show service and foreground daemon status |
+| `brnrd daemon install`   | Install the native user service (systemd or LaunchAgent) |
+| `brnrd daemon uninstall` | Remove the native user service |
+| `brnrd daemon logs`      | Tail native service logs |
+
+Gates: `telegram`, `slack`, `github`.
+
+On macOS, the first daemon run that opens network sockets can trigger
+the system "accept incoming network connections" prompt. Allow it if
+you want gates and managed brnrd traffic to reach the local daemon.
+
+## Extending
+
+**Gates** follow a file protocol: write to `.brr/inbox/`, read from
+`.brr/responses/`.  Any language works.  See `src/brr/gates/README.md`
+for the spec and a bash example.
+
+**Runners** are CLI commands on PATH: any process that can operate files
+from a prompt, print the final reply to stdout, and stream progress to
+stderr. Built-in profiles cover `claude`, `codex`, and `gemini`; manage
+project-specific profiles in `.brr/runners.md`, set `runner=<name>` in
+`.brr/config`, or use `runner_cmd` for one custom command.
+
+**Environments** are daemon backends.  Configure the user-facing policy
+with `environment=<auto|host|worktree|docker>` in `.brr/config`.
+`environment=auto` prefers configured Docker isolation, then falls back
+to worktree behavior.  The concrete built-ins today are `host`,
+`worktree`, and `docker`; future backends such as `devcontainer`, `ssh`,
+or service-specific plugins fit behind the same internal protocol.
+
+Daemon git operations are publish-plan driven. Each task starts on a
+fresh `brr/<task-id>` branch from a resolved seed ref. When the event
+names a target branch (`branch_target`, `target_branch`, `base_branch`,
+or legacy `branch`), brnrd seeds from `<remote>/<target>` and publishes
+under that name after the run. Without a structured target the task
+branch is preserved as-is and published for human routing when a remote
+is configured.
+
+Docker mode wires credentials automatically: brnrd forwards
+`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` /
+`GOOGLE_API_KEY` from the daemon's environment, and bind-mounts your
+host's `~/.claude/`, `~/.codex/`, `~/.gemini/` (when present) into the
+container so subscription auth works without extra config. See
+`src/brr/docs/envs.md` for the full breakdown — image expectations, the
+bundled runner image, and the durability contract.
+
+Branching is mostly task-internal.  brnrd uses branches/worktrees to stage
+reviewable code changes or continue an explicitly named branch, but users
+usually only choose the environment policy.
+
+**Deep customization** should use a local checkout, editable install, or
+fork.  `.brr/config` is for lightweight runtime choices like runner and
+environment policy.
+
+## Development
+
+```bash
+git clone https://github.com/Gurio/brr
+cd brr
+pip install -e ".[dev]"
+pytest
+```
+
+For remote-assisted brnrd development, run the daemon from the editable
+install with developer reload enabled:
+
+```bash
+brnrd up --dev-reload
+```
+
+The daemon re-execs itself between tasks when brnrd package files change.
+
+## License
+
+The local daemon core in `src/brr/` is MIT licensed. The managed backend and
+dashboard in `src/brnrd/` and `src/brnrd_web/` are AGPLv3 licensed. See
+[`LICENSE-OVERVIEW.md`](https://github.com/Gurio/brr/blob/main/LICENSE-OVERVIEW.md) for the package boundary and
+install details.

brnrd-0.1.0/README.md

@@ -0,0 +1,194 @@
+# brnrd
+
+![brnrd](https://github.com/Gurio/brr/raw/main/media/brr-logo.gif)
+
+Structured AI agent playbook with persistent knowledge base and remote execution.
+
+brnrd produces `AGENTS.md` — a playbook that encodes your project's conventions,
+workflow, and guardrails.  Any AI tool that reads it (Claude Code, Cursor, Codex,
+Gemini) gets the same behavior.  brnrd adds a remote execution layer: a daemon that
+accepts tasks from Telegram, Slack, GitHub (issue labels and PR / issue
+mentions), or anything that writes a file.
+
+**Two layers of value:**
+
+1. **Playbook only** — `AGENTS.md` + `kb/` work with any AI tool, no brnrd needed.
+   Copy the conventions, use them everywhere.
+2. **Full tool** — the brnrd daemon handles remote execution, gate I/O, knowledge
+   persistence, and git push.
+
+Execution stays local. The optional managed service relays remote events and
+hosts the dashboard without moving agent work off your machine.
+
+## Install
+
+```bash
+pip install brnrd
+```
+
+Or run from a local checkout while developing or customizing brnrd itself:
+
+```bash
+git clone https://github.com/Gurio/brr
+/path/to/brr/brnrd init
+```
+
+For an editable install:
+
+```bash
+pip install -e /path/to/brr
+```
+
+Forks work with normal Python packaging too:
+
+```bash
+pip install git+https://github.com/Gurio/brr.git
+```
+
+## Quick start
+
+```bash
+brnrd init                          # detect runner, create AGENTS.md + kb/
+brnrd run "fix the failing tests"   # run a task through the configured environment
+
+brnrd bind . telegram               # configure a repo-local remote input
+brnrd up                            # start the daemon in the foreground
+brnrd daemon install                # install the native user service
+```
+
+From Telegram (or Slack, or a task file):
+
+```
+> fix the failing tests in auth/
+> research caching strategies for the API layer
+> review the latest PR for security issues
+```
+
+## What brnrd creates
+
+`brnrd init` sets up:
+
+- **`AGENTS.md`** — playbook with workflow, kb conventions, commit protocol,
+  artifact rules, guardrails, self-review instructions.
+- **`kb/`** — persistent knowledge base committed to the repo.  Compounds
+  across sessions.
+- **`.brr/`** — runtime directory (gitignored): inbox, responses, config,
+  gate state.
+
+## Architecture
+
+```
+AGENTS.md + kb/         universal: works with any AI tool
+  │
+  ├── Claude Code reads it
+  ├── Cursor reads it
+  ├── Codex reads it
+  │
+  └── brnrd adds remote execution:
+
+  ┌─────────┐    .brr/inbox/    ┌────────┐    runner    ┌──────────┐
+  │  Gates  │───────────────────│ Daemon │──────────────│  Runner  │
+  │ tg/slack│    .brr/responses │        │  subprocess  │ (AI CLI) │
+  │ gh/any  │◄──────────────────│        │◄─────────────│          │
+  └─────────┘                   └────────┘   git push   └──────────┘
+```
+
+Gates are transport adapters — they create event files and deliver responses.
+The daemon scans the inbox and runs workers.  The runner is whatever AI CLI
+you have installed.
+
+Telegram works with just a bot token.  Once the daemon is running, send the
+bot a message; brnrd records the chat ID from each message and replies there.
+
+## CLI
+
+| Command                | What it does                          |
+|------------------------|---------------------------------------|
+| `brnrd init [url]`       | Create AGENTS.md + kb/, detect runner |
+| `brnrd run "<task>"`     | Run a task via the configured runner  |
+| `brnrd bind <repo> <gate>` | Bind a repo-local gate               |
+| `brnrd connect [url]`    | Connect this daemon to brnrd service  |
+| `brnrd add <repo>`       | Add a repo to the connected account home |
+| `brnrd kb "<query>"`     | Search home/repo knowledge            |
+| `brnrd up`               | Start the daemon (foreground)         |
+| `brnrd down`             | Stop the foreground daemon            |
+| `brnrd daemon up`        | Start the installed daemon service, or foreground daemon if no service is installed |
+| `brnrd daemon down`      | Stop the installed daemon service, or foreground daemon if no service is installed |
+| `brnrd daemon status`    | Show service and foreground daemon status |
+| `brnrd daemon install`   | Install the native user service (systemd or LaunchAgent) |
+| `brnrd daemon uninstall` | Remove the native user service |
+| `brnrd daemon logs`      | Tail native service logs |
+
+Gates: `telegram`, `slack`, `github`.
+
+On macOS, the first daemon run that opens network sockets can trigger
+the system "accept incoming network connections" prompt. Allow it if
+you want gates and managed brnrd traffic to reach the local daemon.
+
+## Extending
+
+**Gates** follow a file protocol: write to `.brr/inbox/`, read from
+`.brr/responses/`.  Any language works.  See `src/brr/gates/README.md`
+for the spec and a bash example.
+
+**Runners** are CLI commands on PATH: any process that can operate files
+from a prompt, print the final reply to stdout, and stream progress to
+stderr. Built-in profiles cover `claude`, `codex`, and `gemini`; manage
+project-specific profiles in `.brr/runners.md`, set `runner=<name>` in
+`.brr/config`, or use `runner_cmd` for one custom command.
+
+**Environments** are daemon backends.  Configure the user-facing policy
+with `environment=<auto|host|worktree|docker>` in `.brr/config`.
+`environment=auto` prefers configured Docker isolation, then falls back
+to worktree behavior.  The concrete built-ins today are `host`,
+`worktree`, and `docker`; future backends such as `devcontainer`, `ssh`,
+or service-specific plugins fit behind the same internal protocol.
+
+Daemon git operations are publish-plan driven. Each task starts on a
+fresh `brr/<task-id>` branch from a resolved seed ref. When the event
+names a target branch (`branch_target`, `target_branch`, `base_branch`,
+or legacy `branch`), brnrd seeds from `<remote>/<target>` and publishes
+under that name after the run. Without a structured target the task
+branch is preserved as-is and published for human routing when a remote
+is configured.
+
+Docker mode wires credentials automatically: brnrd forwards
+`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` /
+`GOOGLE_API_KEY` from the daemon's environment, and bind-mounts your
+host's `~/.claude/`, `~/.codex/`, `~/.gemini/` (when present) into the
+container so subscription auth works without extra config. See
+`src/brr/docs/envs.md` for the full breakdown — image expectations, the
+bundled runner image, and the durability contract.
+
+Branching is mostly task-internal.  brnrd uses branches/worktrees to stage
+reviewable code changes or continue an explicitly named branch, but users
+usually only choose the environment policy.
+
+**Deep customization** should use a local checkout, editable install, or
+fork.  `.brr/config` is for lightweight runtime choices like runner and
+environment policy.
+
+## Development
+
+```bash
+git clone https://github.com/Gurio/brr
+cd brr
+pip install -e ".[dev]"
+pytest
+```
+
+For remote-assisted brnrd development, run the daemon from the editable
+install with developer reload enabled:
+
+```bash
+brnrd up --dev-reload
+```
+
+The daemon re-execs itself between tasks when brnrd package files change.
+
+## License
+
+The local daemon core in `src/brr/` is MIT licensed. The managed backend and
+dashboard in `src/brnrd/` and `src/brnrd_web/` are AGPLv3 licensed. See
+[`LICENSE-OVERVIEW.md`](https://github.com/Gurio/brr/blob/main/LICENSE-OVERVIEW.md) for the package boundary and
+install details.

brnrd-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "brnrd"
+version = "0.1.0"
+description = "Structured guardrails for AI agent work, managed from a chat"
+authors = [ { name = "HugiMuni" } ]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["requests>=2.31,<3"]
+license = "MIT AND AGPL-3.0-only"
+license-files = [
+  "LICENSE",
+  "LICENSE-OVERVIEW.md",
+  "src/brr/LICENSE",
+  "src/brnrd/LICENSE",
+  "src/brnrd_web/LICENSE",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://brnrd.dev"
+Repository = "https://github.com/Gurio/brr"
+Issues = "https://github.com/Gurio/brr/issues"
+
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+# Per-package license split (see LICENSE-OVERVIEW.md): the daemon
+# core (`src/brr/`) is MIT; the brnrd backend (`src/brnrd/`,
+# pulled by the `backend` extra) is AGPLv3.
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["brr*", "brnrd*", "brnrd_web*"]
+
+[tool.setuptools.package-data]
+brr = ["AGENTS.md", "LICENSE", "Dockerfile", "prompts/*.md", "docs/*.md", "gates/README.md", "diffense/*.html", "data/*.json"]
+brnrd = ["LICENSE"]
+brnrd_web = ["LICENSE", "templates/*.html", "static/*.css"]
+
+[project.optional-dependencies]
+backend = [
+  "fastapi>=0.110",
+  "uvicorn>=0.27",
+  "sqlalchemy>=2.0",
+  "httpx>=0.27",
+  "jinja2>=3.1",
+  "python-multipart>=0.0.9",
+  "PyJWT[crypto]>=2.8,<3",
+]
+# Postgres driver for deployment (Upsun/managed). psycopg3 ships
+# manylinux wheels, so no native build step. SQLite (stdlib) covers
+# local dev, so this stays out of the default `backend` set.
+postgres = [
+  "psycopg[binary]>=3.1",
+]
+dev = ["pytest>=7.0", "brnrd[backend]"]
+
+[project.scripts]
+brnrd = "brr.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

brnrd-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+