Interface Tour

An interactive walkthrough of the Familiars main interface. This page focuses on "where things are and what they do." For full operational details, see the User Manual.

1. Main Window Layout Overview

┌────────────────────────────────────────────────────────────────┐
│ TitleBar (Identity chip / Drag area / Pin / Minimize / Maximize / Close) │
├──────────┬─────────────┬───────────────────────────────────────┤
│ AgentRail│ DialogList  │ Main Content Area (Desktop / ChatStage)│
│ · List   │ · Chats     │ ┌──────────────────────────────────┐  │
│ · + New  │ · + New Chat│ │ Desktop shell (Desktop.vue)      │  │
│ · Gear   │ · Pinned    │ │ or chat stage (ChatStage.vue)    │  │
│          │ · Right-click│ └──────────────────────────────────┘  │
│          │             │ Bottom input bar (InputBar)           │
│          │             │ Right status overlay (StatusOverlay)  │
└──────────┴─────────────┴───────────────────────────────────────┘
│ Bottom taskbar (Taskbar, visible in Desktop shell mode)        │
└────────────────────────────────────────────────────────────────┘

Three-Column Structure

Column	Component	Default Width	Notes
AgentRail	`AgentRail.vue`	212px	Agent list. The manager is always pinned to the top; the rest are sorted by most recent activity
DialogList	`DialogList.vue`	212px	The current agent's conversation list. Supports pinning, renaming, and deletion
Main content	`Desktop.vue` / `ChatStage.vue`	Auto-fit	Desktop shell (manager homepage) or chat stage (agent conversations)

Column widths are adjustable by dragging the edges (ResizeHandle); values are persisted to localStorage.

2. Title Bar (TitleBar)

File: electron/renderer/src/components/TitleBar.vue

┌──────────────────────────────────────────────────────────┐
│ [Me] (avatar + nickname)   ←—— Drag area ——→  [📌][─][□][×] │
└──────────────────────────────────────────────────────────┘

Element	Function
Identity chip `[Me]`	Click to open `UserProfileModal` — edit your user profile (nickname, avatar, preferences)
Drag area	Drag to move the window (`-webkit-app-region: drag`)
📌 Pin	Keep the window always on top (`setAlwaysOnTop`)
─ Minimize	Minimize to the taskbar
□ Maximize / Restore	Toggle the maximized state
× Close	Does not exit the app — hides to the system tray (`win.hide()`); use the tray menu to fully quit

Closing the window ≠ exiting. After closing, the Electron process keeps running, the bridge subprocess stays active, and the tray icon remains visible. Right-click the tray → "Exit background (fully quit)" to actually exit.

3. Agent List (AgentRail)

File: electron/renderer/src/components/AgentRail.vue

┌─────────────────┐
│ [manager]  ⚙   │  ← manager always pinned on top
│ [Assistant] ⚙  │
│ [Support]  ⚙   │
│ [Analyst]  ⚙   │
│                 │
│      [+]        │  ← create a new agent
└─────────────────┘

Interactions

Action	Effect
Click an agent row	Enter that agent's chat view (`store.enterAgent`)
Right-click an agent row	Pop-up menu: Settings / Release memory / Delete
Click the gear ⚙	Open `AgentSettings` (agent-specific configuration)
Click [+]	Open `CreateAgentKindModal` → create a new agent

Agent Row Visuals

Selected state: gradient swatch generated from theme_assets.selected → saturated vivid(theme_color) color → default CSS highlight
Creation placeholder: PendingAgent shows as a semi-transparent placeholder card, replaced by the real row once asset generation completes
Demo-mode lock: with VITE_DEMO_MODE=1, only the manager remains; the create button and gear are disabled

Manager Special Handling

The Manager's (agent 0/1) gear does not open AgentSettings; it opens the global SettingsCenter instead.

4. Conversation List (DialogList)

File: electron/renderer/src/components/DialogList.vue

┌─────────────────┐
│ 📌 Weekly prep 📌│  ← pinned conversation
│ 📌 Weekly report│
│ Daily chit-chat │
│ Data analysis   │
│                 │
│   [+ New chat]  │
└─────────────────┘

Interactions

Action	Effect
Click a conversation row	Switch to that conversation (`store.selectDialogue`)
Double-click a conversation row	Rename the conversation (`PromptModal`)
Right-click a conversation row	Menu: Pin / Rename / Export / Delete
Click [+ New Chat]	Create a new conversation (`dialogue_<n+1>/`)

Pinning

Frontend pinning (localStorage, stored per agent: dlgpin:<agentId>)
Pinned conversations are listed at the top; the rest are sorted by most recent message
No pinned column on the backend; purely frontend behavior

Filtering

Automatically filters out the manager's synthetic workshop conversations (cg_workshop / agent_workshop / skill_workshop / skill_approvals); these have been moved to separate windows in the desktop shell.

5. Desktop Shell (Desktop.vue)

File: electron/renderer/src/components/Desktop.vue

Desktop is the manager's default homepage (replacing the legacy ManagerLanding), similar to an OS desktop:

┌──────────────────────────────────────────────────────────┐
│ 🖼 Wallpaper background                                   │
│                                                          │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌─────┐ ┌────────┐         │
│  │Report│ │Learn │ │Create│ │Demo │ │Todo    │         │
│  │      │ │Familiars│ │Workshop│ │DEMO │ │Schedule│     │
│  └──────┘ └──────┘ └──────┘ └─────┘ └────────┘         │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌─────┐ ┌────────┐         │
│  │Settings│ │Monitor│ │Apps  │ │CG  │ │Agent   │         │
│  │      │ │      │ │Store │ │Workshop│ │Workshop│        │
│  └──────┘ └──────┘ └──────┘ └─────┘ └────────┘         │
│                                                          │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ [F] Familiars  [Reports] [Learn] [Workshop] [Todos] …│ │
│ └──────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

Built-in Apps (12)

Icon	Title	Component	Default Size	Notes
📊	Reports	`ReportApp.vue`	900×620	Daily/weekly/monthly/annual report management
📖	Learn Familiars	`LearnApp.vue`	940×640	Project introduction and tutorials
🧪	Creative Workshop	`WorkshopApp.vue`	1300×780	Recipe / Flow management
🎮	Replicate DEMO	`DemoApp.vue`	640×440	Coming soon (shakes on click)
📅	Todo · Schedule · Cron	`TodoScheduleModal.vue`	960×640	Three-in-one tabs
⚙️	Settings	`SettingsCenter.vue`	880×620	Global settings center
📡	Message Monitor	`MonitorApp.vue`	520×620	WeChat/QQ/Feishu listener status
🛍	App Store	`AppsApp.vue`	1000×660	Broker marketplace + installed apps
🎬	CG Animation Workshop	`CgWorkshopApp.vue`	700×560	CG animation generation
🤖	Agent Workshop	`AgentWorkshopApp.vue`	700×560	Agent management
🔧	Skill Workshop	`SkillWorkshopApp.vue`	700×560	Manager long-running skill forms
✅	Skill Change Approvals	`SkillApprovalsApp.vue`	700×560	Skill proposal approval queue

Broker Apps

Every installed Broker (its manifest.ui block) automatically becomes a desktop icon:

ID: broker:<broker_id>
Icon: cover.png (from the broker directory)
Window: BrokerAppWindow.vue (loads the broker UI in an iframe)
Beta badge: locally developed brokers show a gold "Beta" corner badge

Window Behavior

Double-click an icon: open/restore the window
Drag the title bar: move the window
Double-click the title bar: maximize/restore
Drag the bottom-right corner: resize
Minimize: hide the window but keep it in the taskbar
Close: remove the window from the desktop (does not exit the app)
Taskbar click: minimize ↔ restore ↔ pin

Switching Back to the Legacy Landing

Set localStorage.familiars:legacyLanding = true to switch back to the legacy ManagerLanding.vue.

6. Chat Stage (ChatStage)

File: electron/renderer/src/components/ChatStage.vue

ChatStage is the main interface for agent conversations:

┌──────────────────────────────────────────────────────────┐
│ [← Back]  Assistant  [⚙ Settings]  [🔍 Search]  [🌲 Tree]  [⫶ Split] │
├──────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────┐ │
│ │ [User] Hello                                         │ │
│ │ [Agent] Hi! How can I help you?                      │ │
│ │ [Tool call] read_file(path="USER.md")                │ │
│ │ [Agent] I've read your user profile...               │ │
│ │ [Privacy approval] Allow writing to a file? [Allow] [Deny] │ │
│ └──────────────────────────────────────────────────────┘ │
│                                                          │
│ ┌──────────────────────┐ ┌────────────────────────────┐  │
│ │ [Digital human panel]│ │ [Input bar InputBar]       │  │
│ │ (avatar / expression│ │ text + attachments + voice  │  │
│ │  / voice)            │ │ + shortcuts                │  │
│ └──────────────────────┘ └────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

Top Bar

Button	Function
← Back	Return to the desktop shell (manager homepage)
Agent name	Shows the current agent's name + theme color
⚙ Settings	Open `AgentSettings`
🔍 Search	Open in-conversation search (`localSearchOpen`)
🌲 Dialogue tree	Open `TreeMini` / `TreeFull`
⫶ Split	Switch to split-screen mode (left/right panes)

Message Area

ChatBubble: single message bubble (user / agent / tool call / approval card)
Tool call card: expands to show the tool name + arguments + result
PrivacyApprovalCard: privacy approval card (allow/deny)
PlanApprovalCard: plan approval card (confirm/modify)
AskUserCard: the agent asks the user a question (ask_user_questions tool)
EventWaitCard: waiting for an external event (emit_event tool)
CgWorkshop / AgentWorkshop / SkillWorkshop: synthetic workshop modes (replace the message area)

Digital Human Panel

Agents with a figure: show an animated avatar (DigitalHuman.vue)
Externally imported agents (openclaw / hermes / custom): show an emoji
Local agents without a figure: show the robot mascot
Split-screen mode: hides both digital human panels

Split-Screen Mode

Left pane: main agent (store.currentAgentId)
Right pane: split agent (store.splitAgentId)
Each pane has its own message stream, input bar, and digital human
Clicking the AgentRail switches the split agent while split-screen focus mode is active

Export

ChatStage supports exporting conversations:

HTML: exportHTML()
Markdown: exportMarkdown()
PDF: exportPDF()

7. Input Bar (InputBar)

File: electron/renderer/src/components/InputBar.vue

┌──────────────────────────────────────────────────────────┐
│ 📎 [Attachment area]                                      │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ [🎤]  Type a message...                              │ │
│ │                                                      │ │
│ │                              [Quick] [Send]          │ │
│ └──────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

Input Modes

Mode	Trigger	Description
Plain text	Default	Type directly; Enter to send
Attachment mode	Click 📎	Pick a file/folder (`pickFiles` IPC)
Voice mode	Click 🎤	Push-to-talk (faster-whisper ASR)
Expanded mode	Skill forms / long text	The input bar expands into a multi-line editor

Flow-Bound Input

When an agent is bound to a flow template (flow_template_id):

Has a custom renderer: the entire input area is replaced with <CustomInputRenderer>
No renderer but has custom fields: a label + textbox form is appended below the standard textarea
Reserved fields (prompt / attachments): always use the built-in controls

Keyboard Shortcuts

Ctrl+Shift+L: open QuickCreateModal (global shortcut)
Enter: send the message
Shift+Enter: insert a new line

8. Dialogue Tree View (TreeMini / TreeFull)

Files:

electron/renderer/src/components/TreeMini.vue
electron/renderer/src/components/TreeFull.vue

TreeMini (Mini View)

Shown in the right sidebar of the ChatStage
A compact tree structure with one node per message
Click a node to jump to that position in the conversation

TreeFull (Fullscreen View)

Fullscreen Canvas (VueFlow)
Nodes can be dragged, zoomed, and connected
Right-click menu: jump & replay / set as current / export
Supports branch visualization (multiple paths through the dialogue tree)

Node Types

User node: blue bubble
Agent node: theme-colored bubble
Tool call node: gray card (tool name + argument summary)
Approval node: yellow card (approval status)

9. Status Overlay (StatusOverlay)

File: electron/renderer/src/components/StatusOverlay.vue

A status indicator floating at the top-right corner:

┌──────────────────────────────┐
│ 🟢 monitor: WeChat listening │
│ 🔴 operate: operating the PC │
│ 🟣 train: model training     │
│ 🟡 monitor_active: polling   │
└──────────────────────────────┘

Status Levels

Level	Color	Description
`operate`	🔴 Red	The agent is operating the computer (pyautogui / uiautomation)
`monitor`	🟡 Yellow	Listener pre-check (startup / login check)
`monitor_active`	🔴 Red	Listener polling (reading on-screen messages)
`monitor_dispatching`	🟣 Purple	Listener paused; `generate()` is running (handling a user @ trigger)
`train`	🟣 Purple	Model training in progress
`info`	🔵 Blue	General information

Interactions

Click ⏹ Stop: stop the corresponding monitor/operation task (POST /api/monitor/{key}/stop)
Triple-Esc abort: when operate / monitor is active, press Escape three times to abort urgently
Click-through: by default the overlay window is click-through (does not affect desktop operations); it switches to interactive when a monitor status is present

10. Global Keyboard Shortcuts

Electron Global (triggerable in the background)

Shortcut	Function	Description
Ctrl+Shift+L	Quick create	Open `QuickCreateModal` (Todo/Schedule/Cron)
Ctrl+Shift+Q	Quick-ask the Manager	Open a floating window to chat with agent 0 (`QuickAskView`)
Ctrl+Shift+I	DevTools	Toggle DevTools (`F12` also works)
F12	DevTools	Same as above
Esc × 3	Emergency abort	Only works when `operate` / `monitor` is active

In-App Shortcuts

Shortcut	Function	Scope
Enter	Send message	InputBar
Shift+Enter	New line	InputBar
Escape	Close a dialog / cancel an action	Global

Quick-Create Flow

Select text in any application
Press Ctrl+Shift+L
Electron synthesizes a Ctrl+C to capture the selection (snapshot + clipboard restore)
QuickCreateModal pops up, prefilled with the captured text
Choose a type (Todo/Schedule/Cron)
Confirm manually or hand it to the LLM for extraction (DraftConfirmModal)

11. Todo / Schedule / Cron (TodoScheduleModal)

File: electron/renderer/src/components/TodoScheduleModal.vue

A three-in-one tab interface:

┌────────────────────────────────────────┐
│  [Todo]  [Schedule]  [Cron]            │
├────────────────────────────────────────┤
│  ┌──────────────────────────────────┐  │
│  │ □ Buy milk        Due: 07-05 18:00│  │
│  │ ☑ Write report    Completed      │  │
│  │ □ Prep meeting    Due: 07-06 09:00│ │
│  └──────────────────────────────────┘  │
│                                        │
│  [+ New todo]                          │
└────────────────────────────────────────┘

Todo

Title + deadline + priority + status
Status flow: pending → in progress → completed
Supports repetition (daily/weekly/monthly)

Schedule

Title + start/end time + location + reminder
Calendar view
Supports repeat rules

Cron

APScheduler cron expression
Bound to an agent + prompt
Automatically calls generate() when triggered

Quick Entry

Clipboard quick entry: Ctrl+Shift+L → paste text → the LLM extracts structured data
Create via conversation: just tell the agent, "Remind me of XXX at 9 AM every day"

12. Settings Center (SettingsCenter)

File: electron/renderer/src/components/SettingsCenter.vue

One-stop settings:

Tab	Content
Models	`BASE_URL` / `API_KEY` / `DEFAULT_MODEL` / `MANAGER_MODEL` / `EMBEDDING_MODEL` / `RERANKER_MODEL`
Theme	Theme color / dark mode / font size
Account	User profile (`USER.md`) / nickname / avatar
Privacy	`security_level` / `FAMILIARS_APPROVAL_DISABLED` / sensitive-information detection toggle
Background	Auto-start on boot / daemon / tray behavior
Listeners	WeChat / QQ / Feishu listener configuration
About	Version / update check / log viewer

13. Creative Workshop (CreativeWorkshop)

File: electron/renderer/src/components/CreativeWorkshop.vue

Recipe / Flow management:

┌────────────────────────────────────────┐
│  [Overview]  [chain_1]  [chain_2]  [Knowledge] │
├────────────────────────────────────────┤
│  Recipe list                            │
│  ┌──────────────────────────────────┐  │
│  │ medical_triage    [Compile] [Dry] [e2e] │
│  │ reverse_text      [Compile] [Dry] [e2e] │
│  │ generate_image    [Compile] [Dry] [e2e] │
│  └──────────────────────────────────┘  │
│                                        │
│  [+ New Recipe]                        │
└────────────────────────────────────────┘

Tab Structure

Overview: manifest summary + status
chain_group: a graph editor (VueFlow) for each chain
Knowledge: knowledge/ directory management (AGENTS.md / SKILL.md / external KB)
Tools/Skills: tools.json + custom tools
Utils: utility functions (utils/ directory)
Custom UI: .vue renderer source code

Editor

Graph Editor: VueFlow canvas (nodes + edges + sub-module containers)
Node Editor: right-side properties panel (NodePropertiesPanel)
Palette: left-side node panel (drag to add)
Scope Breadcrumb: top scope navigation (for_each nesting)

Verify Buttons

Each Recipe row has:

Compile: POST /api/recipe_dev/compile (structural validation)
Dry: POST /api/recipe_dev/dryrun (simulated execution)
e2e: POST /api/recipe_dev/e2e (end-to-end test)

14. Skill Forge (SkillForge)

File: electron/renderer/src/components/SkillForgeModal.vue

Describe a need → auto-generate SKILL.md:

Enter a skill description (natural language)
The LLM generates a SKILL.md blueprint (tool sequence + inputs/outputs)
It enters the approval queue (SkillApprovalsView)
It takes effect after a human confirms

Skill Change Approvals

File: electron/renderer/src/components/SkillApprovalsView.vue

Shows pending skill proposals
Compares the diff (old version vs new version)
Allow / Reject / Allow after modification

15. Broker Workshop (BrokerWorkshop)

File: electron/renderer/src/components/broker_workshop/

Installed broker management + marketplace browsing:

┌────────────────────────────────────────┐
│  [Installed]  [Marketplace]            │
├────────────────────────────────────────┤
│  Installed brokers                     │
│  ┌──────────────────────────────────┐  │
│  │ Ventaris    [Open] [Uninstall]   │  │
│  │ starter     [Open] [Uninstall]   │  │
│  └──────────────────────────────────┘  │
│                                        │
│  [+ Install from URL]  [+ Install from file] │
└────────────────────────────────────────┘

Marketplace

Marketplace index: GET /api/broker_workshop/marketplace/index (proxies the remote index.json)
Install: POST /api/broker_workshop/instances/install_from_url (download + sha256 + Ed25519 signature verification)
Author signing: ~/.familiars/authors/<name>.key (Ed25519 seed)

16. System Tray & Background

After the window is closed, Electron hides to the system tray:

[System tray]
  └─ Familiars icon
      ├─ Restore window
      ├─ Run in background (✓)
      ├─ ──────────
      └─ Exit background (fully quit)

Item	Function
Restore window	Show the main window
Run in background	Auto-start on boot toggle (`autorun.py`)
Exit background	Fully quit Electron + terminate the bridge subprocess

First-Hide Hint

The first time you close the window, a system notification appears:

"Familiars has been hidden to the system tray. Click the tray icon in the bottom-right corner to restore the window. To fully quit, use 'Exit background' in the tray menu."

Marker file: app.getPath('userData')/.tray-hint-shown (only prompts once).

17. Recommended First Actions

Experience an approval card: tell an agent, "Help me write a file to the desktop," and watch how privacy-desensitized approval intercepts it
Create a Todo and set it to repeat daily: experience the full Todo/Schedule/Cron flow
Open the Creative Workshop: look at the built-in Recipes (medical_triage / reverse_text), and click "Compile", "Dry", "e2e" to feel the validation flow
Find an installed marketplace Broker (such as Ventaris): post your first guild task and experience collaborative play
Try a global shortcut: select text → Ctrl+Shift+L → quickly create a todo

Next: FAQ → or User Manual

Interface Tour ​

1. Main Window Layout Overview ​

Three-Column Structure ​

2. Title Bar (TitleBar) ​

3. Agent List (AgentRail) ​

Interactions ​

Agent Row Visuals ​

Manager Special Handling ​

4. Conversation List (DialogList) ​

Interactions ​

Pinning ​

Filtering ​

5. Desktop Shell (Desktop.vue) ​

Built-in Apps (12) ​

Broker Apps ​

Window Behavior ​

Switching Back to the Legacy Landing ​

6. Chat Stage (ChatStage) ​

Top Bar ​

Message Area ​

Digital Human Panel ​

Split-Screen Mode ​

Export ​

7. Input Bar (InputBar) ​

Input Modes ​

Flow-Bound Input ​

Keyboard Shortcuts ​

8. Dialogue Tree View (TreeMini / TreeFull) ​

TreeMini (Mini View) ​

TreeFull (Fullscreen View) ​

Node Types ​

9. Status Overlay (StatusOverlay) ​

Status Levels ​

Interactions ​

10. Global Keyboard Shortcuts ​

Electron Global (triggerable in the background) ​

In-App Shortcuts ​

Quick-Create Flow ​

11. Todo / Schedule / Cron (TodoScheduleModal) ​

Todo ​

Schedule ​

Cron ​

Quick Entry ​

12. Settings Center (SettingsCenter) ​

13. Creative Workshop (CreativeWorkshop) ​

Tab Structure ​

Editor ​

Verify Buttons ​

14. Skill Forge (SkillForge) ​

Skill Change Approvals ​

15. Broker Workshop (BrokerWorkshop) ​

Marketplace ​

16. System Tray & Background ​

Tray Menu ​

First-Hide Hint ​

17. Recommended First Actions ​

Interface Tour

1. Main Window Layout Overview

Three-Column Structure

2. Title Bar (TitleBar)

3. Agent List (AgentRail)

Interactions

Agent Row Visuals

Manager Special Handling

4. Conversation List (DialogList)

Interactions

Pinning

Filtering

5. Desktop Shell (Desktop.vue)

Built-in Apps (12)

Broker Apps

Window Behavior

Switching Back to the Legacy Landing

6. Chat Stage (ChatStage)

Top Bar

Message Area

Digital Human Panel

Split-Screen Mode

Export

7. Input Bar (InputBar)

Input Modes

Flow-Bound Input

Keyboard Shortcuts

8. Dialogue Tree View (TreeMini / TreeFull)

TreeMini (Mini View)

TreeFull (Fullscreen View)

Node Types

9. Status Overlay (StatusOverlay)

Status Levels

Interactions

10. Global Keyboard Shortcuts

Electron Global (triggerable in the background)

In-App Shortcuts

Quick-Create Flow

11. Todo / Schedule / Cron (TodoScheduleModal)

Todo

Schedule

Cron

Quick Entry

12. Settings Center (SettingsCenter)

13. Creative Workshop (CreativeWorkshop)

Tab Structure

Editor

Verify Buttons

14. Skill Forge (SkillForge)

Skill Change Approvals

15. Broker Workshop (BrokerWorkshop)

Marketplace

16. System Tray & Background

Tray Menu

First-Hide Hint

17. Recommended First Actions