Before you start
- A Mac on a recent macOS with Node.js 20 or newer.
- Claude Code, Codex, or both, installed and logged in the way you already use them. Tweety Bird finds whichever you have.
- Telegram on your phone. iMessage, WhatsApp, Slack DM, and Discord also work; see Pair your phone.
- Your license key. It is on the welcome page after checkout and in the welcome email.
Run it
npx tweetybird --license YOUR-KEYPlain npx tweetybird works too; it asks for the key during setup. Run it from the repo you work in most. That folder becomes the default working folder for the thread.
The five steps
1. It finds your agents
It looks for claude and codex on your PATH and in the usual install spots, checks the version, and checks that each one is logged in. If you only have one, it says so and carries on. You can add the other later and run tweetybird doctor.
2. You pair your phone
Setup walks you through making a Telegram bot with BotFather: send /newbot, pick a name, paste the token back into the terminal. It checks the token, then prints a six-digit pairing code and a t.me link. Send the code to your bot (or tap the link). That account is now the only one this Mac answers. The code works once and expires in 15 minutes.
3. It reads your instruction files
CLAUDE.md, AGENTS.md, and DECISIONS.md in the repo are read into shared memory for that repo, so both agents carry what is in them from the first text. Your files are not changed. See CLAUDE.md and AGENTS.md.
4. You set the policy
The default is safe: reads, tests, lint, local edits, and branch pushes and PRs run unattended. Money, prod, messaging, and deletes wait for your tap. Change it now or later, per repo, with /policy. See Permission policy.
5. You run the proof
Tell Claude Code one real decision about your repo, something you have actually re-explained before. Then ask Codex about it. When Codex answers with the decision, setup prints "Codex recalled it. You're in." and your first text from the thread arrives on your phone.
What it installs
| Path | What it is |
|---|---|
~/.tweetybird/config.json | Settings, bot token, allowlist. Mode 0600. |
~/.tweetybird/env | The auth variables your agents need, copied from your login shell. Mode 0600. |
~/.tweetybird/app, ~/.tweetybird/bin | The installed copy the background service runs. Never the npx cache. |
~/Library/LaunchAgents/dev.tweetybird.daemon.plist | The background service. Starts at login, restarts if it crashes, keeps running with no terminal open. |
~/.tweetybird/logs/daemon.log | The log. tweetybird logs -f follows it. |
Nothing is installed inside Claude Code or Codex. Tweety Bird runs them the way you do, as their own programs, so their updates never break the thread.
Trial and the proof
Every plan starts with a seven-day trial. The card is collected at checkout and not charged during the trial. If the proof does not land, text /cancel or reply "goldfish" to any email and nothing is charged. After that, the Goldfish Guarantee covers 60 days.
Updating
npx tweetybird@latestThis refreshes the installed copy and restarts the service. Your config, pairing, schedules, and memory stay.
Uninstalling
tweetybird uninstallRemoves the service, the installed copy, and local data, and frees the machine slot on your license. --keep-data keeps ~/.tweetybird. --forget-memory also deletes your shared memory. --yes skips the confirmation.