FEDERaiDE User Manual

1. Welcome & Overview

1.1. What is FEDERaiDE?

FEDERaiDE is a cross-platform, terminal-based multi-agent orchestration harness and universal automation system. It transforms your terminal into an interactive, multi-panel workbench where custom teams of AI agents can collaborate with one another, manage your files, edit and execute code, run deep research, listen to your voice commands, speak back to you, and execute desktop automation routines.

1.2. Core Concepts

• Autonomous Agents: Instead of talking to a single assistant, you can assemble a team of agents (e.g., a junior programmer, a security reviewer, and a project manager). Each agent has its own backstory, API model, voice, color code, and tool permissions.
• Peer-to-Peer Networks: FEDERaiDE supports true peer-to-peer agent networks. Agents can mention and delegate work to each other dynamically using simple text commands like @AgentName or @@AgentName without requiring fixed hardcoded pipelines.
• Local Workspace Isolation: Everything operates inside your designated local workspace directory. Agents inspect your code, run local tests, and build reports directly on your computer or Android smartphone.

1.3. Understanding Launcher Options

FEDERaiDE provides two distinct executable launch commands depending on how you wish to work:

• federaide: Launches the Full TUI Workspace containing the complete multi-panel interface (Multi-Agent Chat ↔ Tabbed Code Editor ↔ Live Program Execution Dashboard ↔ Workspace Explorer ↔ Code Structure Outline).
• federate: Launches the streamlined Chat-Only View, focused entirely on multi-agent conversation, voice interactions, and background skill execution without the multi-panel code editor layout.

2. Installation & Getting Started

2.1. System Requirements & Platform Support

FEDERaiDE runs natively across all major operating systems without requiring Docker or containerization:

• macOS: Intel (x86_64) and Apple Silicon (ARM64 / M-series).
• Linux: x86_64, ARM64 (Raspberry Pi 3/4/5), and standard server distributions.
• Windows: Native Windows 10/11 via PowerShell (no WSL required).
• Android: Native smartphone operation via the Termux terminal environment.

2.2. Installation Commands

Mac / Android (Termux)

Open your terminal and run the single-line installer script:

curl -LsSf https://raw.githubusercontent.com/ROCK-LAB-PRIVATE-LIMITED/federaide/main/install.sh | bash

Linux

Open your terminal and run the Linux installer script (install wget using your package manager if not already present, curl also works use the suitable invocation.):

wget -O- https://raw.githubusercontent.com/ROCK-LAB-PRIVATE-LIMITED/federaide/main/nuxinstall.sh | sh

Windows (PowerShell)

Open Windows PowerShell (no administrator privileges required) and run:

irm https://raw.githubusercontent.com/ROCK-LAB-PRIVATE-LIMITED/federaide/main/install.ps1 | iex

Alternative Package Managers (`uv` or `pip`)

# Via uv (Recommended)
uv tool install "federaide[all]"

# Via pip
pip install "federaide[all]"

2.3. First Launch & The Onboarding Wizard

To start the application, type federaide (or federate for chat-only mode) in your terminal:

federaide

On your very first launch, FEDERaiDE automatically opens the Onboarding Popup Wizard. This modal guides you through configuring your initial active AI agent:

1. Base URL Preset: Select a provider preset from the dropdown menu (Google Gemini, OpenRouter, OpenAI, Anthropic, ChatGPT Subscription (OAuth), or Custom). Choosing a preset populates the base URL automatically.
2. API Key / OAuth Authentication: Input your API key (e.g., from OpenRouter, Google Gemini, OpenAI, or Anthropic). If you choose ChatGPT Subscription (OAuth), click Authenticate with OAuth to connect your ChatGPT Plus, Pro, or Team subscription directly without needing a pay-per-token API key.
3. Model Identifier: Specify your desired LLM model (e.g., gemini-3.1-flash-lite, openai/gpt-4o, anthropic/claude-3.5-sonnet, or gpt-5.6-luna for ChatGPT OAuth).
4. Base URL: Enter or adjust the API endpoint URL (for local models, enter http://localhost:11434/v1 for Ollama or http://localhost:1234/v1 for LM Studio).
5. Agent Name & Backstory: Name your agent (default: Rita) and define a backstory describing its role (default: "You are Rita, a general purpose senior developer.").

Click Get Started. FEDERaiDE securely encrypts and stores your credentials inside your native OS Keychain (macOS Keychain, Windows Credential Manager, or Linux/Termux Encrypted Keyring).

2.4. Phase 1: Operating in Single-Agent Mode

Immediately after onboarding, FEDERaiDE boots into a single-agent environment with your initial assistant (e.g., Rita). In this state, you can use the harness just like any standard AI chat program—ask questions, request code edits, run searches, or manage files.

2.5. Phase 2: Unlocking Multi-Agent Swarms & Backstory Tuning

The full capability of FEDERaiDE is unlocked when you create specialized teams of agents using the Agent Editor (F4):

• Tuning Backstories: Describe domain expertise and delegation rules in the backstory (e.g., "You are a database specialist. Whenever you write SQL, tag @Elena to audit it.").
• Reasoning Effort & Temperature: Adjust temperature and reasoning effort (Low, Medium, or High) for thinking models (o1, o3, Gemini 2.5) in the Agent Editor (F4).
• Backup Provider (Auto-Failover): Configure a secondary Backup Model, Base URL, and API Key for an agent in F4. If the primary provider hits rate limits or server errors, FEDERaiDE automatically switches to the backup model (indicated by a [B] badge in the status bar).

3. Interface Navigation & Safety Controls

3.1. Understanding the Display

The main FEDERaiDE workspace interface consists of five primary panels:

• Multi-Agent Chat Panel: The main conversation hub where user prompts, agent replies, tool outputs, and status updates appear.
• Workspace File Explorer: Left-hand sidebar displaying files and folders in your active working directory.
• Tabbed Code Editor: Central code editor supporting multiple open document tabs with syntax highlighting.
• Structure Outline Tree: Right-hand sidebar displaying a structural breakdown (classes, functions, methods) of the active code file.
• Executions Dashboard: Live terminal dashboard showing printouts and output from running scripts.

3.2. Essential Keyboard Shortcuts & Hotkeys

3.3. Safety Permission Modes

To protect your files and workspace, FEDERaiDE operates under three safety permission levels. You can press Ctrl + T at any time to cycle permissions:

• SAFE (Plan Mode - Default): Agents can only run safe, read-only tools (web search, reading files, listing directory trees, deep research). Destructive file edits or code execution require explicit confirmation popups.
• SEMI-AUTO (Semi-Armed Mode): Agents can edit files and execute terminal commands, but FEDERaiDE presents an authorization popup asking you to approve or reject every single action before it runs.
• FULL-AUTO (Full-Armed Mode): Agents have unrestricted permission to create files, edit code, run terminal scripts, and execute active skills automatically without asking for confirmation.

3.4. Per-Agent Tool Configurations & Permissions Override

FEDERaiDE allows you to customize tool access on a per-agent basis inside the Agent Editor (F4):

1. Enabling Specific Tools in SAFE Mode

Click Manage Agent Abilities... to open the Agent Abilities modal. Here you can check Enable (Safe) next to individual tools (e.g., read_file, run_terminal_command, edit_file). Enabling a tool allows that specific agent to request its execution in SAFE mode, subject to user confirmation popups.

2. Selective Tool Disabling

Check Force Disable next to any tool (e.g., run_terminal_command or visual_computer_operation) to completely revoke that tool from the agent's capabilities.

3. Disable All Tools Override

Check the Disable All Tools checkbox in the Agent Editor to instantly revoke all executable, file-editing, terminal, and computer-automation tools from the agent. An agent with all tools disabled functions as a pure text/reasoning persona while retaining access to passive playbooks, memory retrieval, and user clarification.

3.5. Changing Workspace Directories

Press F8 or type /dir to open the interactive directory modal. Navigate using UP/DOWN arrow keys, press Enter to expand a folder, or press Ctrl + B to select the highlighted folder as your new root workspace.

4. Chatting & Everyday Workspace Controls

4.1. Sending Messages & Multiline Prompt Input

Type your message into the prompt bar at the bottom of the screen and press Enter to submit.

• Multiline Prompts: Press Shift + Enter, Alt + Enter, or Ctrl + J to insert line breaks without submitting your message.
• Dynamic Input Resizing: The prompt input bar automatically grows vertically (up to 5 lines) to accommodate multiline text and long prompts before scrolling internally.

4.2. Attaching Files, Images, and Folders (`&` Shortcut)

You can attach local workspace files, images, PDFs, or entire directory trees directly into your prompt by typing & followed by the relative or absolute path:

• &src/main.py — Reads main.py, prepends line numbers to every line, and injects its contents directly into the prompt context.
• &diagram.png or &report.pdf — Attaches local images or PDF documents. If the active agent is vision-capable, FEDERaiDE automatically converts PDF pages and image files into visual payloads for the agent to inspect.
• &src/ — Recursively scans the entire src/ folder tree, reading all code files, documents, images, and PDFs into context.

Folder Attachments & Ignored Files

Attaching a folder (e.g., &src/) recursively reads all code, documents, images, and PDFs in that directory. FEDERaiDE automatically parses your project's .gitignore and .listignore files, automatically excluding build artifacts, virtual environments (venv/, .venv/), dependency folders (node_modules/), and binary executables to prevent context token bloating.

4.3. Interactive Autocompletion Suggestions Overlay

Typing trigger characters in the chat input displays an interactive completion table directly below the input bar:

• / — Shows slash commands with brief descriptions.
• & — Lists workspace files and subfolders with size indicators.
• @ — Lists available agents, @team, and @room with role summaries.
• Navigation: Use UP / DOWN arrow keys to cycle through choices, and press RIGHT ARROW to accept the highlighted completion.

LaTeX & Mathematical Unicode Rendering

Mathematical expressions in agent responses (both inline $...$ and block $$...$$) are automatically parsed and converted into clean, human-readable Unicode text in the terminal chat view.

4.4. Direct Terminal Passthrough & Persistent Shell Mode (`!` Shortcut)

You can execute terminal commands on your host computer directly from the chat prompt bar without leaving FEDERaiDE:

• One-off Command Execution: Type ! followed by any shell command (e.g. !git status, !pytest, or !npm test). FEDERaiDE executes the command in your active workspace directory and prints the output directly in the chat window.
• Persistent Shell Mode Toggle: Type ! by itself and press Enter to toggle your prompt bar into persistent Shell Mode. The prompt label turns red (e.g. shell@project %). All subsequent inputs will run as direct terminal commands until you type ! again to exit back to AI chat.
• Stateful Directory Navigation (`cd`): Running cd <path> inside Shell Mode changes the process working directory, updates the active workspace root, and automatically reloads the File Explorer tree live.

4.5. Emergency Abort (Ctrl + A)

If an agent starts a long-running calculation, loop, deep research run, or terminal command that you wish to stop immediately, press Ctrl + A. This forcefully terminates all background agent threads, loops, sub-agent workers, and terminal subprocesses across all active agents, returning control to your prompt bar.

5. Multi-Agent Orchestration

5.1. Invocation Syntax & Routing (`@` vs `@@`)

FEDERaiDE features a peer-to-peer communication network that allows you (and agents themselves) to route messages and delegate tasks dynamically using simple mention shortcuts:

• Sequential Invocation (@AgentName): Invokes a specific agent sequentially (e.g. @Rita please review this pull request). The tagged agent processes the prompt and executes its tools. If multiple sequential agents are tagged (e.g. @Leo @Bob), they execute one after another in order.
• Parallel Invocation (@@AgentName): Invokes multiple agents in parallel simultaneously (e.g. @@Leo build the backend API, @@Bob construct the frontend UI). Both agents are dispatched at the exact same time on separate background workers to complete their work concurrently.
• Hybrid Parallel & Sequential Chains: You can combine parallel (@@) and sequential (@) mentions in a single prompt (e.g. @@Leo implement feature X, @@Bob write unit tests, and @Rita summarize when done). All parallel workers launch immediately; sequential agents wait in a queue and are only dispatched once all parallel workers have finished.
• Team Broadcast (@team): Broadcasts your message to every registered agent in your system (e.g. @team good morning, let's review today's roadmap).
• Room Broadcast (@room): Broadcasts your message to all agents currently participating in the active chat session.

5.2. Autonomous Agent-to-Agent Delegation

Agents do not rely on fixed, hardcoded pipelines. Instead, agents autonomously delegate tasks to each other during conversation:

• Proactive Delegation: When an agent encounters a task outside its core backstory (e.g., a frontend developer agent needing SQL database optimization), it can mention the appropriate specialist (e.g. @Marcus please optimize this SQL query) directly in its response.
• Peer Collaboration: Tagged agents receive the full conversation history and context, allowing them to pick up where their colleague left off, critique code, or execute specialized tools seamlessly.

5.3. Controlling Conversation Queues (`@askuser` & `@resume`)

To prevent runaway debates, infinite loops, or unneeded token consumption during complex multi-agent discussions, FEDERaiDE provides queue control keywords:

• @askuser — If an agent includes @askuser in its response (e.g. "I have prepared two database migration options. @askuser which approach do you prefer?"), FEDERaiDE immediately pauses the agent execution queue and waits for your response.
• @resume — Type @resume in the chat input bar to unpause an agent queue that was halted by @askuser and allow the remaining agents to continue their turns.

5.4. Multi-Model Ecosystems & Cost Optimization

Because FEDERaiDE abstracts model providers at the agent level, you can construct teams combining different LLM models and providers in a single session:

• Token Cost Optimization: Assign inexpensive, fast models to junior coder agents handling repetitive file edits and test runs, while assigning high-reasoning frontier models to architect and reviewer agents who only step in for final code reviews or complex problem-solving.

6. Built-in Code Editor & Program Runner (IDE View)

6.1. Workspace Architecture & View Navigation (F6)

Launching FEDERaiDE via the federaide command boots the full multi-panel Terminal IDE. Press F6 at any time to cycle sequentially between the three primary interface views:

1. Multi-Agent Chat View (ai_chat_view): The central multi-agent discussion workspace, voice dictation interface, and tool execution feed.
2. Code Editor Workspace (code_view): The three-panel coding environment comprising the File Explorer, Tabbed Editor, and Real-Time Structure Outline.
3. Executions Dashboard (exec_manager_view): The tabbed terminal dashboard displaying live outputs, PTY terminal shells, and script execution logs. (Note: F6 automatically bypasses this view if no program executions are active or if only the idle panel is open).

6.2. Workspace File Explorer & Folder Navigation

The left-hand Explorer Pane (#explorer_pane) renders an interactive tree view of your active working directory.

• Browsing & Opening Files: Use UP / DOWN arrow keys to highlight items. Press Enter to expand or collapse folders, or to open a selected file in a new document tab inside the central code editor.
• Navigating Up One Directory Level (Backspace): Press Backspace while focused on the Explorer tree to instantly navigate up one directory level in the filesystem hierarchy.
• Set Highlighted Folder as Visual Root (Ctrl + B): Highlight any subfolder in the tree and press Ctrl + B to set that folder as the new visual root of your File Explorer tree.
• Creating New Files (Ctrl + N): Press Ctrl + N to open the filename modal and create a new empty file in the active workspace directory.
• Creating New Folders (F7): Press F7 to open the folder modal and create a new directory or nested subfolder tree in your workspace root.
• Changing Workspace Root Directory (F8 / /dir): Press F8 or type /dir to open the interactive directory selector modal (DirectoryModal) to navigate your drive and switch the application's root working directory.

6.3. Tabbed Code Editor & Document Management

The central Editor Pane (#editor_pane) provides multi-document tabbed editing with automatic language detection, line numbers, soft wrapping controls, and syntax highlighting across 18+ file extensions.

Tab Navigation & Closing Shortcuts

• Cycle Forward to Next Tab (Ctrl + L): Press Ctrl + L to switch focus sequentially to the next open editor tab.
• Cycle Backward to Previous Tab (Ctrl + O): Press Ctrl + O to switch focus to the previous open editor tab.
• Close Active Document Tab (Ctrl + W): Press Ctrl + W to close the currently focused editor tab. When all document tabs are closed, the editor and structure outline panes automatically hide, returning focus to the File Explorer tree.

Saving & File Clipboard Controls

• Save Active File (Ctrl + S): Press Ctrl + S to write changes in the current editor tab directly to disk.
• Save As (Ctrl + Shift + S): Press Ctrl + Shift + S to open the "Save As" modal, allowing you to save the document under a new filename or path.
• Copy Selected Text (Ctrl + C): Highlight text inside any open editor tab and press Ctrl + C to copy the selection directly to your native system clipboard (integrated via pyperclip).

6.4. Real-Time Code Structure Outline & Jump Navigation

The right-hand Structure Pane (#outline_pane) parses open code documents in real-time using high-speed Tree-Sitter language sidecars across 10+ supported programming languages (Python, Go, Rust, C, C++, TypeScript, JavaScript, PHP, Bash, CSS).

• Symbol Classification & Icons: Displays structural declarations with visual category indicators:
  • Cl — Classes, Structs, Interfaces, Modules, Types, and Namespaces.
  • ƒ — Functions, Methods, Closures, and Routines.
• One-Click & Keyboard Line Jumping: Select any symbol node in the Structure Tree and press Enter (or click with your mouse). FEDERaiDE instantly moves the code editor cursor directly to that symbol's starting line number, scrolls the line into view, and focuses the editor.

6.5. Find & Replace Modal (Ctrl + F)

Press Ctrl + F while editing any document tab to open the Find & Replace modal screen:

• Find Input: Type the search term or regex pattern to locate.
• Replace Input: Type the desired replacement string.
• Match Case Checkbox: Uncheck the Match Case checkbox for case-insensitive searching (defaults to case-insensitive).
• Search Navigation (Next / Prev): Click Next or Prev to navigate forward or backward through search matches. The editor automatically selects and scrolls each match into view.
• Replacing Matches (Replace / All): Click Replace to substitute the currently selected match, or click All to replace every occurrence across the entire file simultaneously with an instant status toast notification.

6.6. Program Execution & Live Executions Dashboard (Ctrl + R & Ctrl + E)

Running Code (Ctrl + R)

Press Ctrl + R in any open code editor tab. FEDERaiDE automatically performs a series of synchronized execution steps:

1. Auto-saves the active document tab to disk.
2. Determines the programming language based on file extension and looks up its execution flags and binary path.
3. Creates a new tab inside the Executions Dashboard labeled <filename> #<run_id>.
4. Launches the code inside an interactive pseudo-terminal (PTY) runner and automatically switches the active view to the Executions Dashboard.

Interactive PTY Terminal Emulation & Keyboard Passthrough

Every running script executes inside a dedicated Terminal Emulator with native PTY backend integration (pty on Linux/macOS or pywinpty on Windows):

• ANSI Control Code Processing: Renders carriage returns (\r), backspaces (\b), tab stops, and clear-line sequences natively.
• Live Interactive Input Passthrough: When an execution tab is focused, keystrokes are passed directly to the running process in real-time. You can answer interactive prompts (e.g. Python input() statements, CLI confirmations, or REPL shells) directly in the execution tab!

Execution Tab Navigation & Process Termination

• Cycling Execution Tabs (Ctrl + L / Ctrl + O): Press Ctrl + L or Ctrl + O while viewing the Executions Dashboard to switch focus between multiple concurrently running scripts.
• Terminate Active Process (Ctrl + E): Press Ctrl + E to send a termination signal (SIGTERM / process kill) to the script running in the active execution tab.
• Close Execution Tab (Ctrl + W): Press Ctrl + W to close the active execution tab (terminating the process if still active). When the last execution tab is closed, the dashboard automatically resets to its Idle state and returns focus to the Code Editor workspace.

6.7. Custom Language Executables & Flags Configuration (F9)

Press F9 to open the Execution Settings modal (SettingsModal) to configure custom compiler or interpreter paths and execution flags for 13+ supported languages:

• Supported Presets: Python, Go, C, C++, Rust, Node.js, Julia, Fortran, Nim, Zig, Bash, Batch, and PowerShell.
• Executable Binary Path: Specify custom binary paths (e.g., python3.13, g++-13, cargo, or custom environment binaries).
• Flag String Variables: Customize execution parameter strings using dynamic template variables:
  • {file} — Replaced with the full absolute path to the active code file.
  • {file_no_ext} — Replaced with the full path excluding file extension (essential for compiled binary targets like C, C++, Fortran, and Rust).

6.8. Virtual Environment (Venv) Manager (F10)

Press F10 to open the Venv Manager dialog (VenvManagerModal) to manage isolated Python execution environments:

• Workspace Auto-Detection: Automatically scans your active project directory for local .venv or venv/ folders and lists them for instant one-click activation.
• Global Venvs: Lists all global virtual environments maintained inside ~/.federate/.
• Direct Path Activation: Enter any custom absolute path to an existing virtual environment on your system to activate it immediately.
• Custom Venv Creation: Create brand new virtual environments using uv venv by specifying a name, an optional target Python version (e.g. 3.11 or 3.13), and a custom installation path.

7. Teaching Agents New Skills

7.1. Passive Skills vs. Active Skills

• Passive Skills (Playbooks): Markdown procedural documents containing step-by-step guidelines, rules, or checklists for agents to follow when performing specific tasks.
• Active Skills (Executable Tools): Standalone programs (Python scripts, shell scripts, C/Rust binaries, or compiled CLI utilities) stored in your agent's skills library that agents execute directly as custom tools on demand.

7.2. Creating Passive Playbooks

Agents automatically save playbooks when they complete complex workflows using the distill_journey tool. You can also ask an agent to save a playbook manually, read existing playbooks using read_skill, or delete old playbooks using delete_passive_skill.

7.3. How Active Skills Are Authored & Installed

Active skills do not have to be written exclusively by AI agents. FEDERaiDE strongly encourages users to write custom programs themselves or download and audit useful CLI scripts and utilities from GitHub or community repositories!

Active skills can originate from three sources:

• User-Authored Programs: You write custom Python scripts, shell tools, or C/Rust/Go binaries in your workspace.
• Audited Open-Source Utilities: You (or your agent) fetch and audit open-source CLI scripts, libraries, or tools from GitHub or external repositories.
• Agent-Authored Code: Your AI agent writes new script logic autonomously to automate repeated or complex workflows.

The Unified Agent Installation Pipeline: Regardless of who wrote or downloaded the code, you do not need to manually format JSON schemas or configure internal skill folders. Simply point your agent to the script files in your workspace and pass any accompanying instructions or documentation. The agent then runs prepare_active_skill (to set up an isolated virtual environment, build dependencies, and execute a live validation test) followed by finalize_active_skill (to automatically generate the tool schema, create the usage manual playbook, initialize Git version control, and register the tool into its permanent library).

7.4. Staging & Registering Active Skills

FEDERaiDE manages active skill installation in a 2-stage automated pipeline:

1. Stage & Test (prepare_active_skill): Takes the script files, entry point, sample test inputs, PyPI dependencies, custom build commands (pre_install_commands), and optional argument order (arg_order). It creates a dedicated virtual environment in an isolated staging folder, builds and installs all dependencies, and runs a live validation test.
2. Finalize & Register (finalize_active_skill): Once the validation test succeeds, the agent provides a tool description and usage guide. FEDERaiDE automatically generates the schema.json and metadata.json, moves the tool to the live skills library, creates an automatic usage manual playbook, and initializes Git version control.

Positional vs. Keyword Argument Modes

• Positional Mode: Specify an arg_order list (e.g. ['param1', 'param2']) when staging the skill if your script reads positional CLI arguments (like sys.argv[1]).
• Keyword Mode (Default): Omit arg_order if your script accepts command-line flags (e.g. --param1 value).

7.5. Multimodal Active Skills: Returning Images Directly to Agents

One of FEDERaiDE's most powerful capabilities is that Active Skills can be fully multimodal. An active skill does not just return plain text—it can generate and return rich visual data (plots, charts, diagrams, processed images, CAD renders, or desktop screenshots) directly back into the agent's vision context!

7.6. Skill Version Control & Maintenance

Every finalized skill folder is initialized as an independent Git repository. Use the fix_active_skill tool to maintain your tools:

• File Inspection & Reading: Action list enumerates files in the skill folder; action read prints code with line numbers.
• Line-Range Editing: Action edit replaces lines from start_line to end_line and returns a 20-line surrounding snippet for visual verification.
• Dependency Updates: Action install installs new PyPI packages directly into the skill's virtual environment.
• Automatic Git Commits: Every edit or dependency update is automatically committed with timestamped git logs.
• Management & Deletion: Use manage_active_skill to rename or delete active tools, and delete_passive_skill to delete playbook manuals.

8. Deep Research & Automated PDF Reports

8.1. How Deep Research Works

When assigned a complex research topic, FEDERaiDE spawns a team of parallel sub-agents in the background. Each sub-agent explores a different angle of the research topic simultaneously, gathering web sources, evaluating images, and synthesizing findings.

8.2. Triggering Deep Research

Ask your agent to perform deep research on any topic (e.g., "Perform a deep research report on quantum dot cellular automata") or call the perform_research tool.

8.3. Live Progress Dashboard

During deep research, a split-pane dashboard appears in the chat view:

• Left Pane: Shows live progress bars for each parallel sub-agent research module.
• Right Pane: Streams real-time research logs, search queries, and web page fetches as they occur.

8.4. Enabling the Deep Research Image Companion (Illustrator)

The Deep Research Image Companion gathers, verifies, and embeds visual diagrams into final research reports. This feature is disabled by default.

How to Enable

1. Press F3 or type /settings to open the Global Harness Settings modal.
2. Scroll down to Deep Research Image Companion.
3. Check the Enable Deep Research Image Companion checkbox.

8.5. Global Settings & PDF Styling Customization (F3 / `/settings`)

Press F3 or type /settings to customize global harness parameters:

• Tool Result Availability: Choose between Private (default: tool outputs in multi-agent discussions are hidden behind [Tool Output Hidden - Result ID: X] stubs to save context tokens; agents fetch them via get_toolresult(ids=[X])) or Public (broadcasts full outputs immediately).
• Search Pacing Delay: Set global search pacing delay (default: 65 seconds with random jitter) to prevent DuckDuckGo rate-limiting.
• Auto-Update on Launch: Automatically query PyPI for new releases when starting FEDERaiDE.
• Research Limits: Configure maximum parallel sub-agents (1–10), target context token limit (default: 28,000 tokens), and minimum report token length.
• PDF Customization: Adjust rendering DPI (or use /dpi <number>), change footer text, and select custom body, heading, or code font families and sizes.

9. Voice & Speech Features

9.1. Text-to-Speech (TTS) Output

Type /tts to toggle voice output on or off. When enabled, agents will speak their responses out loud using natural-sounding offline neural voices. Type /readback to re-read the last agent response out loud.

9.2. Setting Up Individual Agent Voices

Every agent can be assigned its own distinct voice in the Agent Editor (F4). This allows you to hear which agent is responding without looking at your screen. Over 50 male and female voices across American, British, Japanese, Mandarin, Spanish, French, Italian, and Hindi accents are supported.

9.3. Hands-Free Voice Dictation (Speech-to-Text / STT)

Type /stt to activate offline background hotword listening. Once active, FEDERaiDE listens to your microphone continuously without sending any audio to external cloud servers.

9.4. Dictation Triggers & Control Hotwords

While Speech-to-Text is active, you can control dictation entirely with your voice:

• Start Dictation: Say any start trigger (e.g. AGENT, ASSISTANT, or COMPUTER) to begin dictating text into your prompt bar.
• Pause Dictation: Say STOP LISTENING or END DICTATION to stop recording and leave your transcribed text in the prompt bar so you can review or edit it.
• Send Prompt: Say EXECUTE, FINISH, or SEND IT to immediately submit your transcribed prompt to the AI.
• Delete Last Sentence: Say DELETE LAST or SCRAP THAT to erase the last transcribed statement from the prompt bar.
• Agent Invocation Hotword: Say ATTENTION <AgentName> (e.g. "ATTENTION RITA" or "ATTENTION TEAM") to target and route your spoken prompt to a specific agent persona.

9.5. Testing Your Microphone & Triggers (`/mictest`)

Type /mictest to open an isolated microphone and hotword testing sandbox. You can speak out loud, monitor live transcription logs, verify trigger word detection, and test noise energy thresholds before using dictation in active conversations.

10. Telegram Mobile Integration

10.1. Connecting FEDERaiDE to Telegram

You can connect your FEDERaiDE agent team directly to your smartphone via Telegram:

1. Type /telegram to open the Telegram Bot Configuration modal.
2. Check Enable Telegram Bot.
3. Configure file permissions: check Allow File Reception (Telegram ➔ Workspace) and/or Allow Sending Files (Workspace ➔ Telegram).
4. Enter your Bot Token obtained from @BotFather on Telegram.
5. Enter your Telegram username or ID in Allowed Users.
6. Click Save & Connect.

10.2. Messaging Your AI Team & Sending Files

Once connected, you can message your bot on Telegram while away from your computer. You can use standard prompts, mentions (e.g., @Rita), and team broadcasts.

• Sending Files to Computer: When Allow File Reception is checked, you can send documents, code files, or photos directly to your Telegram bot. FEDERaiDE automatically downloads them into your workspace (applying an extension whitelist) and formats them into context as text attachments or visual payloads.
• Requesting Files from Computer: When Allow Sending Files is checked, agents can use the send_file_to_telegram tool to deliver workspace files, code scripts, datasets, or images directly to your phone.

10.3. Mobile Voice Notes & Automatic PDF Deliveries

When Enable Telegram TTS is checked in /telegram, agents send audio voice notes back to your phone using their assigned voice persona. When a Deep Research run finishes on your computer, the finished PDF report is automatically uploaded directly to your Telegram chat.

11. Scheduled Task Routines

11.1. Setting Up Automated Tasks

Type /schedule to open the Scheduled Tasks manager. From this modal, you can instruct agents to run automated workflows at specific times of the day.

11.2. Repeat Cycles

When creating a scheduled task, choose from four repeat cycles:

• Daily: Executes every day at the designated 24-hour time (HH:MM).
• Weekly: Executes once a week on the specified start day.
• Monthly: Executes once a month on the specified calendar date.
• Annually: Executes once a year on the specified date.

11.3. Task Due Alert & Offline Catch-Up Logic

When a task becomes due, FEDERaiDE presents a 60-second countdown alert modal offering three choices: Run Now, Defer 15 Min, or Skip. If no action is taken before the countdown expires, the task executes automatically. Click Edit next to any saved task in the Scheduled Tasks modal to reload its parameters for modification.

If your computer or phone was off or asleep when a task was scheduled to run, FEDERaiDE detects the missed run and prompts you to execute or defer it upon the next application launch.

12. Memory & Context Management

12.1. How Agent Core Memory Works

Agents maintain persistent core memories stored in two categories:

• USER Memory (USER.json): Remembers details about you, your role, preferences, working habits, and background.
• MEMORY Store (MEMORY.json): Remembers technical facts about your projects, codebases, rules, and environment.

Agents automatically create, edit, or delete memory entries when learning new facts during conversation.

12.2. Searching Past Conversations (Episodic Memory)

Agents can search through historical chat sessions semantically using the search_episodic_memory tool. They can recall past decisions, architectural choices, and previous discussions even if exact keywords don't match, and retrieve full verbatim chat histories using retrieve_episodic_memory.

12.3. Context Compression Details (`/compress`)

Typing /compress condenses older conversation turns into a first-person technical Markdown summary ([SYSTEM HISTORICAL RECALL SUMMARY]), freeing token context while retaining exact file paths, code structures, and project decisions.

• Verbatim Message Retention: You can configure how many recent messages remain untouched at the end of the history via Verbatim Messages to Keep in Global Settings (F3 / `/settings`, default: 2).
• Multimodal Preservation: Generated or attached images in the compressed history are automatically saved as persistent file references, ensuring visual context survives compression.

12.4. Memory Consolidation (`/consolidate`) & Backstory Sync (`/backstory`)

• Manual Memory Consolidation (/consolidate): Instructs the active agent to review its MEMORY.json store, combine related memorylets, prune obsolete entries, resolve contradictions (retaining newer data), and split clumped memorylets into individual atomic facts.
• Backstory Synchronization (/backstory): Forces an immediate translation and update of all agent backstories across your team into 3rd-person format for multi-agent intercom routing.

13. Complete Slash Command Reference

14. Command-Line (CLI) Reference

14.1. Executable Launch Commands

FEDERaiDE provides two distinct executable launch entry points depending on your desired interface layout:

14.2. Command-Line Arguments & Flags

Both federaide and federate accept optional command-line flags and positional arguments:

15. Troubleshooting & Frequently Asked Questions

15.1. Common Issues & Solutions

Q: How do I use my ChatGPT Plus/Pro subscription instead of pay-per-token API keys?

Solution: In the Onboarding Wizard or Agent Editor (F4), set the Base URL Preset to ChatGPT Subscription (OAuth) and click Authenticate with OAuth. Complete the browser sign-in prompt to authorize your account. FEDERaiDE will securely store your OAuth tokens in your OS keyring and refresh them automatically.

Q: Why are tool results showing as "[Tool Output Hidden - Result ID: X]" in multi-agent chat?

Solution: FEDERaiDE defaults to Private tool result availability to conserve context tokens during multi-agent discussions. Agents can retrieve hidden outputs on demand using get_toolresult(ids=[X]). To broadcast full tool outputs immediately to all agents, open Global Settings (F3) and change Tool Result Availability to Public.

Q: My agent says "Tool is unauthorized" when trying to run a script.

Solution: FEDERaiDE is currently in SAFE permission mode. Press Ctrl + T to cycle safety modes to SEMI-AUTO or FULL-AUTO, or open the Agent Editor (F4) and check the tool permissions under Agent Abilities.

Q: How do I stop a runaway agent conversation or loop?

Solution: Press Ctrl + A at any time to execute an instant emergency stop. This halts all background agent threads, loops, and terminal scripts immediately.

Q: Microphone hotwords are not detecting my voice.

Solution: Type /mictest to open the microphone testing sandbox. Check your energy threshold setting in /speech (try lowering it to 0.002 if your room is quiet, or raising it if your background environment is noisy), and verify that your microphone index is correct.

Q: I am being asked for a password when starting on Linux or Termux.

Solution: Some encrypted keyrings require a master password. Enter your password when prompted by the unlock modal, or click Set New / Reset to establish a new password for storing your API keys securely. If you forget your password you can simply reset it from there. Your existing keys will be erased but everything else (your agents, their backstories and memories, will stay completely unharmed).

Q: How do I run FEDERaiDE in chat-only mode without the code editor panels?

Solution: Launch the application using the federate command instead of federaide.

15.2. Software Updates (`/update`)

Type /update or /version to check for new releases. FEDERaiDE queries PyPI and displays cumulative release notes for new versions. Click Update Now to launch the automated updater script, exit the app, update dependencies, and restart FEDERaiDE automatically. You can also select Skip Version or Remind Later.