Start here: ReachWeaver in plain words

This guide is for you if you are not a developer, or you are new to this tool. It explains what ReachWeaver does, the few ideas you need, and how one post goes from idea to published. No account or password is needed to read it or to try the first steps.

Looking for the exact commands in order? Use the quickstart. Meeting an unfamiliar word? See the glossary. Something went wrong? See troubleshooting. Forgot a command? reachweaver --help lists the everyday ones in plain words, and reachweaver --help all lists every command.

The idea in one minute

You made something real: a software release, a paper, a talk, a demo. You want the right people to see it. Writing a good post for every network, keeping track of what you sent, and not making a costly mistake is a lot of careful work.

ReachWeaver is a careful helper for that work. It has two halves:

• Claude Code (an AI assistant that runs in your terminal or editor) does the thinking and writing: researching your audience and drafting posts.
• ReachWeaver’s commands do the careful bookkeeping: checking drafts, recording your approval, previewing the send, remembering what happened, and refusing anything unsafe.

The most important rule: nothing is sent until you approve that exact post. The AI can suggest and draft. Only you can approve.

Prefer clicking instead of typing commands?

Open the local browser composer once from your ReachWeaver directory:

python3 -m reachweaver share --web --open

Then write your message in the browser, choose the social networks, preview the different posting files, and save a local folder. Nothing goes online. Browser composer guide.

The easiest option: prepare a post to paste into an app

You can use ReachWeaver without connecting Instagram, TikTok, Facebook or any other account. In a terminal in the ReachWeaver folder, type:

python3 -m reachweaver share --guide

Answer which social networks you want, type a caption, give a photo or video to check if you like (or press Enter), type a video title if you chose YouTube (it is required there; pressing Enter twice skips YouTube), review the plan and press Enter to save it (Save these files? [Y/n]; saving only writes files on your computer). A mistyped network, command or option gets a “Did you mean …?” with the right spelling. The new OPEN-FIRST.md file gives you simple steps, and each network has its own copy-ready text file and checklist. You then open the real social app and post manually. No one is logged in, and nothing is uploaded or published by this command.

After you post, copy the link to your post from the app’s share menu and record it, with the numbers you see, in one command: reachweaver posted https://bsky.app/profile/you.bsky.social/post/3k... --likes 12 --replies 3. ReachWeaver works out the network from the link and asks when you posted it (press Enter for today, or type yesterday or a date such as 2026-10-19); its last lines show how your week is going (This week so far: 3 posts · 49 likes · 3 replies · best: ..., the same numbers reachweaver report --week starts with), so you do not need a second command for that. Run the same command again a few days later with the new numbers to update them. Got the day wrong? Run it again with --at yesterday (or the date) and the record is corrected. It only writes a note on your computer. Got an idea for later? reachweaver idea "Behind the scenes of my studio" saves it (several at once: reachweaver idea "first idea" "second idea"), and then shows the command to write your top idea right away; reachweaver next offers your ideas back whenever you are ready.

For two networks in one command, try python3 -m reachweaver share --platform instagram,threads --text "Our new tutorial" --out state/my-post. LinkedIn, Bluesky, Mastodon and Telegram work the same way: you get text to copy, even with no account connected. If your caption is too long for a network, that network’s copy is shortened at a sentence end or a word (a closing link is kept) and marked SHORTENED with what was removed, and a photo or video you name with --attach is checked offline against that network’s documented sizes and durations. For photographs, video and human-only communities, see Easy sharing. Automatic account publishing is a separate, approval-first workflow explained below; reachweaver account-add bluesky adds your account to it without ever asking for a password, then asks Connect it now so ReachWeaver can post for you? [y/N] (press Enter to skip: posting by hand needs no connection; y goes straight into the connection guide).

Five ideas you need

Idea	In plain words
Draft	A saved post that has not been approved or sent. You can edit or delete it freely.
Approval	Your explicit “yes” to one exact post. ReachWeaver ties the approval to the exact text. If anyone changes even one character, the approval stops counting and you must approve again.
Dry run	A rehearsal. ReachWeaver shows what it would do and contacts nobody. This is what happens by default.
Live send	A real post on a real account. It needs several deliberate switches on top of your approval, so it cannot happen by accident.
Manual export	For networks ReachWeaver cannot send to, it prepares the text and a checklist, and you copy it into the app yourself.

The journey of one post

Here is one post, step by step. The commands are real and work offline. The names my-bluesky and POST_ID come from the example files; ReachWeaver prints your real post ID when you create a draft.

1. Draft. Write the text yourself or ask Claude to. Save it as a draft for one account:

reachweaver draft --account my-bluesky --file examples/example-post.txt --campaign first-campaign

ReachWeaver prints Created draft POST_ID for my-bluesky; not published and, in a terminal, the next step: Next: reachweaver review (go through your drafts) or reachweaver show POST_ID. The draft is stored in a private database on your computer.

2. Review. See exactly what would be sent:

reachweaver show POST_ID
reachweaver check POST_ID

show prints the exact text, the account it is for, its status and a preview of how the network will display it. check points out problems such as placeholder text, a post that is too long, or a mention of someone who asked not to be tagged. It also looks at your history: if this account already shared the same video, image or wording on the same platform, check says BLOCKED and approve will refuse unless you pass --allow-repeat on purpose. If you post things by hand, tell ReachWeaver once with mark-shared so it can warn you next time. See the repeat guard. Fix the text and draft again if needed.

3. Approve. When you are happy with it:

reachweaver approve POST_ID --approver YOUR_NAME

This records your decision and locks it to the exact text. It still sends nothing.

4. Rehearse. Run the send as a dry run:

reachweaver publish --post-id POST_ID

You should see DRY RUN: 1 due approved posts; no requests sent. The post stays approved, waiting. If you only wanted to practise, you can stop here.

5. Send, or hand over.

• If the account is on a platform ReachWeaver can send to, and you have finished the security checklist and account onboarding, a real send is a separate, deliberate command that you run yourself. It is described in the first live pilot. Start with one post on a throwaway account.
• If the platform is not supported for sending, use manual-export to get a ready-to-paste package and post it yourself. See manual export.

6. Look back. reachweaver journal lists what you posted, when, on which account, with the exact text, who approved it, the link and the files. reachweaver archive --copy-files saves the same record as a private folder with copies of the files, so you still have them if you move or delete the originals. See the journal guide.

7. Record and learn. After a post is live, copy its numbers from the app’s insights with reachweaver metrics POST_ID --likes 40 --replies 3 (for a post you made by hand, reachweaver posted LINK --likes 40 --replies 3 needs no id) (recorded now; --observed-at yesterday works too) or import the platform’s own export, then run reachweaver report --week for a short summary with your best posts first. Numbers you do not have are shown as unknown (-), never as zero. Record each post again about 7 days after posting: that is the age insights compares. reachweaver next tells you which posts are due and names your saved ideas with a ready command. See attribution and the weekly report example.

Three ways to use it

You are…	Use	Best for
Comfortable chatting with an AI assistant	Claude Code with the /reachweaver skill (see the README)	Research, campaigns, drafts. Claude runs the checks for you and always stops for your approval.
Comfortable with a terminal	The reachweaver commands directly	Full control, scripting, a repeatable routine.
Not ready to connect any account	Offline mode plus manual export	Preparing posts and plans, then pasting them in by hand. This needs no credentials at all.

You can mix them. For example, let Claude draft, then review and approve in the terminal.

What is safe to try right now

Everything in the quickstart is safe. It uses example accounts, a throwaway database and no network. You cannot post by accident, because the live switches are off.

What you need before a real send

Not sure which accounts are ready? reachweaver connect prints a status table without contacting anyone, and reachweaver connect --guide walks you through connecting them one at a time in your own terminal.

All of these, never fewer:

1. An account that you own or are allowed to post for.
2. Credentials for it, created with the narrowest permissions and kept only in your own environment. Never type them into Claude, a chat, an issue, or a file in the repository. Account onboarding shows how for each platform.
3. A post you approved with approve.
4. The three live switches, set on purpose: --live, REACHWEAVER_ALLOW_LIVE=1 and REACHWEAVER_ENV=prod.
5. Your read-through of the security checklist.

Today the real-send adapters are for Bluesky, Mastodon, Telegram and LinkedIn personal profiles, text only. Only Bluesky and Mastodon have been proven with real posts. See the platform matrix for the dated status of everything.

Questions people ask

Will it post by itself? Not by default. Every send needs your approval of that exact post and the live switches. Advanced users can set up a scheduled sweep that only sends posts you already approved; that is described in worker operations and is a deliberate setup, not something that happens on its own.

Does it need my password? No. It never asks for or stores your password. For platforms that allow it, you create a limited-permission token (for Bluesky an App Password, never your main password) and keep it in your own environment.

Can I move to another computer? Yes. Keep everything that is yours in one folder: reachweaver workspace --init ~/reachweaver-work, then work from inside it. It starts with no accounts (in a terminal it asks which networks you use and adds a placeholder for each); add yours with reachweaver account-add bluesky, and remove one with reachweaver account-remove ID. The folder holds your accounts file, database, approval ledger, archive, media and logs, and no passwords or tokens. On the new computer install ReachWeaver, copy the folder, and run reachweaver workspace --repair --apply; then set your credentials again. See your workspace folder.

Where is my data? On your computer, in the state/ folder, in a database only your user can read. ReachWeaver has no server of its own and uploads nothing there. The only things that touch the internet are a send to the platform you chose (--live), commands you start with an explicit --online flag, and a once-a-day check for a newer ReachWeaver release when it runs as a Claude Code plugin (you can turn that off). The README lists exactly what each one contacts. See also the privacy policy.

Can I take something back? Before it is sent, yes: unapprove POST_ID withdraws approval and cancel POST_ID removes it from the queue. After it is sent, ReachWeaver cannot delete a post for you; delete it in the platform’s own app.

What if I am unsure whether a post went out? ReachWeaver will not guess and will not resend. The post is marked needs_review and that account is held until you look at the real account and tell ReachWeaver what happened with reconcile. This is on purpose, so you never double-post by accident.

What if something looks wrong right now? Run reachweaver pause. It stops all publishing immediately. reachweaver resume turns it back on once you have checked.

Will it make my post go viral? No tool can promise that, and ReachWeaver does not. It helps you write platform-appropriate posts, avoid mistakes, and measure what actually happened.

Is it allowed to post on Reddit or Hacker News for me? No. Those communities expect posts written and submitted by a person, so ReachWeaver writes nothing for them. It can still help you understand their rules.

Good habits

• Start with one post, on a test account, and check it on the real platform.
• Read the show output every time before you approve. The approval is only as good as your reading.
• Keep credentials out of anything you share, including screenshots and bug reports.
• Put claims you cannot source (numbers, “first”, “fastest”) through claims-check, or leave them out.
• When in doubt, use manual export. You lose nothing but a copy and paste.

Where to go next

• Quickstart: the safe ten-minute walk-through.
• All documentation by goal.
• All features in detail.