<h1 align="center">Placet</h1>

<p align="center">
  <strong>Your AI coding agents, in your pocket — and talking to each other, with your approval.</strong><br>
  A self-hosted hub for Claude Code, OpenAI Codex and Google Antigravity: follow every session from your phone,
  answer their questions, write to them, and let them hand work to one another only when you say so.
</p>

<p align="center">
  <a href="https://github.com/Pablo-gitub/Placet/actions/workflows/checks.yml"><img src="https://github.com/Pablo-gitub/Placet/actions/workflows/checks.yml/badge.svg?branch=main" alt="Checks"></a>
  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Status: alpha">
  <img src="https://img.shields.io/badge/agents-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Antigravity-6366f1" alt="Agents: Claude Code, Codex, Antigravity">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License: Apache 2.0"></a>
</p>

<p align="center">
  <img src="docs/screenshots/desktop-project.png" alt="Placet on the desktop: usage, a pending agent-to-agent prompt waiting for approval, a project and its live relations diagram" width="900">
</p>

> *Placet* (Latin, "it pleases"): the formal word for giving your consent. Nothing crosses from one agent to another without it.

---

## Why

If you run Claude Code, Codex and Antigravity side by side, you know the problems:

- **You are tied to the desk.** An agent stops to ask "may I run the migration?" and waits until you are back.
- **The agents cannot talk to each other.** You copy a plan from Claude into Codex for a review, then paste the review back.
- **When they *can* talk, nobody is watching.** Letting agents prompt each other unsupervised is how loops and surprises happen.

Placet sits between your agents and your phone. Every session registers itself; you read its conversation, answer its questions and write to it from anywhere. When one agent wants another to do something, the request comes to you first: approve it, edit the prompt, or reject it.

## Agent teams, under your eye

<table>
  <tr>
    <td width="48%"><img src="docs/screenshots/agent-team.gif" alt="Animated relations diagram: eight agents of one project pulse while working, prompts travel along the arrows, a reply travels back, and a yellow dot waits halfway for the human's approval" width="440"></td>
    <td>
      Name your sessions as <b>nodes</b>, group them into a <b>project</b> and connect them with typed <b>relations</b>: <i>Implement</i>, <i>Review</i>, <i>Test</i>, <i>Ship</i>…<br><br>
      The diagram is live:
      <ul>
        <li><b>pulsing nodes</b> are working right now;</li>
        <li><b>a dot runs along an arrow</b> while a prompt is delivered, and <b>back</b> while the reply returns;</li>
        <li><b>a lit arrow</b>: the recipient is executing;</li>
        <li><b>a yellow dot halfway</b>: the chain waits for you.</li>
      </ul>
      <b>Automatic</b> relations (solid) deliver on their own, within your rule, loop limits and usage thresholds; <b>manual</b> ones (dashed) always ask first. Each project and each node in it can carry short instructions repeated with every prompt.
    </td>
  </tr>
</table>

<sub>Simulated activity on the real PWA: eight sessions across Claude Code, Codex and Antigravity working on a refund feature.</sub>

## Features

<table>
  <tr>
    <td align="center" width="25%"><img src="docs/screenshots/phone-home.png" alt="Home: sessions grouped by provider" width="200"><br><sub><b>Every session, by provider</b><br>with live state and pending questions</sub></td>
    <td align="center" width="25%"><img src="docs/screenshots/phone-approval.png" alt="Approving a request from Claude to Codex" width="200"><br><sub><b>Agent → agent, approved by you</b><br>edit the prompt, pick the target session</sub></td>
    <td align="center" width="25%"><img src="docs/screenshots/phone-attachments.png" alt="A conversation with a generated image and a shared PDF" width="200"><br><sub><b>Conversations with attachments</b><br>images, generated pictures, shared PDFs</sub></td>
    <td align="center" width="25%"><img src="docs/screenshots/phone-mention.png" alt="Mentioning another session with @" width="200"><br><sub><b>Mention another session with @</b><br>the agent prepares the request</sub></td>
  </tr>
</table>

- **One inbox for all your agents.** Questions from Claude, Codex and Antigravity arrive as cards in a PWA you add to your home screen, with push notifications that open it on the request (Web Push) and, optionally, through a self-hosted [ntfy](https://ntfy.sh).
- **Read and write to any session.** The conversation as you see it on the PC: Markdown, highlighted code, tool calls collapsed into one line. Write a message and it wakes the session, as if you had typed it at the desk.
- **An approval bus between agents.** `placet_send_to_agent` lets an agent ask another one for a review, a test run or a second opinion. You approve, edit, reject or send it to another session; the reply returns after your separate approval, or you forward it elsewhere.
- **Relations, projects and automation.** Name sessions as stable nodes and group them into projects. Connect nodes with typed relations, each `manual` or `automatic`. Projects can have their own rules, shared project and role instructions, and stricter anti-loop limits. Agents see the policy, read your effective rule before every automatic send, and stop at loop limits; **Stop all** pauses everything. Near a provider's 5-hour or weekly usage limit, its automatic relations can fall back to your review.
- **Reserved commands.** Restarting the backend or the bridge from the phone, authorized with a passkey (Face ID) on a separate administrative origin; agents can propose, never authorize. Deploys from the phone are planned.
- **Attachments both ways.** Images you pasted in the desktop apps, pictures an agent generated, PDFs it shared with `placet_share_file`, and photos or files you attach from the phone.
- **Undelivered messages, readable history.** A Settings page lists messages that have not reached their session (blocked, waiting for a usage reset, scheduled, awaiting approval) with cancel and forward; the history shows every request by number with its full text.
- **Reliable by design.** Hooks write to a local queue and never block a turn. A turn stopped by an API error (such as a usage limit) or interrupted in the app is recognised and holds the queue instead of looking busy forever; Claude Desktop sessions the app unloads or archives are shown as such, with the app's loaded-session count. Each request tracks *delivery*, *execution* and *reply* separately; an uncertain delivery is never re-sent behind your back. One request at a time per session, and time alone never frees the queue.
- **Adaptive.** Two columns on the desktop, a bottom bar on the phone, a theme per provider.

## How it works

```mermaid
flowchart LR
    phone["📱 Phone<br/>PWA + Web Push"]
    subgraph pc["Your PC"]
        backend["Placet backend<br/>FastAPI · SQLite · audit log"]
        bridge["Bridge<br/>runs as you"]
        mcp["Placet MCP tools"]
        subgraph agents["Agent sessions"]
            claude["Claude Code"]
            codex["Codex"]
            agy["Antigravity"]
        end
    end
    phone <-- "Tailscale (HTTPS)" --> backend
    agents -- "hooks → local queue" --> bridge
    agents -- "ask · send · reply · share" --> mcp --> backend
    bridge <-- "jobs, events" --> backend
    bridge -- "wake: waiter · codex queue · app API" --> agents
```

- **Backend** — runs as its own system user, keeps requests and the audit log, and is reachable from your phone only through your [Tailscale](https://tailscale.com) network. It never stores your conversations.
- **Bridge** — runs as you: it reads conversations on demand, wakes sessions, forwards hook events from the local queue and checks which projects are excluded.
- **Hooks** — every Claude Code, Codex and Antigravity session registers itself and reports when a turn starts and ends. Sessions stay quiet until a Placet message arrives; a `.placet-off` file keeps a project out entirely.
- **MCP tools** — `placet_ask_human`, `placet_send_to_agent`, `placet_list_relations`, `placet_reply`, `placet_share_file` and friends, available to every agent.

| Provider | Registers with | Woken by |
|---|---|---|
| Claude Code (desktop app and CLI) | hooks | a background waiter (`asyncRewake`) |
| OpenAI Codex (desktop app and CLI) | hooks | `codex queue` |
| Google Antigravity 2.0 | hooks | the app's language server |

## Security, briefly

- **Two doors.** Agents talk to `127.0.0.1` with their own token; you reach the PWA through a Unix socket exposed with `tailscale serve`, and only the Tailscale logins you allow get in.
- **Least privilege.** The backend has no access to your files. The bridge reads only what a page or an attachment needs, and an attachment is requested by id, never by path.
- **Attachments are checked.** Only files the provider adapter recognised, inside the folders the app uses for that conversation (symlinks resolved), and real JPEG, PNG, WebP or PDF content. Shared files are never taken from hidden folders like `.ssh`.
- **Honest limits.** Agents run as your user and could read each other's tokens: tokens identify agents in the audit log, they do not isolate them. Some integrations rely on undocumented app internals and may break on updates; they are isolated in adapters.

More in the [architecture](docs/architecture.md).

## Quick start

Placet targets **Linux** with **Python 3.11+**, **Node.js 22.13+** and [Tailscale](https://tailscale.com). Push notifications work through Web Push with no extra server; a self-hosted [ntfy](https://ntfy.sh) is optional.

```bash
git clone <this repository> placet && cd placet
sudo deploy/install.sh                  # backend service, bridge service, PWA build
python3 /opt/placet/hooks/install.py    # hooks for Claude Code, Codex and Antigravity
sudo tailscale serve --bg unix:/run/placet/human.sock
```

Then add the Placet MCP server to your agents, approve the Codex hooks once with `/hooks`, restart the apps, and open `https://<your-machine>.<tailnet>.ts.net` on your phone.

The complete guide — environment variables, notifications, MCP setup, the tmux channel — is in [docs/installation.md](docs/installation.md).

## Status

Placet is **alpha**, used every day by its author on one machine. The interface supports English and Italian, covering approvals, history, session selection, chat controls, delivery feedback and image/PDF viewers. Notifications and generated Placet messages have a separate shared language setting. See [localization scope and contributor rules](docs/localization.md).

- ✅ Questions and approvals from the phone, push notifications, audit log
- ✅ Sessions on the phone: read, write, wake (Claude Code, Codex, Antigravity)
- ✅ Reliability: local event queue, delivery / execution / reply, one request at a time
- ✅ Attachments: viewing, `placet_share_file`, uploads from the phone; `@` mentions
- ✅ "Now" messages inside a running turn (Claude Code, Antigravity); scheduled messages and delivery at the provider's usage reset
- ✅ Undelivered messages with cancel/forward; turns stopped by API errors or interrupted in the app
- ✅ Nodes, typed relations with manual / automatic policy, a general rule for automatic relations, loop limits and Stop all; change of recipient on approval
- ✅ Projects with per-project rules, limits and instructions; a live relations diagram; usage guard
- ✅ Web Push to the installed PWA (a tap opens the request)
- ✅ Reserved commands confirmed with a passkey: restart the backend or the bridge
- 🚧 Deploys from the phone; verified session binding (RS-09, backend done, credential opt-in)
- 🗺️ A graph editor for relations; a local model provider (OpenJarvis/Ollama)
- ✅ Provider usage windows and session model/context/effort where provider data is available
- ✅ Remote compact/effort for Claude Code CLI sessions in tmux
- 🗺️ A project-manager view (RFC-17), creating sessions from the phone, macOS/Windows and a local mode without Tailscale

Documentation: [overview](docs/README.md) · [requirements](docs/requirements.md) · [architecture](docs/architecture.md) · [experiments](docs/experiments/provider-integration.md) · [contributing](CONTRIBUTING.md).

## Development

```bash
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
npm --prefix frontend ci
npm --prefix frontend test && npm --prefix frontend run build
.venv/bin/python -m pytest -q                    # API tests also serve the built PWA
.venv/bin/python run_all.py                      # backend + bridge in one process (development only)
```

## Contributing

Issues and pull requests are welcome, especially adapters for other agents and checks on new versions of the supported apps. Please keep the two rules that shape the project: nothing reaches an agent from another agent without passing through Placet's policy, and nothing on the phone reveals a file the user did not choose to share.

## License

Licensed under the [Apache License 2.0](LICENSE). Copyright 2026 Paolo Pietrelli.