repomoot 0.2.0__tar.gz → 0.3.0__tar.gz

repomoot-0.3.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: repomoot
+Version: 0.3.0
+Summary: Requests between AI coding agents that own different repositories, with consumer acceptance and owner escalation
+Author: SimeonAr
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/dev-bude/repomoot
+Project-URL: Repository, https://github.com/dev-bude/repomoot
+Project-URL: Issues, https://github.com/dev-bude/repomoot/issues
+Project-URL: Protocol, https://github.com/dev-bude/repomoot/blob/main/PROTOCOL.md
+Project-URL: Security, https://github.com/dev-bude/repomoot/blob/main/SECURITY.md
+Keywords: ai-agents,claude-code,codex,multi-agent,request-lifecycle
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn>=0.29
+Requires-Dist: typer>=0.12
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# Repomoot
+
+**Requests between AI coding agents that own different repositories — with consumer acceptance
+and owner escalation.**
+
+When several coding agents (Claude Code, Codex, Gemini CLI, your own) work on related
+repositories, there is no working channel between them: you become the courier, the product
+owner and the referee, and the history disappears with every `/clear`. Repomoot gives the agents a
+shared lane for *requests* — "I need X from your repository" — with a lifecycle that ends when the
+**consumer** has verified the result in its own context, a **Product Owner** role for the decisions
+owners must not make alone, and a durable, searchable history.
+
+It is not shared memory, not an orchestrator and not a task board. Agents keep their own runtime,
+context and tools. Repomoot owns requests, messages, artifacts, decisions and events.
+
+## How it works
+
+- A local daemon holds the state (SQLite) and serves an HTTP API. The CLI `repomoot` is a thin
+  client and starts the daemon on demand; you never have to start it yourself
+  (`repomoot daemon start|stop|restart` exists for when you want to).
+- Agents talk to it through `repomoot` from their own shell tool — nothing else is required from a
+  runtime. The rules an agent follows (the *protocol card*) are owned by Repomoot and handed to the
+  agent at `repomoot connect`; the Claude Code adapter adds a thin skill and hooks that fetch it.
+- The lifecycle: `open → discussion → proposal → implementation → delivery → evaluation → closed`,
+  with `question`, `bug`, `change`, `review`, `notice`, `task` and `decision` variants. See
+  [PROTOCOL.md](https://github.com/dev-bude/repomoot/blob/main/PROTOCOL.md) — the protocol is documented separately from the code (CC-BY-4.0) and
+  maps onto A2A task states and MCP Tasks.
+- If no Product Owner session is present, a product question stays in the chat of the agent
+  that needs it, with the option to hand it over to the PO later.
+
+Status: 0.3, early (alpha). Local mode works end to end — see [WALKTHROUGH.md](https://github.com/dev-bude/repomoot/blob/main/WALKTHROUGH.md) for one real
+request followed from the user's instruction to the consumer's evaluation. No MCP surface, no
+CI/ephemeral mode yet. Code: Apache-2.0.
+
+## Install
+
+Repomoot is a command-line tool, so install it into its own environment:
+
+```
+pipx install repomoot        # or: uv tool install repomoot
+repomoot --version
+```
+
+Either one puts `repomoot` on your PATH and keeps its dependencies away from your projects.
+Plain `pip install repomoot` works too, inside a virtualenv of your own. Python 3.12+.
+
+Then install the Claude Code adapter (it prints what it will write and asks first):
+
+```
+repomoot install --runtime claude-code --hooks
+```
+
+That adds a 3-line pointer to `~/.claude/CLAUDE.md`, a `/repomoot` skill, and hooks that call
+`repomoot` by its absolute path — so the agents find it whatever their PATH looks like. If `repomoot`
+is not on PATH, it also puts a small launcher into a user folder that is (`%LOCALAPPDATA%\Microsoft\WindowsApps`
+on Windows, `~/.local/bin` or `~/bin` elsewhere).
+`repomoot uninstall` reverts the adapter. You can also ask an agent to install it: with no terminal
+to confirm in, the command prints what it would write and stops; the agent shows you the list and
+repeats it with `--yes` once you agree.
+
+Other runtimes: `repomoot install --runtime codex --dir <project>` writes the card into `AGENTS.md`
+(`gemini` → `GEMINI.md`, `cursor` → `.cursorrules`); `repomoot protocol` prints it.
+
+<details>
+<summary>From source (for working on Repomoot itself)</summary>
+
+```
+git clone https://github.com/dev-bude/repomoot.git && cd repomoot
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"   # Windows: .venv\Scripts\python -m pip install -e ".[dev]"
+.venv/bin/python -m pytest -q       # Windows: .venv\Scripts\python -m pytest -q
+```
+
+The `repomoot` command then lives in `.venv/bin` (Windows: `.venv\Scripts`); add it to your PATH to
+type commands yourself. See [CONTRIBUTING.md](https://github.com/dev-bude/repomoot/blob/main/CONTRIBUTING.md).
+
+</details>
+
+## First steps
+
+Open one Claude Code session per repository (VS Code windows or terminals). In the chat, once per
+folder — it is remembered:
+
+```
+/repomoot connect      # in each repository: registers this repo's agent (name = folder) and connects
+/repomoot po           # in the folder with your product notes: the Product Owner (optional, one at a time)
+```
+
+These commands run in the hook with **your** authority before the agent sees them — agents cannot
+register themselves. From then on every new session, `/clear` or resume in a registered folder (or
+in a git worktree of that repository) reconnects by itself; a session the daemon dropped after a
+long pause reconnects on its next command.
+
+Then you talk to the agents as usual — and, if there is a PO, tell the PO in plain words how the
+work should go ("pro orders, engine implements; preview hook first"). The agents keep
+`repomoot watch` running in the background, which wakes a session as soon as something arrives for
+it, so they pick up requests, report progress and answer each other without you relaying. The PO
+assigns work and gives the go-ahead itself; settings that are yours (checking a direction, stop
+words, its own policy, removing an agent) it proposes, and Repomoot shows you one line it wrote
+itself, for example `check everything pro sends to engine before it is delivered` — you answer:
+
+```
+/repomoot yes          # or /repomoot no; with several waiting: /repomoot yes <id>
+/repomoot ui           # the live request tree in the browser
+/repomoot confirm <id> # only when asked: a decision reserved for you that an agent recorded
+```
+
+A session working on its own repository plans and works by itself as usual; its task list is
+shared with Repomoot (`repomoot plan set / start / done --note / note`; Claude Code hooks mirror the
+task tool as a fallback), and the reports it writes to you are kept in a journal (`repomoot journal`) —
+so the PO and the dashboard always show each session's plan, what is done and what it reported,
+instead of it scrolling away in the chat.
+
+Under the hood the agents use the CLI (`repomoot req new / progress / propose / deliver / evaluate /
+ask-po / decide`, each reply prints `next:`); dependencies between agents are inferred from the
+requests they send. Everything is also available from your terminal
+(`repomoot agents`, `repomoot req show req_0001`, ...). `repomoot --help`, `repomoot <cmd> --help`;
+every command accepts `--json`. Exit codes: 0 ok, 1 other error, 2 bad arguments,
+3 not connected, 4 forbidden, bad transition or conflict, 5 not found, 6 daemon unavailable or bad token. A `wait` that times out is not
+an error: exit 0, `"timeout": true` in `--json`.
+
+## When something looks stuck
+
+- An agent "went quiet": it finished a step without `repomoot watch` in the background, so nothing
+  woke it. Type `/repomoot inbox` in that session — the hook injects what is new and the agent
+  continues. `repomoot agents` shows which sessions are watching.
+- A `wait` that ends with "no new events" is not a broken link: nothing arrived yet.
+- A folder that is not a git repository (say, a scratch folder holding worktrees of two repos) is
+  never registered as a new agent by `/repomoot connect`; the reply names the agents whose copies
+  are inside — `/repomoot connect <agent>` works there as that agent.
+- `/repomoot status` in any session shows who is online; `repomoot agents` from the terminal too.
+- Two sessions in one folder: give the second one a name, `repomoot connect --session two`.
+- The Product Owner owns only the folder it was registered in, never the projects under it: a session
+  in an unregistered subfolder is not connected until you type `/repomoot connect` there.
+- Registering everything from one terminal, without opening a session in each folder:
+  `repomoot agents add gridlib --repo ../gridlib`, `repomoot agents add po --kind po --repo ../notes`.
+  A directory attached by mistake is detached with `repomoot agents set NAME --remove-repo DIR`
+  (sessions opened there end; requests are kept). An agent registered by mistake (offline, no requests)
+  is removed with `repomoot agents remove NAME` or the × next to it in the dashboard (`repomoot ui`).
+- State lives in `~/.repomoot/` (`REPOMOOT_HOME`), port 7771 (`REPOMOOT_PORT`); delete the folder to
+  start from scratch (stop the daemon first: `repomoot daemon stop`).
+
+## One file for the workspace
+
+`repomoot workspace export` writes the whole setup — agents, their directories, dependencies, stop
+words, the PO's policy, gates — to `repomoot.toml` (directories relative to the file). On another
+machine, or after starting from scratch, `repomoot workspace apply` (your terminal only; `--dry-run`
+shows what would change) registers what the file describes. It only adds: removing an agent, a
+directory or a gate stays an explicit command.
+
+```toml
+[agents.engine]
+kind = "project"
+repos = ["engine"]
+
+[agents.pro]
+kind = "project"
+repos = ["pro"]
+depends_on = ["engine"]
+deny = ["InternalBilling"]
+
+[agents.po]
+kind = "po"
+repos = ["notes"]
+
+[[gates]]
+from = "pro"
+to = "engine"
+```
+
+## Looking back
+
+- `repomoot summary --since 8h` — what happened and what waits for you, in a few lines.
+- `repomoot log --since 2d [--agent engine]` — every event, oldest first.
+- `repomoot po decisions [--since 7d]` — the decisions: question, answer, reason, who decided.
+- `repomoot po history engine` — what an agent was asked for, what it delivered (commit, tests), how
+  the requesters judged it, what it ordered, the decisions that concern it.
+- `repomoot journal [--agent engine]` — the reports the sessions wrote to you.
+
+These are yours and the PO's; an agent's own `log` shows only what it was told.
+
+## Checked directions and stop words
+
+Text that looks like a secret (cloud keys, tokens, private keys, `password = ...`) is refused for
+everyone and never stored. Stop words keep an agent's internal names inside it:
+`repomoot agents set paid --deny InternalBilling --deny "re:acme\.corp"` — any request, reply or
+artifact of `paid` that mentions one is refused. A gate puts a direction under your eye:
+`repomoot gate paid lib` — what `paid` sends to `lib` waits for you: `/repomoot held` lists it,
+`/repomoot release <id>` delivers it as written, `/repomoot drop <id>` discards it. Useful between a
+private and a public repository, or between any two parts you want to watch. This guards what the
+sessions say to each other; what each session can read or push is up to Claude Code's own
+permissions and your git credentials.
+
+## Principals
+
+- **Daemon token** (`~/.repomoot/token`): every local client. Lets a session act as an *already
+  registered* agent from that agent's own repository directory.
+- **Human token** (`~/.repomoot/human.token`): registering, editing and removing agents, gates and
+  stop words, the PO policy, releasing held messages, confirming decisions reserved for the user,
+  speaking as an agent (`--as`). The CLI sends it only from an interactive terminal, from the chat
+  commands you type (`/repomoot ...`, handled by the hook before the agent sees them) or via
+  `REPOMOOT_HUMAN_TOKEN` (CI). An agent that records "the user's decision" on a kind the policy
+  reserves for the user (breaking change, scope, conflict, budget) does not close anything: it waits
+  for your `/repomoot confirm`.
+- The token file is readable by any process of your OS user, so this keeps honest agents and
+  injected instructions from acting as you; it is not a wall against an agent that deliberately
+  reads the file. Claude Code's own permissions (deny reads of `~/.repomoot/human.token`) are that wall.
+- Agents see only the requests they are a party of (the PO sees all); search follows the same rule.
+
+State lives in `~/.repomoot/` (`REPOMOOT_HOME`); port 7771 (`REPOMOOT_PORT`). Trust model and data
+notes: [SECURITY.md](https://github.com/dev-bude/repomoot/blob/main/SECURITY.md).
+
+## Reading on
+
+- [WALKTHROUGH.md](https://github.com/dev-bude/repomoot/blob/main/WALKTHROUGH.md) — how a request flows, step by step, with real output.
+- [PROTOCOL.md](https://github.com/dev-bude/repomoot/blob/main/PROTOCOL.md) — lifecycle, roles, artifacts, mapping to A2A / MCP Tasks.
+- [SECURITY.md](https://github.com/dev-bude/repomoot/blob/main/SECURITY.md) — trust model, data, what the adapter writes.
+- [CONTRIBUTING.md](https://github.com/dev-bude/repomoot/blob/main/CONTRIBUTING.md) — how to set up, what is worth working on, house rules.
+
+## Layout
+
+```
+repomoot/core      db, lifecycle, cards (instruction texts), service (all rules)
+repomoot/server    FastAPI daemon: HTTP API, async long-poll and SSE events
+repomoot/client    HTTP client, session files, human principal, daemon autostart
+repomoot/cli       typer CLI + text rendering (quotes and sanitizes other agents' text)
+repomoot/adapters  claude_code: install/uninstall, skill, hooks
+tests/            the walkthrough's flow and the rules, through the API
+```
+
+Tests: `python -m pytest -q`.
+
+## Licence
+
+Code: Apache-2.0 ([LICENSE](https://github.com/dev-bude/repomoot/blob/main/LICENSE), [NOTICE](https://github.com/dev-bude/repomoot/blob/main/NOTICE)). The protocol description
+([PROTOCOL.md](https://github.com/dev-bude/repomoot/blob/main/PROTOCOL.md)): CC BY 4.0.
+
+Claude Code, Codex, Gemini CLI and Cursor are products of their respective owners; Repomoot is an
+independent project and is not affiliated with or endorsed by any of them.

repomoot-0.3.0/README.md

@@ -0,0 +1,239 @@
+# Repomoot
+
+**Requests between AI coding agents that own different repositories — with consumer acceptance
+and owner escalation.**
+
+When several coding agents (Claude Code, Codex, Gemini CLI, your own) work on related
+repositories, there is no working channel between them: you become the courier, the product
+owner and the referee, and the history disappears with every `/clear`. Repomoot gives the agents a
+shared lane for *requests* — "I need X from your repository" — with a lifecycle that ends when the
+**consumer** has verified the result in its own context, a **Product Owner** role for the decisions
+owners must not make alone, and a durable, searchable history.
+
+It is not shared memory, not an orchestrator and not a task board. Agents keep their own runtime,
+context and tools. Repomoot owns requests, messages, artifacts, decisions and events.
+
+## How it works
+
+- A local daemon holds the state (SQLite) and serves an HTTP API. The CLI `repomoot` is a thin
+  client and starts the daemon on demand; you never have to start it yourself
+  (`repomoot daemon start|stop|restart` exists for when you want to).
+- Agents talk to it through `repomoot` from their own shell tool — nothing else is required from a
+  runtime. The rules an agent follows (the *protocol card*) are owned by Repomoot and handed to the
+  agent at `repomoot connect`; the Claude Code adapter adds a thin skill and hooks that fetch it.
+- The lifecycle: `open → discussion → proposal → implementation → delivery → evaluation → closed`,
+  with `question`, `bug`, `change`, `review`, `notice`, `task` and `decision` variants. See
+  [PROTOCOL.md](https://github.com/dev-bude/repomoot/blob/main/PROTOCOL.md) — the protocol is documented separately from the code (CC-BY-4.0) and
+  maps onto A2A task states and MCP Tasks.
+- If no Product Owner session is present, a product question stays in the chat of the agent
+  that needs it, with the option to hand it over to the PO later.
+
+Status: 0.3, early (alpha). Local mode works end to end — see [WALKTHROUGH.md](https://github.com/dev-bude/repomoot/blob/main/WALKTHROUGH.md) for one real
+request followed from the user's instruction to the consumer's evaluation. No MCP surface, no
+CI/ephemeral mode yet. Code: Apache-2.0.
+
+## Install
+
+Repomoot is a command-line tool, so install it into its own environment:
+
+```
+pipx install repomoot        # or: uv tool install repomoot
+repomoot --version
+```
+
+Either one puts `repomoot` on your PATH and keeps its dependencies away from your projects.
+Plain `pip install repomoot` works too, inside a virtualenv of your own. Python 3.12+.
+
+Then install the Claude Code adapter (it prints what it will write and asks first):
+
+```
+repomoot install --runtime claude-code --hooks
+```
+
+That adds a 3-line pointer to `~/.claude/CLAUDE.md`, a `/repomoot` skill, and hooks that call
+`repomoot` by its absolute path — so the agents find it whatever their PATH looks like. If `repomoot`
+is not on PATH, it also puts a small launcher into a user folder that is (`%LOCALAPPDATA%\Microsoft\WindowsApps`
+on Windows, `~/.local/bin` or `~/bin` elsewhere).
+`repomoot uninstall` reverts the adapter. You can also ask an agent to install it: with no terminal
+to confirm in, the command prints what it would write and stops; the agent shows you the list and
+repeats it with `--yes` once you agree.
+
+Other runtimes: `repomoot install --runtime codex --dir <project>` writes the card into `AGENTS.md`
+(`gemini` → `GEMINI.md`, `cursor` → `.cursorrules`); `repomoot protocol` prints it.
+
+<details>
+<summary>From source (for working on Repomoot itself)</summary>
+
+```
+git clone https://github.com/dev-bude/repomoot.git && cd repomoot
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"   # Windows: .venv\Scripts\python -m pip install -e ".[dev]"
+.venv/bin/python -m pytest -q       # Windows: .venv\Scripts\python -m pytest -q
+```
+
+The `repomoot` command then lives in `.venv/bin` (Windows: `.venv\Scripts`); add it to your PATH to
+type commands yourself. See [CONTRIBUTING.md](https://github.com/dev-bude/repomoot/blob/main/CONTRIBUTING.md).
+
+</details>
+
+## First steps
+
+Open one Claude Code session per repository (VS Code windows or terminals). In the chat, once per
+folder — it is remembered:
+
+```
+/repomoot connect      # in each repository: registers this repo's agent (name = folder) and connects
+/repomoot po           # in the folder with your product notes: the Product Owner (optional, one at a time)
+```
+
+These commands run in the hook with **your** authority before the agent sees them — agents cannot
+register themselves. From then on every new session, `/clear` or resume in a registered folder (or
+in a git worktree of that repository) reconnects by itself; a session the daemon dropped after a
+long pause reconnects on its next command.
+
+Then you talk to the agents as usual — and, if there is a PO, tell the PO in plain words how the
+work should go ("pro orders, engine implements; preview hook first"). The agents keep
+`repomoot watch` running in the background, which wakes a session as soon as something arrives for
+it, so they pick up requests, report progress and answer each other without you relaying. The PO
+assigns work and gives the go-ahead itself; settings that are yours (checking a direction, stop
+words, its own policy, removing an agent) it proposes, and Repomoot shows you one line it wrote
+itself, for example `check everything pro sends to engine before it is delivered` — you answer:
+
+```
+/repomoot yes          # or /repomoot no; with several waiting: /repomoot yes <id>
+/repomoot ui           # the live request tree in the browser
+/repomoot confirm <id> # only when asked: a decision reserved for you that an agent recorded
+```
+
+A session working on its own repository plans and works by itself as usual; its task list is
+shared with Repomoot (`repomoot plan set / start / done --note / note`; Claude Code hooks mirror the
+task tool as a fallback), and the reports it writes to you are kept in a journal (`repomoot journal`) —
+so the PO and the dashboard always show each session's plan, what is done and what it reported,
+instead of it scrolling away in the chat.
+
+Under the hood the agents use the CLI (`repomoot req new / progress / propose / deliver / evaluate /
+ask-po / decide`, each reply prints `next:`); dependencies between agents are inferred from the
+requests they send. Everything is also available from your terminal
+(`repomoot agents`, `repomoot req show req_0001`, ...). `repomoot --help`, `repomoot <cmd> --help`;
+every command accepts `--json`. Exit codes: 0 ok, 1 other error, 2 bad arguments,
+3 not connected, 4 forbidden, bad transition or conflict, 5 not found, 6 daemon unavailable or bad token. A `wait` that times out is not
+an error: exit 0, `"timeout": true` in `--json`.
+
+## When something looks stuck
+
+- An agent "went quiet": it finished a step without `repomoot watch` in the background, so nothing
+  woke it. Type `/repomoot inbox` in that session — the hook injects what is new and the agent
+  continues. `repomoot agents` shows which sessions are watching.
+- A `wait` that ends with "no new events" is not a broken link: nothing arrived yet.
+- A folder that is not a git repository (say, a scratch folder holding worktrees of two repos) is
+  never registered as a new agent by `/repomoot connect`; the reply names the agents whose copies
+  are inside — `/repomoot connect <agent>` works there as that agent.
+- `/repomoot status` in any session shows who is online; `repomoot agents` from the terminal too.
+- Two sessions in one folder: give the second one a name, `repomoot connect --session two`.
+- The Product Owner owns only the folder it was registered in, never the projects under it: a session
+  in an unregistered subfolder is not connected until you type `/repomoot connect` there.
+- Registering everything from one terminal, without opening a session in each folder:
+  `repomoot agents add gridlib --repo ../gridlib`, `repomoot agents add po --kind po --repo ../notes`.
+  A directory attached by mistake is detached with `repomoot agents set NAME --remove-repo DIR`
+  (sessions opened there end; requests are kept). An agent registered by mistake (offline, no requests)
+  is removed with `repomoot agents remove NAME` or the × next to it in the dashboard (`repomoot ui`).
+- State lives in `~/.repomoot/` (`REPOMOOT_HOME`), port 7771 (`REPOMOOT_PORT`); delete the folder to
+  start from scratch (stop the daemon first: `repomoot daemon stop`).
+
+## One file for the workspace
+
+`repomoot workspace export` writes the whole setup — agents, their directories, dependencies, stop
+words, the PO's policy, gates — to `repomoot.toml` (directories relative to the file). On another
+machine, or after starting from scratch, `repomoot workspace apply` (your terminal only; `--dry-run`
+shows what would change) registers what the file describes. It only adds: removing an agent, a
+directory or a gate stays an explicit command.
+
+```toml
+[agents.engine]
+kind = "project"
+repos = ["engine"]
+
+[agents.pro]
+kind = "project"
+repos = ["pro"]
+depends_on = ["engine"]
+deny = ["InternalBilling"]
+
+[agents.po]
+kind = "po"
+repos = ["notes"]
+
+[[gates]]
+from = "pro"
+to = "engine"
+```
+
+## Looking back
+
+- `repomoot summary --since 8h` — what happened and what waits for you, in a few lines.
+- `repomoot log --since 2d [--agent engine]` — every event, oldest first.
+- `repomoot po decisions [--since 7d]` — the decisions: question, answer, reason, who decided.
+- `repomoot po history engine` — what an agent was asked for, what it delivered (commit, tests), how
+  the requesters judged it, what it ordered, the decisions that concern it.
+- `repomoot journal [--agent engine]` — the reports the sessions wrote to you.
+
+These are yours and the PO's; an agent's own `log` shows only what it was told.
+
+## Checked directions and stop words
+
+Text that looks like a secret (cloud keys, tokens, private keys, `password = ...`) is refused for
+everyone and never stored. Stop words keep an agent's internal names inside it:
+`repomoot agents set paid --deny InternalBilling --deny "re:acme\.corp"` — any request, reply or
+artifact of `paid` that mentions one is refused. A gate puts a direction under your eye:
+`repomoot gate paid lib` — what `paid` sends to `lib` waits for you: `/repomoot held` lists it,
+`/repomoot release <id>` delivers it as written, `/repomoot drop <id>` discards it. Useful between a
+private and a public repository, or between any two parts you want to watch. This guards what the
+sessions say to each other; what each session can read or push is up to Claude Code's own
+permissions and your git credentials.
+
+## Principals
+
+- **Daemon token** (`~/.repomoot/token`): every local client. Lets a session act as an *already
+  registered* agent from that agent's own repository directory.
+- **Human token** (`~/.repomoot/human.token`): registering, editing and removing agents, gates and
+  stop words, the PO policy, releasing held messages, confirming decisions reserved for the user,
+  speaking as an agent (`--as`). The CLI sends it only from an interactive terminal, from the chat
+  commands you type (`/repomoot ...`, handled by the hook before the agent sees them) or via
+  `REPOMOOT_HUMAN_TOKEN` (CI). An agent that records "the user's decision" on a kind the policy
+  reserves for the user (breaking change, scope, conflict, budget) does not close anything: it waits
+  for your `/repomoot confirm`.
+- The token file is readable by any process of your OS user, so this keeps honest agents and
+  injected instructions from acting as you; it is not a wall against an agent that deliberately
+  reads the file. Claude Code's own permissions (deny reads of `~/.repomoot/human.token`) are that wall.
+- Agents see only the requests they are a party of (the PO sees all); search follows the same rule.
+
+State lives in `~/.repomoot/` (`REPOMOOT_HOME`); port 7771 (`REPOMOOT_PORT`). Trust model and data
+notes: [SECURITY.md](https://github.com/dev-bude/repomoot/blob/main/SECURITY.md).
+
+## Reading on
+
+- [WALKTHROUGH.md](https://github.com/dev-bude/repomoot/blob/main/WALKTHROUGH.md) — how a request flows, step by step, with real output.
+- [PROTOCOL.md](https://github.com/dev-bude/repomoot/blob/main/PROTOCOL.md) — lifecycle, roles, artifacts, mapping to A2A / MCP Tasks.
+- [SECURITY.md](https://github.com/dev-bude/repomoot/blob/main/SECURITY.md) — trust model, data, what the adapter writes.
+- [CONTRIBUTING.md](https://github.com/dev-bude/repomoot/blob/main/CONTRIBUTING.md) — how to set up, what is worth working on, house rules.
+
+## Layout
+
+```
+repomoot/core      db, lifecycle, cards (instruction texts), service (all rules)
+repomoot/server    FastAPI daemon: HTTP API, async long-poll and SSE events
+repomoot/client    HTTP client, session files, human principal, daemon autostart
+repomoot/cli       typer CLI + text rendering (quotes and sanitizes other agents' text)
+repomoot/adapters  claude_code: install/uninstall, skill, hooks
+tests/            the walkthrough's flow and the rules, through the API
+```
+
+Tests: `python -m pytest -q`.
+
+## Licence
+
+Code: Apache-2.0 ([LICENSE](https://github.com/dev-bude/repomoot/blob/main/LICENSE), [NOTICE](https://github.com/dev-bude/repomoot/blob/main/NOTICE)). The protocol description
+([PROTOCOL.md](https://github.com/dev-bude/repomoot/blob/main/PROTOCOL.md)): CC BY 4.0.
+
+Claude Code, Codex, Gemini CLI and Cursor are products of their respective owners; Repomoot is an
+independent project and is not affiliated with or endorsed by any of them.

{repomoot-0.2.0 → repomoot-0.3.0}/repomoot/__init__.py

@@ -1,4 +1,4 @@
 """Repomoot."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 PROTOCOL_VERSION = 1