Quick Start (5 Minutes)

Goal: Complete the full loop in 5 minutes — launch the app → create your first agent → have your first conversation → create a Todo → see memory in action → use the CLI. Assumes you've completed the Installation Guide.

Step 1: Launch the App

Option A: Electron Full Stack (Recommended)

bash

cd electron
npm run electron:dev

Startup sequence:

Vite dev server starts at http://localhost:5173
Electron window opens and loads the Vite page
Electron automatically spawns the Python bridge subprocess (.venv/Scripts/python.exe -m src.bridge.run)
Bridge listens on https://127.0.0.1:18711 (hypercorn + HTTP/2 + self-signed certificate)
Prewarm phase: embedder (bge-m3) → rembg → rewriter → most recent agent's digital human model
Desktop shell (Desktop.vue) renders, showing the app icon grid

Startup logs are available in workspace/.bridge.log. GPU detection results are cached in workspace/gpu_tier.json.

Option B: Bridge Only (Backend Testing / No GUI)

bash

.venv/Scripts/python -m src.bridge.run

Once the bridge is running, you can use the CLI or browse to https://127.0.0.1:18711.

Step 2: Your First Agent

After launch, agent 1 (the Manager) is already running by default. The Manager is the special agent 0/1, responsible for:

Global summaries and persona evolution
Framework documentation index (injected into the system prompt every turn)
Cross-agent routing and coordination
Debug tools (list_framework_docs / read_framework_doc / list_logs / read_log)

Create a New Agent

Click the ＋ button in the AgentRail on the left sidebar, or:

The CreateAgentKindModal pops up — select an agent type (regular / special role)
Fill in a name, choose a role template (or leave it empty to let the system auto-generate a persona based on USER.md)
After confirming, the system will:
- Create the workspace/agents/agent_<id>/ directory
- Initialize the dialogue tree (dialogue_0/)
- Generate avatar assets (theme_assets/)
- Register the agent in the SQLite database

The new agent appears in the AgentRail list; click it to enter its chat view.

Agent Settings

Click the gear icon on an agent row in the AgentRail to open AgentSettings:

Change the name and theme color
Configure theme_color (affects chat bubbles, title bar highlight)
Adjust agent-specific parameters (intense_mode / turbo_mode / security_level, etc.)

Step 3: Your First Conversation

Sending Messages

Type directly in the InputBar at the bottom and press Enter to send:

Say "Help me plan today's schedule" → the agent calls the Todo/Schedule tools
Say "Remember what I just said" → triggers a memory write (memorizer)
Say "Read today's USER.md" → triggers memory retrieval (RAG)
Say "Help me write a file to the desktop" → triggers the privacy approval card (PrivacyApprovalCard)

Each message triggers the agent's plan → tool call → answer pipeline:

The Planner analyzes the intent and decides whether a tool is needed
The ToolDispatcher routes to the specific tool (DailyTools / BrowserTools / MemoryTools — one of the 15 default instances)
The synthesizer integrates the tool results to produce the final answer

Approval Cards

When an operation requires approval (writing files / high privilege / sensitive information), a PrivacyApprovalCard pops up:

Shows the operation about to be performed + desensitized parameters
Click Allow to continue, Deny to cancel
The approval threshold is controlled by security_level (high / medium / low)

In a development environment you can set FAMILIARS_APPROVAL_DISABLED=1 to disable all approvals (not recommended for production).

Voice Input

Click the 🎤 speaker icon on the left side of the InputBar to enter push-to-talk mode:

Hold to speak; release to auto-recognize (faster-whisper)
The recognized text is filled into the input box; you can edit it before sending

Split-Screen Mode

Click the split-screen button at the top of the ChatStage to view two agents' conversations side by side:

Left pane: main agent
Right pane: split agent
Each pane has its own message stream, input bar, and digital human panel

Step 4: Your First Todo / Schedule

Creating via Conversation

Just tell the agent:

Help me sync today's weather to the weekly meeting every day at 9 AM

The agent automatically splits this into:

Todo: a to-do item (title + deadline + priority)
Schedule: a calendar entry (start/end time + repeat rule)
Cron Job: a scheduled task (APScheduler cron expression)

Creating via the UI

Click the Todo/Schedule icon at the top, or press Ctrl+Shift+L (global shortcut):

QuickCreateModal pops up; choose a type (Todo/Schedule/Cron)
Fill in the form manually, or click "LLM-assisted extraction" to have the model extract structured data from clipboard text
After confirming, view it in TodoScheduleModal

Creating via the CLI

bash

# Create a todo
python main.py todos create --title "Buy milk" --deadline 2026-07-05T18:00

# List todos
python main.py todos list --pretty

# Complete a todo
python main.py todos complete <todo-id>

# Create a schedule
python main.py schedule create --title "Weekly meeting" --start 2026-07-06T09:00 --end 2026-07-06T10:00

# Create a cron job
python main.py cron create --expr "0 9 * * *" --prompt "Sync today's weather"

Step 5: Viewing Memory

Dialogue Tree View

Click the dialogue tree icon on the right side of the ChatStage to open TreeMini (mini view) or TreeFull (fullscreen view):

Each message is a node (Node) in the tree, with an embedding vector (bge-m3)
The Full view supports dragging, zooming, jumping, and replaying
Right-click on the tree: jump & replay / set as current / export

Memory Retrieval

Say "Review the X I was following last month" in a conversation to trigger RAG retrieval:

rewriter rewrites the query (workspace/rewriter/prompt.md)
dense recall (bge-m3 embeddings + hnswlib index)
sparse recall (BM25)
reciprocal rank fusion (RRF, k=60)
reranker (bge-reranker-v2-m3) re-ranks
The top-K results are injected into the context

Memory Writing

During a conversation the agent automatically decides whether memory is needed:

ephemeral: valid for a single turn, evicted at the end of the turn
dialogue: persisted to workspace/agents/agent_<id>/dialogue_<n>/
agent: persisted across conversations to workspace/agents/agent_<id>/
user / identity: persisted globally to workspace/USER.md / IDENTITY.md

Memory categories: event / state / profile / procedure / directive, each with its own decay constant.

Memory Management

The memory entry at the bottom-right / side of the chat page: view the current agent's dialogue tree and long-term memory
The Manager can see every agent's memory size on the settings / reports page
Right-click an agent in the AgentRail → Release memory to manually release an inactive dialogue tree (DialogueManager.release_memory)

Step 6: Common CLI Commands

The CLI is the bridge's command-line wrapper (main.py), covering all REST endpoints (except WebSocket streams).

Basic Usage

bash

# View help
python main.py --help                    # list command groups
python main.py agents --help             # list actions in the agents group
python main.py agents list               # run an action

Agent Management

bash

# List all agents
python main.py agents list --pretty

# Create an agent (SSE streaming)
python main.py agents create --name "Assistant" --role "Support"

# View agent details
python main.py agents get --id 1

# Release an agent's memory
python main.py agents release-memory --id 1

Chat

bash

# SSE streaming chat
python main.py chat stream --prompt "Hello" --agent-id 1

# Synchronous chat (waits for the complete answer)
python main.py chat send --prompt "How's the weather today?" --agent-id 1

# View chat history
python main.py chat history --agent-id 1 --dialogue-id 0

Todo / Schedule / Cron

bash

# Todos
python main.py todos create --title "Buy milk" --deadline 2026-07-05T18:00
python main.py todos list --pretty
python main.py todos complete <id>

# Schedules
python main.py schedule create --title "Weekly meeting" --start 2026-07-06T09:00
python main.py schedule list

# Cron jobs
python main.py cron create --expr "0 9 * * *" --prompt "Sync weather"
python main.py cron list

Skills / Recipe / Flow

bash

# Skills
python main.py skills list
python main.py skills forge --description "Auto-generate a weekly report"

# Recipe
python main.py recipes list
python main.py recipes compile --id <recipe-id>

# Flow
python main.py flows list
python main.py flows get --id <flow-id>

Broker / Marketplace

bash

# Broker
python main.py broker keys-list
python main.py broker pack --dir workspace/manager/brokers/my_broker
python main.py broker sign --file my_broker.broker.zip
python main.py broker install --file my_broker.broker.zip

# Marketplace index
python main.py broker marketplace-index

Authentication

The CLI automatically reads the X-Bridge-Token from workspace/.bridge_token. Override methods:

bash

# Command-line argument
python main.py --token <token> agents list

# Environment variable
export BRIDGE_TOKEN=<token>
python main.py agents list

# Specify a token file
python main.py --token-file /path/to/token agents list

Bridge Port

The CLI automatically reads workspace/.bridge.port (written by the bridge at startup). If 18711 is occupied, the bridge picks a new port and writes it to that file; the CLI follows automatically.

Override method:

bash

python main.py --base-url https://127.0.0.1:18712 agents list

Step 7: Going Further

Everything installed and want to play? Next steps:

Interface Tour — walk through all the main interface components
Creative Workshop — manage Recipes / Flows (User Manual · Creative Workshop)
Skill Forge — describe a need and auto-generate SKILL.md (User Manual · Skill Forge)
Broker Marketplace — install collaborative apps such as Ventaris (Ecosystem Tutorial)
Digital Human — render AI digital humans locally (requires a GPU, Digital Human chapter)
Voice Calls — push-to-talk + ASR + TTS (Voice Input)

Step 8: Common Pitfalls

Symptom	Cause / Fix
Conversation keeps spinning	Check `BASE_URL` / `API_KEY` in `.env`; if no model responds, switch `DEFAULT_MODEL`
Tool calls stuck waiting for approval	This is normal privacy-by-design behavior; click Allow on the approval card, or disable it with `FAMILIARS_APPROVAL_DISABLED=1` (not recommended)
Memory writes take a long time	First run needs to download the `bge-m3` model; it's fine afterwards
Digital human doesn't show up	Requires a local GPU and the GPT-SoVITS models; it's an advanced feature, see Digital Human
Bridge startup reports a port conflict	Normal — the bridge automatically switches ports and writes to `workspace/.bridge.port`; the CLI reads it automatically
Electron window won't open	Check `workspace/.bridge.log` to see whether the bridge started; check whether `.venv` is activated correctly
CLI reports 401 Unauthorized	`X-Bridge-Token` missing or wrong; check whether `workspace/.bridge_token` exists
Slow model responses	Check whether `MAX_TURNS` (default 50) is too large; check network latency to `BASE_URL`
Inaccurate memory retrieval	Adjust `RAG_DENSE_TOPK` / `RAG_RERANK_MIN_SCORE`; make sure `EMBEDDING_MODEL` is downloaded

Next: Interface Tour →

Quick Start (5 Minutes) ​

Step 1: Launch the App ​

Option A: Electron Full Stack (Recommended) ​

Option B: Bridge Only (Backend Testing / No GUI) ​

Step 2: Your First Agent ​

Create a New Agent ​

Agent Settings ​

Step 3: Your First Conversation ​

Sending Messages ​

Approval Cards ​

Voice Input ​

Split-Screen Mode ​

Step 4: Your First Todo / Schedule ​

Creating via Conversation ​

Creating via the UI ​

Creating via the CLI ​

Step 5: Viewing Memory ​

Dialogue Tree View ​

Memory Retrieval ​

Memory Writing ​

Memory Management ​

Step 6: Common CLI Commands ​

Basic Usage ​

Agent Management ​

Chat ​

Todo / Schedule / Cron ​

Skills / Recipe / Flow ​

Broker / Marketplace ​

Authentication ​

Bridge Port ​

Step 7: Going Further ​

Step 8: Common Pitfalls ​

Quick Start (5 Minutes)

Step 1: Launch the App

Option A: Electron Full Stack (Recommended)

Option B: Bridge Only (Backend Testing / No GUI)

Step 2: Your First Agent

Create a New Agent

Agent Settings

Step 3: Your First Conversation

Sending Messages

Approval Cards

Voice Input

Split-Screen Mode

Step 4: Your First Todo / Schedule

Creating via Conversation

Creating via the UI

Creating via the CLI

Step 5: Viewing Memory

Dialogue Tree View

Memory Retrieval

Memory Writing

Memory Management

Step 6: Common CLI Commands

Basic Usage

Agent Management

Chat

Todo / Schedule / Cron

Skills / Recipe / Flow

Broker / Marketplace

Authentication

Bridge Port

Step 7: Going Further

Step 8: Common Pitfalls