carry docs
Everything carry does, with the exact commands. carry runs on your computer and shares through your own Google Drive or a synced folder. There is no carry account.
Quick start
The fastest way: let your AI do it. Copy the setup prompt and paste it into Claude Code, Codex or Cursor. It checks Node, installs carry and connects your Drive, asking you before each step.
The prompt points at carry-si.vercel.app/setup.md, a page written for AI assistants. Read it first if you like.
Or by hand, with Node 22.15 or newer:
Install
Works on macOS, Windows and Linux. You need Node 22.15 or newer, and git if you share whole projects.
1. Node and git
No Homebrew? Get the installer from nodejs.org. macOS asks to install git the first time you use it.
Then close PowerShell and open a new window so it finds node and git.
Other distros: any Node 22.15 or newer from your package manager or nodejs.org.
2. carry
carry uses txcript to convert chats between tools. It is downloaded and checksum-checked for your system on install, or the first time carry needs it.
3. The /carry command
Adds the /carry skill to Claude Code, Codex and ~/.agents. Type /carry in a chat and the AI runs the commands below for you.
Connect Google Drive
carry needs somewhere to put shared chats. Pick one, once per laptop.
Web mode (default)
Opens Google sign-in in your browser. You sign in and click Allow. carry asks only for drive.file: it can see and edit the files it creates, nothing else in your Drive. The name after --as is what friends see. Add --with a@gmail.com,b@gmail.com to share with the same people by default.
If Google shows "Google hasn't verified this app", click Advanced, then continue.
Synced folder mode
Already use Google Drive for desktop, Dropbox or iCloud? Point carry at a folder and share that folder with your group. No Google sign-in.
Your chats
carry reads Claude Code chats from ~/.claude/projects and Codex chats from ~/.codex/sessions. Names come from the first real prompt, with secrets removed. Rename any chat with carry name.
Share with friends
Pair once
The codes carry a key that encrypts everything you send each other (AES-256-GCM). carry friends lists who you're paired with; carry friend remove <name> unpairs.
Send, open, send back
The chat opens on Riya's own account, so her tokens are used. If you also kept working on your copy, carry opens her version next to yours and overwrites nothing.
Send back automatically
Share with --auto-return and Riya's carry sends the chat back after she works on it, when carry sync runs. carry install-hook runs it after every Claude Code session.
Share without pairing
A private (email) link opens in Riya's browser; she clicks Download and carry picks the file up from Downloads. carry packs lists what you've shared, and carry sync re-uploads shared chats that changed.
Share a whole project
A project pack holds the newest chats started in the repo (5 by default, --chats N), any you --add, minus any you --skip (or --related for all related chats), Claude Code's memory notes, CLAUDE.md and AGENTS.md, and a handoff. The code itself goes through git.
Claude Code gets your memory notes and a handoff note where it reads them at the start of a session. Codex gets a .carry/ folder and a pointer line in AGENTS.md. Nothing of Riya's is overwritten: a note changed on both sides is kept as <note>.from-<friend>.md.
Open and continue
carry open <name | file.carry | Drive link | inbox number> --to <target>
| --to | What happens |
|---|---|
claude_code | Loaded as a real Claude Code session, full history. Tested end to end. |
codex | Converted into a Codex session. |
opencode · cursor · pi | Converted by txcript. Less tested. |
chat | For claude.ai, ChatGPT or the Claude app: copies a prompt and shows the handoff file to attach. |
here | Prints the handoff and history, for an AI that is already reading your terminal. |
Chat apps
claude.ai, ChatGPT and the Claude app keep chats on their servers, so carry can't read their history. Ask the AI to write a handoff (goal, what was done, decisions, next steps), save it, and share it as a summary:
With the connector installed, just say "share this conversation with Riya" and the AI writes and sends the summary itself.
Use it inside AI apps
carry runs as an MCP connector. Add it once, then ask in plain words. It always runs the latest version. You need Node installed, nothing else.
Claude Desktop: one click
Double-click the file (or drag it into Claude Desktop) and click Install.
Claude Code: plugin
Installs the connector and the /carry skill together.
By hand: Claude Desktop, Codex, Cursor
Claude Desktop: Settings, Developer, Edit Config. Merge with any servers already there, save, restart Claude.
Add it to ~/.codex/config.toml (Windows: %USERPROFILE%\.codex\config.toml) and restart Codex.
Cursor Settings, MCP, Add new global MCP server. Paste into ~/.cursor/mcp.json and save.
Then just ask
"Connect carry to my Google Drive" · "Share this chat with Riya" · "What's in my carry inbox?" · "Open the first one in Codex" · "Send it back to Riya".
Connector tools
| Tool | Does |
|---|---|
carry_status | Is carry set up, where shares go, update notice. Read only. |
carry_connect_google_drive | Opens Google sign-in in your browser. |
carry_list_chats · carry_list_projects | Your chats and projects, by name. Read only. |
carry_share_chat · carry_share_project | Share to friends, emails or a link, with a handoff the AI writes. |
carry_share_summary | Share this conversation from a chat app as a summary. |
carry_add_friend | Make or accept a pairing code. |
carry_inbox · carry_list_shared | What friends sent you; what's been shared. Read only. |
carry_open | Open a share here, or as a real session in a coding tool. |
carry_return | Send a chat or project back with your work. |
All commands
| Command | What it does |
|---|---|
carry setup --web [--as name] [--with emails] | Connect Google Drive in the browser |
carry setup [folder] [--as name] | Use a synced folder instead |
carry install-skill | Add /carry to Claude Code, Codex and ~/.agents |
carry list · carry name <chat> <new name> | This laptop's chats, by name; rename one |
carry friend add <email or code> · friend remove <name> · friends | Pair once with a friend |
carry share <chat> --to <friend> [--auto-return] | Into their inbox |
carry share <chat> [--with emails] [--link] [--handoff file] | Share without pairing |
carry projects [name] | Your projects, or the chats in one |
carry share --project [name] [--chats 5] [--add a,b] [--skip c] [--related] [--to friend] | Share a whole repo |
carry note "<name>" --handoff file [--with emails] [--link] | Share just a summary |
carry inbox | What friends sent you, including your own chats coming back UPDATED |
carry open <ref> [--to target] [--dir folder] | Continue it here (see targets) |
carry return <chat> · return --project <name> | Send borrowed work back |
carry install-hook | Run carry sync after each Claude Code session |
carry sync · carry packs | Re-upload changed shares; list your shares |
carry mcp | Run as an MCP connector |
carry update · carry doctor · carry --version | Update; check setup; version |
Updates
Run carry update. carry checks npm once a day and tells you when a new version is out; turn that off with CARRY_NO_UPDATE_CHECK=1. The connector (@heyvamz/carry@latest) updates itself. See the changelog.
Privacy and security
- carry runs on your computer. Chats go from your computer to your Google Drive (or synced folder) and nowhere else. No carry server, no telemetry.
- Google access is
drive.fileonly. Your sign-in token stays in~/.carry/google.json, readable only by you. Revoke it at myaccount.google.com/permissions. - Before anything leaves your laptop, carry replaces common secret shapes with [REDACTED]: OpenAI, Anthropic and Sarvam keys, GitHub tokens, AWS and Google keys, Slack tokens, JWTs, Bearer tokens, private keys and
KEY=valuelines. It is pattern based, so don't share chats full of secrets you care about. - Friend shares are encrypted with AES-256-GCM using a key that lives only in your pairing codes.
- Shared files stay in your Drive until you delete them. Settings live in
~/.carry/.
Troubleshooting
carry: command not found
npm's global bin folder isn't on your PATH. Run npm prefix -g, add its bin folder to PATH and open a new terminal. On Windows, open a new PowerShell window.
Permission denied on npm install -g (Linux)
Use sudo npm install -g @heyvamz/carry, or install Node with nvm so global installs don't need root.
Couldn't get txcript
Run carry doctor again once you're online. Opening with --to chat or --to here doesn't need txcript.
Sign-in times out or the browser doesn't open
carry prints the sign-in link; open it yourself. It waits 5 minutes.
My Codex chats don't show up
carry reads ~/.codex/sessions (or $CODEX_HOME/sessions). Chats from the Antigravity app and from claude.ai or ChatGPT on the web can't be read; share a summary instead.
The connector doesn't show up
Restart the app after editing its config. Check node -v is 22.15 or newer. On Windows the config must use "command": "cmd" with "/c", "npx".
Opening a project changed nothing
carry never overwrites existing files; it prints "kept your existing …" for those. Merge by hand if you want the incoming version.
More: TROUBLESHOOTING.md · open an issue
FAQ
Can I move a Claude Code chat into Codex?
Yes. carry open <ref> --to codex converts the full conversation into a Codex session.
Do I need the Google Drive app?
No. Web mode signs in through your browser. If you already use Drive for desktop, Dropbox or iCloud, you can use a synced folder instead.
Can carry read my claude.ai or ChatGPT web chats?
Not yet. Those live on their servers. Share a summary instead.
Does it work on Windows and Linux?
Yes. Every release is tested on macOS, Windows and Linux.
What does it cost?
Nothing. carry is free and open source (Apache-2.0).