Orbital

简介

<p align="center"> <strong>English</strong> · <a href="README.zh-CN.md">简体中文</a> </p>

<p align="center"> <img src="docs/subagent-dispatch.gif" alt="Delegating work to Claude Code from inside an Orbital project" width="800"> </p> <p align="center"><em>You assign work to the project. The agent plans, delegates to Claude Code, and reports back.</em></p>

<p align="center"> <img src="docs/approval.gif" alt="Claude Code requests approval to create a folder — approved from phone" width="800"> </p> <p align="center"><em>Consequential action — approval request to your phone — work continues.</em></p>

Give your agent a project, not a prompt.

The project workspace you and your agent share — with memory that persists,
sandbox boundaries you set, and approvals you control.

<p align="center"> <a href="https://github.com/zqiren/Orbital/releases/download/v0.5.1/Orbital-Setup-1.0.0.exe"><strong>Windows Installer (.exe)</strong></a> &nbsp;&middot;&nbsp; <a href="https://github.com/zqiren/Orbital/releases/download/v0.5.1/Orbital-1.0.0-macOS.dmg"><strong>macOS Installer (.dmg)</strong></a> &nbsp;&middot;&nbsp; <a href="https://www.youtube.com/watch?v=ranTQFmW6vU"><strong>Watch the demo</strong></a> </p> <p align="center">Set up in under 5 minutes. No Python or Node required.</p>

<p align="center"> <img src="docs/screenshots/orbital-logo.png" alt="Orbital" width="80"> </p>

Feature Deep Dives

<details> <summary><strong>Orbital Is / Is Not</strong></summary>

</details>

<details> <summary><strong>Project & Workspace Model</strong></summary>

Each project maps to a workspace directory and maintains its own sessions, triggers, and configuration.

<p align="center"> <img src="docs/screenshots/files.png" alt="File explorer — browse and upload files in the project workspace" width="800"> </p> <p align="center"><em>Browse, preview, and upload files in each project's workspace</em></p>

{workspace}/
+-- orbital/                            # Operational metadata
    +-- sessions/
    |   +-- {session_id}.jsonl          # Append-only session log
    +-- instructions/
    |   +-- project_goals.md
    |   +-- user_directives.md
    +-- skills/                         # Project skills
    +-- sub_agents/                     # Sub-agent transcripts
    +-- tool-results/                   # Tool output artifacts
    +-- output/                         # Agent work artifacts
    |   +-- screenshots/                # Browser screenshots
    |   +-- pdfs/                       # Saved PDFs
    |   +-- shell-output/               # Shell command output
    +-- PROJECT_STATE.md                # Current task state
    +-- DECISIONS.md                    # Decision log
    +-- LESSONS.md                      # Learned patterns
    +-- SESSION_LOG.md                  # Last 3 session summaries
    +-- CONTEXT.md                      # External reference material

~/orbital/                              # Home global (daemon infrastructure)
+-- daemon.pid                          # Singleton enforcement
+-- daemon-state.json                   # Agent heartbeat state
+-- device.json                         # Device identity
+-- browser-profile/                    # Shared browser profile
+-- credential-meta.json                # Credential metadata

Session format: One JSON line per message (role, source, content, timestamp, tool_calls). Append-only with file locks. Never modified except during compaction.

</details>

<details> <summary><strong>Quick Tasks</strong></summary>

The sidebar includes a Quick Task section for fire-and-forget interactions. Scratch projects skip the full project creation flow — useful for one-off tasks that don't need a dedicated workspace.

<p align="center"> <img src="docs/screenshots/quick-task.png" alt="Quick Task — browsing Hacker News and returning structured results" width="800"> </p>

</details>

<details> <summary><strong>Autonomy & Approval System</strong></summary>

Three autonomy presets control how much supervision agents receive:

<p align="center"> <img src="docs/screenshots/budget.png" alt="Project settings — autonomy presets and budget controls" width="700"> </p> <p align="center"><em>Pick an autonomy level and set budget limits per project</em></p>

Approval flow: 1. Interceptor catches tool call based on autonomy rules 2. Frontend shows an Approval Card with tool name, arguments, and context 3. User can Approve, Deny, or Auto-approve for 10 minutes 4. Per-action bypass: same tool+args auto-approved for 60 seconds

<p align="center"> <img src="docs/screenshots/5B2-mobile-approval-card.png" alt="Mobile approval card — approve agent actions from your phone" width="350"> </p> <p align="center"><em>Approve agent actions from your phone — with full context and optional guidance</em></p>

</details>

<details> <summary><strong>Sub-Agent Delegation</strong></summary>

Orbital is not tied to a single AI tool. The management agent plans and delegates, while specialized sub-agents execute. Any CLI-based agent can be registered via a manifest file.

<p align="center"> <img src="docs/screenshots/3A-chat-file-creation.png" alt="Management agent creating a plan and delegating to sub-agents" width="800"> </p> <p align="center"><em>The management agent creates an implementation plan...</em></p>

<p align="center"> <img src="docs/screenshots/3B-subagent-delegation.png" alt="Sub-agent executing delegated work and reporting back" width="800"> </p> <p align="center"><em>...delegates Phase 1 to @claudecode, monitors progress, and reviews the result</em></p>

Transport types:

Note: ACP transport is implemented in the daemon but agent manifests currently default to PTY for stability. Switching any ACP-compatible agent (Gemini CLI, Codex, Copilot CLI, Cline, Goose) to ACP is a one-line manifest change — see docs/acp-migration.md (coming soon).

</details>

<details> <summary><strong>Built-in Tool Suite</strong></summary>

The management agent has access to these tool categories:

</details>

<details> <summary><strong>Browser Automation</strong></summary>

Built on Patchright (a Playwright fork with anti-bot-detection):

• Stealth mode: Anti-automation detection scripts injected into every browser context
• Shared profile: One browser profile across all projects — log into services once, all agents share cookies
• Accessibility-first: snapshot returns an accessibility tree with [ref=eN] element references for reliable interaction
• 26 browser actions: navigate, click, type, fill, press, hover, select, drag, upload, snapshot, screenshot, extract, search (page), evaluate, tab management, go back/forward, reload, wait, PDF export, web search, URL fetch, batch

<p align="center"> <img src="docs/screenshots/5A-mobile-browsing-activity.png" alt="Agent browsing arxiv.org and scanning research papers" width="350"> </p> <p align="center"><em>An agent browsing arxiv.org — scanning for AI reasoning papers on a daily schedule</em></p>

</details>

<details> <summary><strong>Continuous Operation & Triggers</strong></summary>

Agents run continuously via triggers — no manual intervention needed. Create triggers through natural language in the chat:

"Watch the uploads/ folder for new .jpg files and analyze them" "Run a research scan every morning at 6 AM"

The management agent translates this into a create_trigger tool call with the appropriate type and parameters.

Trigger types:

<p align="center"> <img src="docs/screenshots/file-watch-trigger.png" alt="File watch trigger — monitoring auth/ directory for .py changes" width="800"> </p> <p align="center"><em>File watch trigger: monitors auth/ for .py changes, runs tests on every save. 22 runs so far.</em></p>

<p align="center"> <img src="docs/screenshots/scheduled-trigger.png" alt="Scheduled trigger — daily research scan at 6 AM" width="800"> </p> <p align="center"><em>Scheduled trigger: scans arxiv, Hacker News, and tech blogs every day at 6 AM. 12 runs.</em></p>

Real-world example — Health Tracker with file watch:

<p align="center"> <img src="docs/screenshots/4B-mobile-meal-chat1.jpg" alt="Setting up a meal photo file watcher from phone" width="350"> &nbsp;&nbsp;&nbsp;&nbsp; <img src="docs/screenshots/4B-mobile-meal-chat2.jpg" alt="Agent automatically analyzing a meal photo" width="350"> </p> <p align="center"><em>Left: "Watch uploads/ for meal photos and track calories." Right: Drop a photo, get instant nutritional analysis.</em></p>

</details>

<details> <summary><strong>Context Management & Compaction</strong></summary>

Five workspace files maintained by the LLM at session boundaries:

Cold resume: On session start, these files are assembled into the system prompt to reorient the agent — no context lost between sessions.

Compaction (when context usage exceeds 80%): memory flush, LLM-driven summarization of older messages, recent messages kept intact, post-compaction reorientation with project goals and current state.

Prefix caching (v0.4.2): the system prompt is split into static, semi-stable, and truly-dynamic sections so up to ~95% of input tokens hit the provider's prefix cache on follow-up turns. See the v0.4.2 release notes for benchmark numbers.

</details>

<details> <summary><strong>Mobile Remote Control</strong></summary>

Control agents from your phone on the local network or via a cloud relay.

<p align="center"> <img src="docs/screenshots/4A-mobile-dashboard.png" alt="Mobile dashboard — all projects at a glance" width="350"> &nbsp;&nbsp;&nbsp;&nbsp; <img src="docs/screenshots/5C-mobile-approved.png" alt="Agent completing work after mobile approval" width="350"> </p> <p align="center"><em>Left: Project dashboard on phone. Right: Agent completes its research after you approve from anywhere.</em></p>

Local network: Scan the QR code in Settings to open Orbital on your phone via LAN.

<p align="center"> <img src="docs/screenshots/qr-code-lan-pairng.png" alt="QR code for mobile access on local network" width="700"> </p> <p align="center"><em>Scan to open Orbital on your phone — same Wi-Fi network required</em></p>

Cloud relay (optional): Deploy a relay server for access outside your home network. Push notifications for approval requests, budget alerts, and agent status changes.

</details>

<details> <summary><strong>Cost Controls & Budget Limits</strong></summary>

Per-project budget limits prevent runaway spending:

The agent loop tracks cumulative token usage and computes cost using per-model pricing from the provider registry. When the budget threshold is reached, the configured action fires and a push notification is sent.

</details>

<details> <summary><strong>Credential Management</strong></summary>

<p align="center"> <img src="docs/screenshots/credential-store.png" alt="Credential store — website passwords stored in system keychain" width="700"> </p> <p align="center"><em>Website credentials stored in your system keychain. Agents always ask permission before using them.</em></p>

• API keys: Stored in OS keychain (keyring), masked in API responses, per-project BYOK override
• Website credentials: Metadata in credential-meta.json, values in OS keychain. The request_credential tool lets agents request credentials mid-session via a secure modal — credentials never appear in chat history.

</details>

<details> <summary><strong>LLM Provider Routing & BYOK</strong></summary>

13 providers supported out of the box:

Anthropic, OpenAI, DeepSeek, Moonshot (Kimi), Groq, Google Gemini, xAI, Mistral, Together, OpenRouter, Zhipu, Qwen, plus a custom entry for any OpenAI-compatible endpoint (e.g., Ollama, Azure OpenAI, self-hosted models).

• SDK routing: Anthropic SDK for Anthropic, OpenAI SDK for OpenAI-compatible providers
• Per-model metadata: Display name, tier, context window, max output, capabilities (vision, tool use, streaming), pricing
• Fallback rotation: When the primary provider fails, the loop rotates to fallback providers with error classification (transient, rate limit, abort)

</details>

<details> <summary><strong>Loop Safety Guards</strong></summary>

The agent loop includes multiple safety mechanisms to prevent runaway execution:

</details>

<details> <summary><strong>Desktop App & System Tray</strong></summary>

Orbital ships as a desktop application bundled with PyInstaller:

• System tray: Agent activity status, quick access menu, running port in tooltip
• Native window: Embeds the React frontend via pywebview — no browser needed
• Daemon lifecycle: Desktop app spawns the daemon on launch, manages port allocation, cleans up on exit
• Sleep prevention: Blocks system sleep while agents are active (Windows SetThreadExecutionState), re-allows when idle

Skills system: Agents create reusable skills from multi-step workflows and consult matching skills before starting similar tasks. Skills are stored as SKILL.md files in the workspace and managed through the Settings UI.

<p align="center"> <img src="docs/screenshots/skills.png" alt="Skills — operational patterns the agent follows" width="700"> </p> <p align="center"><em>Skills like Efficient Execution, Learning Capture, and Task Planning shape how the agent works</em></p>

</details>

---