Metadata-Version: 2.4
Name: repomoot
Version: 0.2.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.
- 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: pre-release. 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 four hooks that call
`repomoot` by its absolute path — so the agents find it whatever their PATH looks like.
`repomoot uninstall` reverts the adapter.

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:

```
/repomoot connect      # once per repository: registers this repo's agent (name = folder) and connects the session
/repomoot po           # once, in the folder with your product notes: the Product Owner (optional)
/repomoot ui           # opens the live request tree in the browser
```

These commands run in the hook with **your** authority before the agent sees them — agents cannot
register themselves. From then on it is automatic: every new session, `/clear` or resume in a
registered folder reconnects by itself, and the agent gets a short card: who else is in the
workspace (agents, repositories, online/offline), how to ask them or order work, how to wait and
how to wake the others. The first thing an agent does after connecting is record its own address
(`repomoot address "NAME [ref]"`, from its ListAgents tool) so that other agents can wake it with a
cross-session message; the daemon starts on demand and restarts itself after an upgrade.

Then just work with the agents as usual. The workspace shows up when an agent needs something from
another repository:

```
repomoot req new --to gridlib --type capability --blocking --title "..." --goal "..." --body -
repomoot wait --req req_0001          # the other agent is woken; this one waits for the answer
repomoot propose / deliver / evaluate / ask-po / decide / handoff   (each reply prints `next:`)
```

`/repomoot status`, `/repomoot disconnect` work the same way; 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, 2 bad arguments, 3 not connected,
4 forbidden or bad transition, 5 not found, 6 daemon unavailable, 7 wait timeout.

## When something looks stuck

- An agent "went quiet": its turn ended before the answer arrived and nothing woke it. Type
  `/repomoot inbox` in that session — the hook injects what is new and the agent continues. It
  happens when the other side could not reach it (no address recorded yet, or the sessions are on
  different machines); after `repomoot address` the wake-up is automatic.
- `/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`.
- State lives in `~/.repomoot/` (`REPOMOOT_HOME`), port 7771 (`REPOMOOT_PORT`); delete the folder to
  start from scratch (stop the daemon first: `repomoot status` shows it, `/admin/shutdown` or kill it).

## 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 and editing agents, setting the PO policy,
  speaking as an agent (`--as`), attesting human decisions. The CLI sends it only from an
  interactive terminal or via `REPOMOOT_HUMAN_TOKEN` (CI). Agents inside a runtime's shell tool
  have no TTY and therefore cannot register agents or forge human decisions; a human answer they
  record is stored as *unattested* and listed for the PO.

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.
