Iwacu — Family Tree

Iwacu means "home" in Kinyarwanda. The app is a family tree builder, a communication tool, and a privacy-respecting group space for your family — in one place.

Overview

The screen has three areas:

• The tree canvas — the visual representation of your family. Drag to pan, pinch or scroll to zoom.
• The terminal — at the bottom, collapsible. Every action in the app can be done from here.
• The side panel — opens on the right when you select a person or family.

A floating Script Editor button (📜) in the toolbar opens a separate panel where you can write, save, and run multi-line scripts.

Terminal commands

Person commands

person add <alias> --first <name> [--last <name>] [--gender male|female|other] [--born YYYY-MM-DD] [--died YYYY-MM-DD]

Add a person to the tree. The alias is a short label you use in other commands.

person find <query>

Search people by name. Returns a list of matches with their aliases.

person show <alias>

Open the person's detail panel.

person list

List all people in the tree with their aliases and short details.

person alias <newAlias> <existingAliasOrName>

Give an existing person an additional alias. The second argument can be an existing alias or a partial first-name match.

person edit <alias> --first <name>

Update a person's fields. You can update any combination of --first, --last, --gender, --born, --died.

person delete <alias>

Permanently delete a person. This removes all their family memberships, bridges, personal alias, and any family aliases where they held a parent role. A confirmation summary is shown before the deletion executes.

me <alias>

Set yourself as the focal person. Your alias will appear in group chats and on the connection map.

Family commands

family couple <familyAlias> <alias1> <alias2> --first1 <name> --gender1 <male|female> --first2 <name> --gender2 <male|female> [--last1 ..] [--last2 ..] [--born1 ..] [--died1 ..] [--born2 ..] [--died2 ..] [--name "Family Name"]

Create two people and a family node in one step. This is the fastest way to start a tree or add a new couple.

family new <familyAlias> <parentAlias1> [parentAlias2 ...] [--name "Family Name"]

Create a new family node from existing people.

family child <familyAlias> <personAlias> [--first <name> --last <name> --gender .. --born ..]

Add a child to a family. If --first is given, a new person is created on the spot; otherwise an existing alias is used.

family marry <newFamilyAlias> <childAlias> <spouseAlias> [--first .. --last .. --gender .. --born ..] [--name "Family Name"]

Create a bridged family: someone who is already a child in one family starts their own. If the spouse does not exist yet, include the person flags to create them inline.

family show <familyAlias|personAlias>

Open the family panel. Accepts person aliases too — it shows all the families that person belongs to.

family open <familyAlias>

Open the family panel (members, chat, invite tabs).

family list

List all family nodes with their aliases.

family chat <familyAlias> <message>

Send a message to a family group chat from the terminal.

family invite <familyAlias>

Show the invite link for a family cell.

family join <invite-link>

Join a family using an invite link.

Tree commands

tree demo

Load a sample Rwandan family tree to explore the app.

tree clear

Remove everything and start fresh.

tree focus <personAlias> [--origin]

Navigate the tree canvas to a person. With --origin, the view centres on their parents' family instead.

tree export [--format yaml|json|script]

Export the tree. The default format is YAML, which can be re-imported. Use --format script to export as a sequence of terminal commands that can reconstruct the tree from scratch — useful for version control, sharing, or running in the Script Editor.

tree import

Paste a YAML or JSON tree definition directly into the terminal to restore or merge a tree.

tree merge

Open the Merge dialog to connect your tree with a cousin's tree. See Connect Branches.

Navigation commands

go <alias> [--origin]

Navigate to a person or family by alias. Accepts person aliases, family aliases, or a partial first-name match.

Alias commands

aliases

List all current aliases — persons and families — with their full names.

person alias <newAlias> <existingAliasOrName>

Assign a new alias to an existing person.

unalias <alias>

Remove a person or family alias. Does not delete the person or family — only the short name.

help

Print a summary of available commands.

Script Editor

The Script Editor lets you write, save, and run multi-line scripts against the tree.

Open it with the 📜 button in the toolbar.

Writing a script

Each line is a terminal command. Comments start with #. Blank lines are ignored.

# Build the Kamanzi family
family couple gen1 father mother --first1 Habimana --gender1 male --first2 Uwera --gender2 female --name "Kamanzi Family"
family child gen1 alice --first Alice --gender female --born 1998-06-12
family child gen1 bob --first Bob --gender male --born 2001-03-04

Dry run

Click Dry Run to preview what the script would do without making any changes. Results appear line-by-line. Any error is highlighted. Nothing is saved. Aliases and tree data return to their state before the dry run when it finishes.

This is the safe way to test a script before running it for real.

Saving scripts

Click Save (💾) to give the script a name and save it to the local database. Saved scripts appear in the Library (📂). From the library you can load, run, or delete any script.

Exporting as script

To turn your current tree into a replayable script, run:

tree export --format script

The output is a sequence of commands in dependency order — parents before children, root families before bridged ones. Copy the output into the Script Editor to save it.

Device sync

Sync your tree across all your own devices without sharing access with anyone else.

Open Manage → Sync → My devices to set up device sync.

Pairing a second device

1. On the first device, tap Enable sync then Show pair QR.
2. On the second device, open Manage → Sync → My devices and tap Scan pair QR (or paste the pair code manually).
3. Both devices connect to the same personal cell on the relay. Changes you make on one device appear on the other within seconds.

The pair code format is iwacu://devicesync/<id>/<secret>?relay=<url>. The relay sees only the encrypted payload — it cannot read your tree.

Connection status

A coloured dot next to My devices shows the connection state:

• Green — connected and syncing
• Grey — not connected (relay unavailable or not yet paired)

The side panel

Click on any person or family node in the tree to open the side panel.

Person view

Two tabs:

Details — Shows the person's full name, birth/death dates, and which families they belong to (as child, as parent).

Chat — A private direct message thread with that person. Messages are encrypted and delivered over the family cell. The person must have joined the tree via invitation to receive messages.

Family view

Three tabs:

Members — Lists all parents and children in the family. Each member row has a 🔗 button to generate a personal invitation for that slot.

Chat — Group chat for all members of this family who have joined. Think of it as the family WhatsApp group, but one that cannot be read by anyone outside the family cell.

Invite — Quick link to generate a family-level invitation. Use this when you want someone to join but have not yet decided which person record they are.

Invitations

Two types of invitations exist:

Person invitation — ties a new member to a specific record in the tree. Generate from Members → 🔗. The recipient joins as that person.

Family invitation — lets someone join the family cell without being assigned a specific person record yet. Use this for members you want to chat with before completing their record.

See Invite Family Members for the full flow.

Touch and pointer interactions

On the tree canvas:

• Hover / tap a person chip to reveal a 💬 button — tap to open their chat tab directly.
• Hover / tap a family card to reveal a 💬 button — tap to open the family group chat.
• Double-click / double-tap a person chip to navigate to their origin family (parents).
• Ctrl+double-click (desktop) or long-press (touch) to navigate to their own family (children and spouse).

Data persistence

Tree data is stored in a local SQLite database on your device. Changes are saved automatically after every action — you do not need to export manually to preserve your work between sessions.

Export is still useful for:

• Sending your tree to another person or device without pairing
• Version control — keep a tree.yaml in a folder you back up
• Reconstructing the tree on a fresh install

tree export --format yaml

Copy the YAML and keep it somewhere safe. To restore, paste it directly into the terminal.

Cross-tree bridges

After completing a tree merge with a cousin, a bridge appears in the tree as a dashed link between the shared ancestor and the cousin's branch. Click the cousin's person record to open a direct message thread with them — this works the same as messaging any other person in your own tree.