twin-me-up

<!-- mcp-name: io.github.GitDakky/twin-me-up -->
<p align="center">
  <img src="https://raw.githubusercontent.com/GitDakky/twin-me-up/main/assets/banner.svg" alt="Twin Me Up: a personal work twin for every AI agent" width="100%">
</p>

<p align="center">
  <a href="https://pypi.org/project/twin-me-up/"><img alt="PyPI" src="https://img.shields.io/pypi/v/twin-me-up?color=5eead4&label=pypi"></a>
  <a href="https://pypi.org/project/twin-me-up/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/twin-me-up?color=7fb6ee"></a>
  <a href="https://github.com/GitDakky/twin-me-up/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/GitDakky/twin-me-up/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/GitDakky/twin-me-up"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/GitDakky/twin-me-up/badge"></a>
  <a href="https://github.com/GitDakky/twin-me-up/blob/main/LICENSE"><img alt="Licence: Apache-2.0" src="https://img.shields.io/badge/licence-Apache--2.0-a78bfa"></a>
  <img alt="Model Context Protocol" src="https://img.shields.io/badge/MCP-server-ff8cc6">
</p>

<p align="center">
  <b>Teach it once. Every agent you use works the way you would, and asks before it acts.</b>
</p>

<p align="center">
  <a href="#quick-start">Quick start</a> ·
  <a href="#install-with-one-prompt">One-prompt install</a> ·
  <a href="#how-it-works">How it works</a> ·
  <a href="#works-with">Works with</a> ·
  <a href="#the-research">The research</a> ·
  <a href="#safety-model">Safety</a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/GitDakky/twin-me-up/main/assets/demo.svg" alt="Installing Twin Me Up, then an agent being briefed, asking before it sends an email, and being stopped from pushing code it was not authorised to push" width="100%">
</p>

## Why

You probably use more than one AI agent. Each one starts from zero. It does not know what you
care about, which corners you never cut, or which decisions you always want to make yourself.
So you repeat yourself, correct the same mistakes, and hope nothing consequential happens
before you look.

Twin Me Up is a small, local, open-source service that gives every agent the same answers to
three questions:

1. **How does this person want this kind of work done?** Your confirmed guidance, criteria,
   exceptions and red lines, briefed to the agent at the start of work.
2. **Am I allowed to do this?** Explicit grants, scoped to a workflow and a set of actions, with
   optional expiry. Anything not granted returns `ask`. Optional hooks enforce that outside the
   model.
3. **What did I just learn?** Your decisions and corrections become candidate lessons. Only you
   can confirm them.

It is not a chatbot of you, a personality clone or an autonomous replacement for you. The
evidence does not support those claims, and [the research](https://github.com/GitDakky/twin-me-up/blob/main/docs/research.md) explains why.

## What makes it different

| | |
|---|---|
| **Learning you ratify** | Agents propose lessons. Only you confirm, revise, reject or retire them. Every lesson keeps its origin, sources and history. |
| **Authority you grant** | Agents act on explicit grants for a workflow and named actions, optionally expiring. Actions in the reserved `twin.` namespace can never be granted to anyone. |
| **Enforcement outside the model** | Pre-action hooks for Hermes, Claude Code and pi block or escalate ungranted tool calls. They fail closed. |
| **Evidence, not vibes** | Freeze held-out decisions, then test the twin against a generic assistant and a rules-only baseline. Results come with sample-size warnings. |
| **One twin, every agent** | One MCP server, a native pi extension, a CLI bridge and function-calling schemas. Thirteen agent systems and frameworks documented, ten verified live. |
| **Yours** | Local SQLite with owner-only files, a tamper-evident audit log, portable export, and erasure that removes everything derived from a record. No telemetry. |

### Compared with what you might use today

| | A rules file or system prompt | Built-in agent memory | Twin Me Up |
|---|---|---|---|
| Works across every agent you use | Copied into each one | Within one product | One twin, over MCP |
| Learns from your corrections | No | Often, automatically | Yes, as proposals |
| You approve what it learns | You write all of it | Usually after the fact | Always, before it counts |
| Stops actions you have not allowed | No | No | Yes: grants, `ask` and hooks |
| Shows whether it actually helps | No | No | Held-out tests against baselines |
| Where your data lives | Your files | The vendor | Your machine |

## Quick start

You need Python 3.11 or later and [uv](https://docs.astral.sh/uv/) (or pipx). macOS and Linux
are tested. Windows should work but is untested.

```bash
uv tool install twin-me-up        # or: pipx install twin-me-up
twinmeup init                     # your name and a passphrase, in your own terminal
twinmeup connect --list           # every supported agent system
twinmeup connect claude-code      # the exact steps for one of them, with your paths
twinmeup doctor                   # check everything, including a live MCP handshake
```

`twinmeup init` asks for your name and a passphrase. The passphrase guards everything only you
should do: confirming lessons, granting authority, exporting and erasing. Agents are never
given it, and those commands refuse to run without it.

Only need the MCP server? After `twinmeup init`, any MCP client can start it with
`uvx twin-me-up`. Prefer the latest code? `uv tool install git+https://github.com/GitDakky/twin-me-up`.

Using Claude Desktop? After `twinmeup init`, download the `.mcpb` desktop extension from the
[latest release](https://github.com/GitDakky/twin-me-up/releases/latest) and open it. One bundle
works on macOS, Windows and Linux.

## Install with one prompt

Already working inside an agent? Paste this into it.

<details open>
<summary><b>Copy-paste install prompt</b></summary>

```text
Install Twin Me Up for me and connect it to yourself. Twin Me Up is a local, open-source
work twin: it learns how I make decisions, briefs you at the start of work and tells you when
you need my approval. Repository: https://github.com/GitDakky/twin-me-up

Work step by step and show me each command you run.

1. Install it. Prefer uv:
     uv tool install twin-me-up
   If uv is not available, use pipx:
     pipx install twin-me-up
   If PyPI cannot be reached, install from GitHub instead:
     uv tool install git+https://github.com/GitDakky/twin-me-up
   Then check with: twinmeup version

2. Ask me to run `twinmeup init` myself, in my own terminal, and wait until I say it is done.
   It sets my name and a passphrase that only I know. Do not run it for me, do not ask me for
   the passphrase, and never type a passphrase anywhere.

3. Run `twinmeup connect --list`, pick the entry that matches you (or `generic`), then run
   `twinmeup connect <entry>` and carry out the steps it prints to register the MCP server and
   install the skill. If it offers optional enforcement hooks, show me the action map and the
   hook configuration first, and install them only if I agree.

4. Run `twinmeup doctor` and report the result.

5. If your system needs a new session to load MCP tools, tell me. Otherwise call twin_brief
   for workflow "general" and summarise what it says.

While you work with my twin:
- Call twin_brief at the start of a piece of work.
- Call twin_authorise before anything consequential: sending, paying, publishing, deleting or
  committing on my behalf. If the answer is "ask", stop and ask me.
- When I correct you, record it with twin_record_correction.
- Never try to confirm lessons, grant authority, export or erase. Those are mine, and the twin
  will refuse you anyway.
```

</details>

The agent installs the package, connects itself and checks the result. The two steps that
matter stay with you: choosing the passphrase, and approving any enforcement hooks. The prompt
is also in [docs/install-prompt.md](https://github.com/GitDakky/twin-me-up/blob/main/docs/install-prompt.md).

## How it works

```mermaid
flowchart LR
    you([You])
    twin[("Your twin<br/>local store")]
    agent["Any agent"]
    hook{{"Pre-action hook"}}
    you -- "confirm lessons<br/>grant authority" --> twin
    twin -- "candidate lessons<br/>to review" --> you
    agent -- "twin_brief<br/>twin_authorise" --> twin
    agent -- "record decisions<br/>and corrections" --> twin
    agent -. "every governed tool call" .-> hook
    hook -- "ungranted: block or ask" --> agent
    hook -- "checks grants" --> twin
```

### The loop

1. **Orient.** At the start of work the agent calls `twin_brief`. It gets your confirmed
   guidance for the workflow, with boundaries and escalation rules always included, and a list
   of what it is authorised to do.
2. **Check.** Before anything consequential it calls `twin_authorise`. The answer is `allow`
   only when a live grant covers the action. Otherwise it is `ask`, and the agent stops to ask
   you.
3. **Learn.** When you make a decision or correct the agent, it records the decision or the
   correction and proposes lessons from it.
4. **Ratify.** You review the queue and confirm, revise or reject each lesson. Only confirmed
   lessons reach future briefs.
5. **Prove.** You freeze held-out decisions and test the twin against two baselines before
   trusting it with more.

### Tools your agents get

| Tool | What it does |
|---|---|
| `twin_brief` | Your confirmed guidance and current authority for a workflow. Call it at the start of work. |
| `twin_authorise` | May I do this now? Returns `allow` with the covering grant, or `ask`. |
| `twin_request_approval` | Ask you to approve one action. You decide in your own terminal. |
| `twin_approval_status` | Has the request been approved, declined or not yet decided? |
| `twin_search` | Find c