System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
- src/features/skills/model/createSkill.ts
- src/features/pilots/model/pilotFiles.ts
- src/features/orchestration/model/orchestrationPlan.ts
- src/features/sessions/model/plan.ts
- host/server.test.ts
- README.md
- src/shared/lib/paths.test.ts
- src/features/automations/model/automationTemplates.ts
- crates/rebase-gpui/src/settings/skill_document.rs
Rebase is a graphical user interface for coding agents that integrates multiple provider subscriptions (such as Claude Code, Cursor, and Devin) into a unified workspace. The system employs a hybrid architecture comprising a production React/Tauri application, an experimental Rust/GPUI native preview, and a remote host engine for RPC-based operations.
Sources: README.md:1-12, README.md:52-64
High-Level Component Overview
The architecture divides responsibilities between the user interface, a backend bridge (Tauri or Native GPUI), and an orchestration layer that manages agent communication.
The system interacts with local provider CLIs to execute agent tasks while maintaining session data and project context locally in a SQLite database (rebase.db).
Sources: README.md:12-14, README.md:66-70, host/server.test.ts:28-40
Remote Host and RPC Server
Rebase includes a HostEngine and HostServer that facilitate remote operations and agent-to-environment interactions through a JSON-RPC interface.
Key Remote Modules
- HostEngine: Manages project lifecycles, environment state, and provider interactions.
- HostStore: Handles persistent data for the host, including device authentication tokens and environment identities.
- HostServer: Exposes RPC endpoints for command dispatch, file system manipulation, and Git operations.
RPC Methods Summary
| Method | Description |
|---|---|
commands.dispatch | Triggers agent actions like creating or sending messages to sessions. |
workspace.run | Executes workspace commands such as list_dir, read_text_file, or stat_files. |
git.worktreeCreate | Manages isolated Git worktrees for parallel agent tasks. |
attachments.upload | Handles file uploads for agent context. |
Sources: host/server.test.ts:70-100, host/server.test.ts:250-300, host/server.test.ts:400-450
Agent Orchestration and Planning
Rebase uses a specialized orchestration model to decompose complex user requests into discrete tasks assigned to different worker agents.
Orchestration Workflow
The Lead Agent prepares an OrchestrationProposal which includes a task breakdown and worker model selection.
Data Structures
- ProposedTask: Defines a task's ID, title, model settings, and file scopes.
- OrchestrationProposal: Contains the execution status, task list, and worker model catalog.
Sources: src/features/orchestration/model/orchestrationPlan.ts:5-40, src/features/orchestration/model/orchestrationPlan.ts:210-230
Pilot System and Persistent Memory
Pilots are agents that operate across projects and maintain persistent memory through specific Markdown files stored in the application data folder.
File-Based Identity
| File | Purpose |
|---|---|
SOUL.md | Contains standing instructions and the agent's identity. |
MEMORY.md | Stores dated facts and user preferences (limited to ~200 lines for context). |
memory/*.md | Topic-specific notes for detailed long-term storage. |
Context Planning
Rebase calculates the AgentContextPlan for every turn. It determines if the "Soul" (identity) or "Memory" needs to be resent to the native provider session based on version hashes.
Sources: src/features/pilots/model/pilotFiles.ts:13-25, src/features/pilots/model/pilotFiles.ts:180-210, src/features/pilots/model/pilotFiles.ts:275-290
Skill and Automation Framework
The system allows users to define "Skills" and "Automations" to extend agent capabilities using standard Markdown formats.
Skill Structure
Skills are stored as SKILL.md files within specific directories:
- Project Scope:
.agents/skills/<name>/SKILL.md - Personal Scope:
~/.agents/skills/<name>/SKILL.md
Sources: src/features/skills/model/createSkill.ts:16-30
Automation Templates
Automations are predefined tasks triggered by time schedules (e.g., weekdays at 09:00) or external events (e.g., GitHub PR opened). The AUTOMATION_TEMPLATES define categories like security, review, and incidents.
Sources: src/features/automations/model/automationTemplates.ts:45-70
Data Flow and Storage Resolution
The system manages complex path resolution to ensure agents operate within authorized file scopes, especially when using remote hosts or isolated worktrees.
Summary
The Rebase architecture emphasizes modularity and environment isolation. By separating the user interface from the host engine and provider CLIs, the system enables cross-platform support (Tauri/GPUI) and remote collaboration. The use of Markdown for memory and skills ensures that agent intelligence is portable and human-readable.