Twin Me Up

[Twin Me Up: a personal work twin for every AI agent]

[PyPI] [Python versions] [CI] [OpenSSF Scorecard] [Licence: Apache-2.0] [Model Context Protocol]

Teach it once. Every agent you use works the way you would, and asks before it acts.

Quick start · One-prompt install · How it works · Works with · The research · Safety

[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]

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 explains why.

What makes it different

Compared with what you might use today

Quick start

You need Python 3.11 or later and uv (or pipx). macOS and Linux are tested. Windows should work but is untested.

uv tool install twin-me-up        # or: pipx install twin-me-uptwinmeup init                     # your name and a passphrase, in your own terminaltwinmeup connect --list           # every supported agent systemtwinmeup connect claude-code      # the exact steps for one of them, with your pathstwinmeup 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.

Upgrading? Run uv tool upgrade twin-me-up (or pipx upgrade twin-me-up), then twinmeup doctor. The FAQ explains what an upgrade changes for your twin.

Using Claude Desktop? After twinmeup init, download the .mcpb desktop extension from the latest release and open it. One bundle works on macOS, Windows and Linux.

Install with one prompt

Already working inside an agent? Paste this into it.

Install Twin Me Up for me and connect it to yourself. Twin Me Up is a local, open-sourcework twin: it learns how I make decisions, briefs you at the start of work and tells you whenyou 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", prepare a draft, request my approval with  twin_request_approval, and act only once twin_approval_status says it is approved.- Give every write a request_id, so a retry never records anything twice.- When I correct you, record it with twin_record_correction.- Never try to confirm lessons, approve requests, grant authority, export or erase. Those are  mine, and the twin will refuse you anyway.

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.

How it works

flowchart LR    you([You])    twin[("Your twin<br/>local store")]    agent["Any agent"]    hook{{"Pre-action hook"}}    you -- "confirm lessons<br/>grant and approve" --> twin    twin -- "candidate lessons<br/>to review" --> you    agent -- "twin_brief<br/>twin_authorise<br/>request approval" --> 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: the agent prepares a draft, requests your approval and waits for your decision.
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

What only you can do

These commands need your passphrase, so agents cannot run them.

Approvals

An agent that needs an action it has not been granted asks for it, then waits:

1. twin_authorise says ask. The agent prepares a draft and calls twin_request_approval with a one-line summary of what and why.
2. You see the request with twinmeup approvals list and decide in your own terminal: twinmeup approvals approve <id>, or twinmeup approvals decline <id> --note "why".
3. The agent checks twin_approval_status and acts only once it says approved.

An approval grants exactly the action requested, once and for an hour, unless you say otherwise (--uses 3, --for 1d). Where a hook enforces, the tool call that acts spends it, so another attempt needs another request. Every approval and decline is also recorded as a decision, so your twin learns where your lines are. Requests survive restarts, and an agent that asks twice gets its first request back.

Write tools also take an optional request_id. A retry with the same id, after a dropped connection or a crash, returns the first result instead of recording twice.

Works with

twinmeup connect <system> prints the exact steps for each of these, using the paths on your machine. All the guides are also in docs/integrations.md.

Checked in October 2026 against current releases. The host checks ran on 0.1.0; 0.2.0 adds two tools to the same MCP server, and the Pi Durable check ran on 0.2.0. The framework checks are reproducible with scripts/interop/frameworks.py. Got it working somewhere marked "not yet run"? Tell us how.

No MCP? Export function-calling schemas and dispatch calls through the CLI:

twinmeup tools schema --format openai > twin-tools.jsontwinmeup --actor agent:my-bot tools call twin_authorise '{"workflow": "general", "action": "email.send"}'

Teach your twin

Start small: one workflow you repeat often, such as reviewing quotes or triaging requests.

1. Write down the red lines. These are carried into every brief and never ranked out.

twinmeup probes onboarding      # questions worth answering for a new workflowtwinmeup lesson propose --workflow quote-review --kind boundary \  --statement "Never instruct a contractor without my written approval." \  --origin written_rule --confirm

2. Record real decisions. Agents do this with twin_record_decision as you work. You can also add them yourself from JSON (see examples/); records you add yourself ask for your passphrase, because they carry your name.

twinmeup episode add examples/episode.quote-review.jsontwinmeup episode gaps <episode-id>      # what the record does not yet explain

3. Review what it proposes. Nothing an agent proposes has authority until you say so.

twinmeup lesson list --status candidatetwinmeup lesson confirm <lesson-id> --note "Yes, always"twinmeup lesson revise <lesson-id> --statement "Only for quotes over budget"

4. Grant authority narrowly, and let it expire.

twinmeup grant add --workflow quote-review --action draft.prepare --expires 2026-12-31twinmeup grant list

Lessons come in seven kinds: fact, criterion, exception, escalation, procedure, boundary and preference. Each records whether it was a written rule, elicited from you, inferred by a model or learned from a correction.

Measure it

Do not trust a twin because it sounds like you. Test it on decisions it has not seen.

twinmeup eval create --name holdout --workflow quote-reviewtwinmeup eval from-episode <set-id> <episode-id>     # or: eval add-case <set-id> case.jsontwinmeup eval freeze <set-id>
export OPENROUTER_API_KEY=...                         # or use endpoint: with a local modelfor arm in generic rules twin; do  twinmeup --actor agent:eval eval run <set-id> --arm $arm --responder openrouter:<model>donetwinmeup eval report <run-id>

Each case is answered three ways with the same model:

The twin has earned its keep only if it beats the rules arm. Reports show agreement with your choices and how often the twin correctly escalated, with warnings when the sample is too small to mean much. twin_track_record moves a workflow from observe to draft to supervised as evidence accumulates. A stage is advice, not authority: more autonomy still needs an explicit grant from you.

docs/pilot-guide.md describes a six-week pilot for one workflow.

Safety model

• Human-only operations need your passphrase. It is stored as a salted scrypt hash and read from your terminal, never from an agent's arguments.
• Agents cannot set themselves up as you. Setting up an unprotected twin has to be done from a real terminal.
• Reserved actions. Anything under twin. can never be granted, so no grant can hand an agent control of the twin itself.
• Approvals cover one action, once. Only you can approve or decline, with your passphrase. An approval grants exactly the action requested, for one use and an hour unless you say otherwise. Where a hook enforces, every tool call is a new attempt, so an id a host reuses cannot ride on a spent approval.
• Enforcement fails closed. If a hook cannot reach a decision, the tool call is blocked. The example action maps also stop agents running human-only commands, writing to the twin's store or editing the host configuration that registers the hook.
• Tamper-evident audit. Every write is appended to a hash chain. twinmeup audit verify checks it.
• Signed, reproducible releases. Packages are built in GitHub Actions and published to PyPI with trusted publishing and attestations. No long-lived tokens exist.
• Honest limits. Twin Me Up runs as you. Any program running as your user can read your files. The passphrase stops agents using the twin's own commands to act as you, and hooks stop governed tool calls, but neither is a sandbox. For hard isolation, run agents as a different user or in a container.

See SECURITY.md for the threat model and how to report a vulnerability.

Where it can still fail

Twin Me Up narrows what agents may do. It does not make an agent safe on its own.

• Without a hook, the twin advises. Over MCP alone it tells an agent what it may do, and nothing stops an agent that ignores it. Enforcement needs a pre-action hook: Hermes, Claude Code, Cursor, pi or Pi Durable.
• Hooks govern only mapped calls. A tool or command your action map does not match is left to the host's own permissions.
• Without a hook, an approval is time-boxed, not single-use. The hook is what spends it, so over MCP alone an approved action stays allowed until it expires.
• A grant is not a sandbox. An allowed action runs with the agent's full permissions.
• Retries are safe only with a request_id. A write retried without one can be recorded twice.
• Your passphrase is the boundary. Anyone with it and your terminal can confirm lessons and approve requests. Agents never receive it, and a compromised machine is out of scope.
• Files are private, not encrypted. The store and settings are readable only by your user account. Encryption at rest is not built in yet.
• A prediction is not consent. The twin learns how you decide, and never treats a forecast of your answer as your approval.

Your data

• Everything lives in ~/.twinmeup (set TWINMEUP_HOME to move it). Files are readable by you only.
• twinmeup export twin.bundle.json writes a portable bundle. Held-out evaluation answers stay sealed unless you ask for them.
• twinmeup erase episode <id> --reason "..." removes a decision and every lesson, handoff and evaluation case derived from it, and redacts it from the audit log while keeping the chain valid.
• The twin itself never calls a model and sends nothing anywhere. The only network calls are the evaluation responders you choose to configure.

The research

Before writing code we reviewed the primary research on digital twins of people, expertise transfer and AI assistance. The headline results:

That is why the twin never infers authority, why learning needs your confirmation, why it asks follow-up questions about omitted reasons, and why it is tested against baselines instead of trusted on feel. The full review, with every source and the regulatory lines it draws (including the EU AI Act's prohibition on workplace emotion inference), is in docs/research.md.

Command reference

FAQ

Roadmap

• Enforcement hooks for more hosts as their hook interfaces allow
• Encryption at rest for the store
• Signed bundles for moving a twin between machines
• A small local review app for lessons and approvals
• Verified guides for VS Code, Goose and Windows
• The Pi Durable extension out of experimental, with a verified map for pi's coding tools

Follow along, or pick something up, in issues and discussions.

Contributing

Contributions are very welcome, from a typo fix to a new agent integration. Good first issues are a gentle start, and CONTRIBUTING.md explains the setup, the one-command check and how reviews work. Please report security issues privately, as described in SECURITY.md.

Credit and licence

Twin Me Up was created by GitDakky and is released under the Apache License 2.0. If you redistribute it or build on it, the licence requires you to keep the NOTICE file, which credits the original author. Using it in research? GitHub's "Cite this repository" button gives you a ready-made citation.

If Twin Me Up is useful to you, a star helps other people find it.

[Star history]

Built on the Model Context Protocol.