How to share a project together with the explanation behind it

What does sharing a project with its explanation mean?

It means the other person gets the files and the reasoning that connects them: what was decided, why, what is still open, and what supports each decision. Klypix is a portable project workspace with a shared brain, so that reasoning sits on the same canvas as the files and travels with them.

Take a café opening. The folder holds the lease, the floor plan, supplier quotes and photos of the space. A new partner needs more than that. They need to know why the counter moved to the left wall, which supplier was turned down and why, and whether the outdoor seating licence is still an open question.

How do you make the reasoning easy to follow before you share?

Give each decision its own card with its reason, put the evidence next to it, and connect the two with a labelled arrow. Someone opening the project for the first time can then follow the reasoning with fewer questions for you.

1. One decision per card. State the decision and its reason in a sentence or two: “The counter moves to the left wall, because the water supply runs there.” In a project brain, agents record decisions, open questions and milestones with a small set of markers in the card text. The markers are plain text, so a card you type with the same marker counts the same way.
2. Open questions get their own cards. Write down what is still undecided, such as “Do we need a separate licence for outdoor seating?” In a project brain, open questions carry a ❓ marker, and the app’s Unresolved view lists them, oldest first.
3. Put the evidence on the canvas. Drop the photo, the floor plan or a screenshot of the supplier’s quote next to the decision it supports. Dropped files and images are copied into the .klypix file byte for byte, so the evidence travels with the project and keeps working if the originals are moved, renamed or deleted. By default, small folders are copied in the same way and big ones stay on disk. A folder that stays on disk, or a very large file, becomes a linked card: the canvas shows it, but its bytes stay on your PC.
4. Use arrows that say what they mean. Connect evidence to a decision with a “supports” arrow, and a risk to a plan with “blocks” or “conflicts with”. Klypix arrows can carry one of eight relationships (leads to, depends on, relates to, conflicts with, supports, questions, costs and blocks) plus a free-text label. Each connection also records whether a person or an agent drew it.
5. Correct decisions instead of deleting them. When a decision changes, keep the old card. Add the new decision and draw an arrow from the old card to the new one labelled “superseded by”. In a project brain, answers from the brain tools then point to the newer decision, and a reader can still see what was tried first. When an agent records an explicit correction through the brain tools, the old card is archived with that arrow and a date, never deleted.

Code projects can go one step further. A decision captured in Claude Code with an evidence anchor can cite the exact code it was decided against. When that file’s committed content changes, the next Claude Code session’s brief flags the card for re-checking. This check runs only through Claude Code’s hooks, the author has to attach the anchor, and a flag means the cited code changed, not that the decision is wrong.

Which way of sharing should you use?

Choose by who is receiving the project and whether they need to change it. Send the file to someone who uses Klypix, share a link with someone who only needs to look, invite people who will work on it with you, and export for people who use other tools.

How do you send the .klypix file itself?

Save the canvas and send the .klypix file the way you send any other file: by email, through a shared folder or on a USB drive. The recipient opens it in Klypix for Windows, which is free to download, and gets the same cards, embedded files and arrows you have. Linked cards are the exception: their bytes stay on your PC. If the other person needs a folder that stays on disk, choose Embed into file on its card before you send the file.

A .klypix file is a plain ZIP you can unzip and read. manifest.json holds the metadata, canvas.json holds the layout, connections and settings, items/ holds one JSON file per card, and assets/ holds the embedded files. The parser is published in the free, Apache-2.0 klypix-mcp library, so tools and agents can read the file without the app.

Sending the file gives the other person their own copy. Their changes stay in that copy until they send it back. If they are not on Windows, share a link instead.

How does a share link work?

A share link lets anyone who has it open the project in a browser, read-only, with no account and no install.

1. Share from the app. Open the canvas in Klypix and choose Share. Sharing needs you to be signed in.
2. Let it encrypt and upload. The file is encrypted on your machine before it is uploaded.
3. Send the link. Choose Copy link. The link opens the web viewer at klypix.com/c/…, which is read-only, with pan and zoom.

Once a canvas is shared, Klypix keeps the cloud copy up to date as you edit, while that canvas is the open tab in the app. Sharing is per canvas: a canvas reaches the cloud only when you share it.

To limit who can open it, switch the share to members-only, so that opening it requires signing in as a member. You can also approve or deny access requests, and revoke the link permanently so it no longer opens the canvas. Anyone who already opened the canvas keeps the copy they saw. The stored canvas and its edit history are gated in the database, but the live collaboration channel is not yet membership-gated, so someone who previously had the link may still be able to observe live editing.

Who can read a shared project?

Anyone who holds the link (unless the share is members-only) or accepts your invitation can read it, and Klypix can read some parts of every share. Which parts depends on how you share it. For a link share, the key that decrypts the canvas file is in the link. For an email invitation, Klypix stores the key on its servers. With either kind of share, the canvas title and the live edits can be read by Klypix.

So neither kind of share means Klypix cannot see your canvas, and a link deserves the same care as the file itself. The privacy policy has the details.

How do you invite people to work on it with you?

Invite them by email from the Share dialog. They sign in, accept the invitation, and the canvas appears in their library with editor access.

As the owner, you can see who has access, remove someone, or hand ownership to someone else. A collaborator can also leave a canvas someone shared with them.

Several people can work on the same canvas at once, with live cursors, presence, in-canvas chat and an activity feed. People viewing through a link appear alongside the desktop editors. Editing happens in Klypix for Windows; the browser view is read-only. Live collaboration traffic is not end-to-end encrypted and the live channel is not yet membership-gated, so use it for work you are comfortable sharing with everyone who has, or has had, the link.

There is one collaborator role. Invited people are editors and link recipients are read-only. Sharing is per canvas, so there is no team or workspace object to set up. Link sharing and invitations work on every account today; see pricing for current plan details.

What if the other person does not use Klypix?

Export the canvas to Markdown or JSON Canvas and send them the result. Save the canvas, right-click it, choose Save & export, then Export as Markdown… or Export as JSON Canvas….

• Markdown writes the cards grouped by area as sections, then a list of connections and a list of assets, with the embedded files extracted alongside. The arrows come out as the connections list, so the reasoning survives as plain text next to real files.
• JSON Canvas writes the board in JSON Canvas 1.0, an open file format for canvas boards, with the assets extracted. It suits someone who uses a tool that reads that format.

Neither export is a lossless round trip. Matching each image or file to its card is best-effort. Some Klypix card types (code, video, audio, approval and canvas-link cards) have no equivalent in JSON Canvas.

How does a software team share a project brain?

Commit brain.klypix with your code so the reasoning moves when the code moves, or use Brain Sync so each teammate’s copy catches up while Klypix has it open. A project brain is a .klypix file that people and supported AI coding tools both read and update. For the Atlas mobile app, it might hold the decision to keep refresh tokens on the server, the approach that was rejected, and an open question about how long a sign-in session should last.

Through Git

1. Set up each machine. Run npx klypix-mcp install inside the project. It gives the project a brain.klypix if it has none and, in a Git repository, registers the .klypix merge driver.
2. Commit the brain. It is one file in your repository, committed with your code: versioned, branchable and portable.
3. Pull as usual. When two people change the brain, a pull unions both sides’ cards instead of stopping at a binary conflict, once each machine has registered the driver.
4. Review with the right tool. Git shows the brain as a binary file. npx klypix-mcp diff main lists the cards added, updated and removed.

Registration is per machine. A clone without the merge driver gets an ordinary conflict on brain.klypix. Supported coding tools reach the brain over MCP through the free klypix-mcp engine, and the Windows app shows the same file as a map a person can inspect. The shared project memory guide covers the setup in more detail.

With Brain Sync

Share a project brain once from the Klypix app and invite your teammates. While Klypix for Windows has that brain open, each copy syncs by itself through an encrypted cloud copy: when the brain is opened, when an agent writes to it, and when you come back to the window. You can also sync on demand from the sync button.

The merge runs on each PC with the same three-way engine as the Git merge driver, so an edit on one side survives a delete on the other. A dot on the sync button shows whether that copy is in sync, needs you, has never synced, or is view-only.

Brain Sync is not continuous. It runs on those three events, not on a timer, and only the brain open as the current canvas syncs. An agent’s write to a brain that is not open reaches the cloud when that brain is next opened. Because teammates are invited by email, Klypix’s servers hold that brain’s key. Brain Sync does not carry session presence or file-overlap warnings; by default, those stay on each machine. Keep every PC that syncs a brain on Klypix 1.3.171 or later.

What are the limits?

• It shares what was written down. Klypix does not reconstruct reasoning nobody recorded, and corrections are not detected automatically. A person or an agent has to record the correction.
• Sharing is not blanket end-to-end encryption. Titles and live edits can be read by Klypix, and for email invitations Klypix holds the key.
• Members-only does not yet cover the live channel. Someone who previously had the link may still be able to observe live editing.
• Revoking is not recalling. A revoked link no longer opens the canvas. Anyone who already opened the canvas keeps the copy they saw.
• Shared copies update only while the canvas is the open tab in the app. Open the link to check what others see.
• Simultaneous edits are handled simply. If two people change the same card at once, the last change to arrive wins, and each person’s undo history is their own.
• Brain Sync can revert a concurrent edit. Two PCs syncing at the same moment can undo one of the edits. With Auto-save off, unsaved local edits are not included in a sync.
• Exports are not lossless. Markdown and JSON Canvas exports are not a lossless round trip.
• Linked cards do not travel. A folder that stays on disk, or a very large file, is linked rather than copied, so the .klypix file and a shared link do not carry its bytes.
• Size caps apply. An embedded folder holds up to 200 MB per file and 1 GB in total; files over the cap are skipped and listed on the card. A very large canvas can be too big to share, and the Share dialog tells you when that happens.
• The desktop app runs on Windows. People on other systems can view a shared project through a link.
• You choose and run the agents. Klypix does not launch, route or supervise them.

Where should you start?

Start with one project you need to hand over. Add the three decisions a newcomer would ask about first, one open question, and the evidence for each, then connect them with labelled arrows. Send it to one person and ask them to explain the project back to you. Whatever they miss is what the canvas does not say yet.

Download Klypix for Windows to build the canvas. For code projects, begin with the shared project memory guide. For current plan details, see pricing.