Pilot Agents & Habits
Relevant source files
The following files were used as context for generating this wiki page:
A Pilot is a persistent, long-lived agent within Rebase that maintains its own identity, conversation history, and memory across multiple projects. Unlike standard sessions tied to a single repository, a Pilot resides on the application rail and can be assigned to work on various project folders simultaneously.
Pilots perform automated tasks through "Habits"—scheduled routines that run in separate, hidden sessions to provide periodic updates, reports, or maintenance without direct user intervention.
Pilot Architecture and Identity
Each Pilot is defined by a unique ID and a distinct visual identity consisting of a name, mascot, and color. The Pilot model tracks the projects it is authorized to access and its current conversation state.
Pilot Data Model
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (UUID). |
sessionId | string | The ID of the Pilot's primary conversation. |
name | string | User-defined name or generated default (e.g., "PilotCrab"). |
mascot | string | Visual identifier (e.g., "mushroom", "invader"). |
color | string | Theme color used in the UI and mascot rendering. |
projects | string[] | List of project folder paths the Pilot works on. |
legacyProject | string | Project path used during migration from legacy storage. |
Sources: src/features/pilots/model/pilot.ts:25-50, crates/rebase-core/src/pilot.rs:43-61
Data Flow and Migration
The system migrates legacy project-bound agents into the global Pilot roster. This process ensures that previous project agents keep their identities and conversations while becoming multi-project capable.
Pilot Context and Files
Pilots maintain a "Soul" and "Memory" stored as Markdown files in the application's data directory. These files define the agent's behavior and persistent knowledge.
Core Files
- SOUL.md: Contains standing instructions that rank below the user's current request. It defines the Pilot's core personality and rules.
- MEMORY.md: Stores dated facts, preferences, and project details. It has a budget of 200 lines or 24KB; older entries move to
memory/archive.md. - Topic Files: Longer notes on specific subjects stored in
memory/<topic>.md.
Sources: src/features/pilots/model/pilotFiles.ts:13-30, src/features/agent-app/model/agentApp.ts:468-475
Context Management
When a turn starts, the system plans the context to send to the LLM provider. If a session already possesses the current version of the Soul or Memory, the system omits these parts to save tokens.
Habits and Automation
Habits are scheduled tasks that a Pilot performs autonomously. Each habit run occurs in a separate, hidden session.
Habit Configuration
A Pilot can have a maximum of 10 habits. Each habit consists of a name, instructions, and a schedule.
| Schedule Kind | Requirement | Description |
|---|---|---|
hourly | minute | Runs every hour at the specified minute. |
daily | time | Runs every day at a specific HH:MM. |
weekdays | time | Runs Monday through Friday at HH:MM. |
weekly | dayOfWeek, time | Runs on a specific day of the week. |
Sources: src/features/pilots/model/pilotHabits.ts:21-34, src/features/pilots/ui/NewHabitPage.tsx:18-30
Execution Logic
Habits only message the user in the Pilot's chat if they have something significant to report. If a run results in "NOTHING_TO_REPORT", it remains silent.
Pilot Interface and Overview
The PilotOverview component provides a centralized view for managing Pilot activities. It is organized into tabs:
- Sessions: Lists every session started by the Pilot, including active, history, and search filters.
- Documents: Displays artifacts and reports written by the Pilot.
- Habits: Manages scheduled tasks, allowing users to add, edit, or run habits immediately.
- Changes: Shows pending file changes across projects assigned to the Pilot, enabling review and commit actions.
Sources: src/features/pilots/ui/PilotOverview.tsx:43-70, src/features/pilots/ui/PilotOverview.tsx:238-275
Status Tracking
The Pilot's state is derived from its underlying session activity.
- Working: The Pilot is thinking, writing, or executing a tool.
- Needs you: The Pilot is waiting for user approval or an answer to a question.
- Idle: No active turns are running.
Sources: src/features/pilots/model/pilot.ts:318-350
Summary
Pilot Agents represent the primary interface for persistent automation and multi-project orchestration in Rebase. By leveraging a centralized identity, persistent Markdown-based memory, and scheduled Habits, Pilots act as autonomous collaborators that maintain context across the development lifecycle.