Iwacu — Family Tree

Iwacu means "home" in Kinyarwanda. The app is a family tree builder, a private communication tool, and a persistent record of your family history — stored on your devices, not on any server.

The three areas of the screen

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

A floating 📜 button in the toolbar opens the Script Editor. The toolbar also has buttons for Terminal, Manage families, Historical atlas, Article editor, Connect Trees, Profile, and Settings.

Terminal commands

The terminal is the fastest way to build and navigate the tree. Open it with the 🌳 button. Drag the top edge to resize it.

Person commands

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

Create a new person. The alias is the short name you use in all other commands. --first is required; everything else is optional.

person find <query>

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

person show <alias>

Print full details for a person — name, dates, which families they belong to — and open their detail panel.

person list

List everyone in the tree with their aliases.

person alias <newAlias> <existingAliasOrName>

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

person edit <alias> [--first <name>] [--last <name>] [--gender ..] [--born ..] [--died ..]

Update any fields on a person. Only the flags you supply are changed.

person delete <alias>

Permanently delete a person. Removes all their family memberships, personal alias, and any family aliases where they held a parent role. The terminal prints a summary before deleting.

me [alias]

Set yourself as the focal person. With no argument, prints your current identity. Your alias appears in group chats and on the connection status 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 family node from existing people.

family child <familyAlias> <personAlias> [--first <name> --last .. --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 already in a family as a child starts their own family. If the spouse does not exist yet, include the person flags to create them inline.

family show <familyAlias|personAlias>

Print full details of a family and open the panel. Accepts a person alias too — shows all families that person belongs to, with a connected/total member count.

family open <familyAlias>

Open the family side panel directly (Members, Chat, Invite tabs).

family list

List all family nodes with their aliases and member counts.

family chat <familyAlias> <message>

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

family invite <familyAlias>

Print the invite link for a family cell.

family join <invite-link>

Join a family cell using an invite link. The family node is added to your tree and its members appear in the chat.

Tree commands

tree demo

Load a sample Rwandan family tree. Clears any existing tree first. Good for exploring before building your real tree.

tree clear

Delete everything and start fresh. Aliases are cleared too.

tree focus <personAlias> [--origin]

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

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

Export the entire tree. Default format is YAML. Use --format script to export as a sequence of terminal commands that can rebuild the tree from scratch — useful for version control and the Script Editor. Use --format json for machine-readable output.

tree import

Prompts you to paste a YAML or JSON block into the terminal. Multi-line paste is detected automatically — you can also just paste without running the command first.

tree merge

Open the Connect Trees dialog to exchange QR codes with another person and link a shared ancestor. See Connecting two trees.

tree link

Print the connect-trees link for your focal person — the same link the Connect Trees QR encodes, without opening the dialog. Hand this to whoever runs tree connect.

tree connect <link> <myPersonAlias> [--direction lateral|ancestor|descendant]

Consume a tree link from another tree, bridging it to a person in yours. The scriptable equivalent of the Connect Trees dialog — useful for setting up several trees and connecting them entirely from scripts, with no dialog interaction needed. See Connecting two trees.

Navigation and alias commands

go <alias> [--origin]

Navigate to a person or family by alias or partial first-name match. With --origin, centres on the origin family.

aliases

List all registered person and family aliases with what they point to.

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.

The manage page

Open Manage from the toolbar or go to /manage. This is the data management layer — a table view of your entire tree alongside device sync and settings.

People table

All people are listed in a grouped table, one row per person per family membership. From here you can:

• Edit inline — click any name, date, or gender field to edit it directly.
• Add a family — tap + New Family to create a couple and family node through a form (the same as family couple in the terminal).
• Manage aliases — the alias column shows each person's short name; click to change it.

Device sync

The Sync → My devices section keeps the tree in sync across your own devices without sharing access with anyone else.

Pairing a second device:

1. On the first device, tap Enable sync → Show pair QR.
2. On the second device, tap Scan pair QR (or paste the pair code manually).
3. Both devices connect to the same private cell on the relay. Changes appear within seconds.

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

A coloured dot shows connection state:

• Green — connected and syncing
• Grey — not connected

Settings

The ⚙ icon in the toolbar opens settings:

• Display name — the name others see in group chats.
• Identity QR / bundle export — export your Ed25519 identity for use in abantu. See Using your identity with abantu.
• Relay URL — the WebSocket relay your sync uses. Change this if you self-host.

Family history: articles, biographies, and the atlas

Two toolbar buttons unlock a second layer on top of the tree: a written archive of your family's history, and a historical map of Rwanda to place it on.

Historical atlas

Open Historical atlas (the map icon) to see Rwanda's prefectures and communes on a map, switchable between historical eras — the names and boundaries shown change to match the period you select, since prefecture names have changed over time.

• Click a region to see its details in the Selected region panel; click it again to clear the selection.
• Map settings lets you switch between visual presets and toggle commune-level borders on the fine-detail layer.

Article editor

Open Article editor (the file icon) to write biographies and other articles about people in your tree.

• The main panel is a markdown editor with a formatting toolbar (headings, bold, etc.) and a live Preview tab.
• Upload lets you attach images — each one is embedded into the article text and shown resolved in the preview. Images you've already uploaded this session appear in a gallery so you can reuse them without uploading twice.
• Save persists the article. Reopen any past article from the dropdown at the top instead of starting a new one each time.

My Articles and Manage

Two more tabs turn the editor from "one article at a time" into an archive you can act on:

• My Articles lists every article you've authored, most recently updated first. A small badge shows how many suggestions are waiting on an article. Click a row to open that article and jump straight into Manage.
• Manage is where you act on the currently open article:
  • Assign to a person's history — search for a person and attach the article to them as part of their record; link or unlink any of that person's key moments from the article from the same panel.
  • Pending suggestions — anyone can propose a change to someone else's article (a different title or body, with a note explaining why). If you're the article's author or your family node's admin, you'll see Approve and Reject buttons on each suggestion here; approving merges the suggested change straight into the article.
  • A ← My Articles link at the top of Manage returns you to the list without losing your place.

Script Editor

Open the 📜 button in the toolbar. Each line is a terminal command. Comments start with #. Blank lines are ignored.

# Build the Kamanzi family from scratch
family couple gen1 father mother \
  --first1 Habimana --gender1 male --last1 Kamanzi --born1 1955-04-02 \
  --first2 Uwera --gender2 female --last2 Mugabo --born2 1958-09-14 \
  --name "Kamanzi Family"
family child gen1 me --first Ishimwe --gender male --born 1984-11-22
family child gen1 sister --first Ineza --gender female --born 1987-03-10
me me

Dry run

Click Dry Run to preview what the script would do without making any changes. Each line's result is shown. Errors are highlighted. All aliases and tree data revert when it finishes.

Saving scripts

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

Managing scripts from the terminal

Everything the Library panel does is also available as terminal commands — useful for setting things up without switching panels, or from a script itself.

script list

List every saved script.

script create <name> [--from <existingScriptName>]

Create a new saved script. Empty by default; with --from, starts as a copy of an existing script's contents.

script open <name>

Open a saved script in the Script Editor — the same as clicking it in the Library.

script run <name> [--dry]

Open a saved script in the Script Editor and run it there, so you see it execute in the real editor rather than silently. Add --dry to preview without making changes.

Exporting the tree as a script

tree export --format script

Outputs the current tree as terminal commands in dependency order — parents before children, root families before bridged ones. Copy the output into the Script Editor to save a replayable snapshot.

Inviting a family member

Person invitation (recommended)

A person invitation ties the new member to a specific record in the tree.

1. Open a family panel: click a family card, or run family open <alias>.
2. Go to the Members tab.
3. Click 🔗 next to the person you want to invite.
4. Share the generated link with the right person by any trusted channel.

When they open the link and accept, they join as that specific person. They get access to the family group chat and can receive direct messages from other connected members.

Family invitation

Lets someone join a family cell without being assigned a specific record yet — useful when you want to chat before completing their entry.

1. Open the family panel → Invite tab.
2. Share the link.

You can assign them to a specific person record later.

Connecting two trees

Use this when you have found a cousin who maintains their own separate tree and you share a common ancestor.

What connecting does

After connecting, a bridge appears in both trees as a dashed line between the shared ancestor in your tree and the corresponding person in your cousin's. You can open a direct message thread with your cousin from their person record in your tree.

The two trees stay independent — you keep yours, they keep theirs. Only the bridge and the message channel are shared.

How to connect

1. Run tree merge or click Connect Trees in the toolbar.
2. Choose the relationship direction:
   • Lateral — you and the other person are at the same generation (cousins).
   • Ancestor — the other person's tree extends further back.
   • Descendant — your tree extends further back.
3. One person taps Show QR, the other taps Scan QR.
4. Both sides confirm the shared person. Tap Connect.

The bridge is established on both sides.

Touch and pointer interactions

On the tree canvas:

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

Data persistence

Tree data is stored in a local SQLite database. Changes are saved automatically after every action.

Export is still useful for:

• Off-device backup
• Sending your tree to someone without relay access
• Version control (tree.yaml in a backed-up folder)
• Rebuilding on a fresh install

tree export --format yaml

Paste the output somewhere safe. To restore, paste it directly into the terminal — multi-line paste is auto-detected.

Desktop app (Electron)

Iwacu is delivered as an Electron desktop application for Windows, macOS, and Linux. The Electron shell wraps the Nuxt app — the full experience (tree canvas, terminal, script editor, manage page) runs natively on the desktop without a browser.

Build the desktop app:

pnpm build:electron

This runs nuxt build first, then packages with Electron Builder. Output lands in dist-electron/.

The desktop app stores its SQLite database in the system user-data directory, separate from any browser instance. Device sync, the relay, and all features work identically on desktop and mobile.

Using your identity with abantu

Your iwacu identity — an Ed25519 keypair with a did:iwacu: identifier — is the same identity used by abantu, the community governance app. You do not need two accounts. Import once, use everywhere.

Export from iwacu

1. Open Settings (⚙ in the toolbar).
2. Tap Show identity QR — or Copy bundle text for the clipboard method.

The QR encodes a base64 bundle containing your DID, display name, and keypair. Only share it with your own devices.

Import into abantu

1. Open abantu. On the welcome screen, choose Import from iwacu.
2. Point the camera at the QR shown in iwacu.

Your display name and keys are imported in one scan. You can now join abantu communities using the same identity that your family members already know from iwacu.

No camera? Use the clipboard method:

• In iwacu: Settings → Show identity QR → Copy bundle text
• In abantu: choose Paste identity bundle and paste

See the Abantu documentation for what you can do once your identity is imported.

The side panel

Person view

Details — Full name, birth/death dates, gender, and family memberships (child in, parent in). A 🔗 button generates a personal invitation for that slot.

Chat — A private direct message thread. Encrypted over the family cell. The person must have joined via invitation to receive messages.

Family view

Members — All parents and children. A green dot marks members who have connected. 🔗 next to each row generates a personal invitation for that person.

Chat — Group chat private to all members who have joined. The relay cannot read it.

Invite — Quick link for a family-level invitation (not tied to a specific person record).