GitHub - zqiren/Orbital: The Project Agent: Where every agent's work compounds in your local project

English · 简体中文

🔥 Aug 13, 2026 — DeepSeek's official harness (dsh) launched today; Orbital dispatched it as a sub-agent within 3 hours — same project memory, same queue, same files. Full integration (one-click install, key management, tool capsules) built in 5 hours that night. Watch the demo →

What you're seeing: a marketing project asks Orbital to size up a competitor. It researches the target itself so the task brief is accurate, hands the token-heavy deep-dive to Claude Code per a standing project directive, then reads the findings back against the project's own decisions and lessons — ending on the calls only you can make.

The project agent

Every agent owns a session. Orbital owns the project.

Orbital works like Claude Code or Codex: ask it to research, plan, write, run commands, browse the web, or operate your tools.

The difference is that Orbital treats a local folder as a long-running project. It maintains the project's context on its own — where it left off, what's next, and how to do it — as files inside that folder. Every new task starts from everything learned before it, so work compounds instead of resetting to zero.

Orbital can also dispatch Claude Code, Codex, Gemini CLI, Cursor, and other CLI agents. Every dispatch briefs the worker on the project and the task and points it at the relevant files — you never re-explain the project. Orbital watches the run, reads the result against the project's context, and writes the outcome back in. The more you delegate, the more it knows.

One accountable manager · Interchangeable workers · Local-first

Windows Installer (.exe)  ·  macOS Installer (.dmg)  ·  Watch the demo

Set up in under 5 minutes. No Python or Node required. Bring your own API key.

Why a project agent?

People already use several capable agents at work — for the newest model, the leftover quota, or because a particular tool is better at the job.

But each agent works inside its own session, with its own context and history. When you move between sessions or tools, you become responsible for carrying the project between them: restating goals, explaining previous decisions, locating artifacts, and checking what was left unfinished. You end up working as their intern, ferrying context between them to keep your own project moving.

Orbital changes the unit of work from the session to the project.

A project agent stays responsible for the project across tasks, sessions, and worker agents. It maintains the shared context, decides what needs to happen next, delegates when useful, and records every outcome back into the project.

Individual agents complete tasks. Orbital keeps the project moving.

What it means to own the project

Orbital maintains five things that normally disappear or fragment between agent sessions — all of them as plain files in your project folder:

• State — what is true about the project now (PROJECT_STATE.md)
• Decisions — what was decided and why (DECISIONS.md)
• Lessons — what the project has learned (LESSONS.md)
• Work — what is running, completed, or blocked (queue.json). Every queued task ends Completed or Blocked — an agent that stops without a verdict gets re-prompted, then force-blocked with a reason. Nothing drifts away silently.
• Artifacts — what the agents researched, wrote, or built (the workspace itself, plus orbital/output/)

These stay in the local project and become context for future work. On a cold start, Orbital assembles them into its own system prompt before it acts.

When Orbital delegates, the worker is pointed at those same files and told they are authoritative — that briefing is rendered fresh on every dispatch, not something you paste in. Each worker also keeps its own memory file inside the project, so it accumulates its own experience across dispatches. When the task finishes, Orbital reads the result and records what matters back into the project.

The worker can change. The project continues.

How it works

1. Set up once — pick an LLM provider and paste your API key; optionally connect accounts your agents will need.

2. Create a project — name it, choose the local folder that holds your work, set an autonomy level.

3. Give Orbital a task — ask it to research, plan, write, code, browse, or work with files.

4. Orbital maintains the context — it keeps the project's state, decisions, lessons, queue, and artifacts current as the work progresses.

5. Orbital delegates when useful — it dispatches work to Claude Code, Codex, Gemini CLI, Cursor, or another CLI agent against the same accumulated context.

6. Every result becomes part of the project — future tasks begin on top of the work that came before them.

flowchart LR
    You["You"] --> Orbital["Orbital<br/>Project agent"]
    Orbital <--> Project["Local project folder<br/>State · Decisions · Lessons · Queue · Artifacts"]
    Orbital -->|briefs + dispatches| Workers["Worker agents<br/>Claude Code · Codex · Gemini CLI · Cursor"]
    Workers -->|results| Orbital
    Orbital -->|every task ends<br/>Completed or Blocked| Project
    Phone["Your phone"] -.->|approvals · check-ins| Orbital

A concrete example

Suppose you ask Orbital to research a competitor.

Orbital gathers the initial information and records the findings inside the project. It then dispatches the token-heavy technical investigation to Claude Code, which starts by reading the project's goals, constraints, and previous decisions from the project folder.

When Claude Code finishes, Orbital reads its findings and records the useful results back into the project.

A week later, you ask Orbital to draft a launch plan. It begins with that earlier research, the decisions made since, and the artifacts already produced.

You do not begin again with an empty chat. You continue the project.

Quick Start

1. Launch Orbital — the setup wizard guides you through two steps:

   Step 1 — LLM Provider: Pick a provider from the preset cards, follow the key-console link to grab an API key, and paste it in. Supports DeepSeek, Anthropic, OpenAI, Moonshot, and a dozen other providers.

   

   Step 2 — Connect Your Accounts: Link API connectors (Google Calendar, Drive) and sign in to sites your agents will need (Google, GitHub, etc.) so they can browse without getting blocked by CAPTCHAs. Everything here is optional and can be done later in Settings.

   

2. Create a project — give it a name, pick a workspace directory, set an autonomy level

3. Chat — type a task in the chat bar and the project agent handles it
4. Walk away — queue the next tasks; each finished one becomes context the next builds on

See the project stay under one manager

The project agent keeps the project's state, decisions, and lessons current across sessions.

It delegates to Claude Code, Codex, or Gemini CLI against the same project context, then records the result.

At a Glance

Why the project never loses its memory

• Accountable management loop — one agent plans, delegates, supervises, and records outcomes for the project
• Persistent project context — PROJECT_STATE.md, DECISIONS.md, LESSONS.md, and artifacts remain available across sessions
• Self-improving skills — the agent creates reusable skills from multi-step workflows and consults them before repeating similar tasks

Why you can swap agents mid-project

• Interchangeable workers — dispatch Claude Code, Codex, Gemini CLI, Cursor, or any CLI agent against the same project context
• Task queue — queue work per project and walk away; the agent drains items one at a time, marking each completed (with a summary) or blocked (with a reason); pause mid-queue to chat and steer, then resume

Why you can delegate without watching

• Workbench (beta) — the decisions and actions only you can take, flagged by the agent as it works and collected across every project into one list, each with the evidence behind it
• Project-based governance — each project is a folder with its own workspace, instructions, queue, budget, approval policy, and audit trail
• Sandboxed execution — agents only access folders you specify (Windows sandbox user, macOS Seatbelt)
• Approval workflows — agents pause before risky actions; approve from desktop or phone
• Budget controls — per-project spending limits with configurable actions
• Credential store — API keys and website passwords in OS keychain, never exposed to chat

Why the project moves while you're away

• Triggers — set up a cron job or file watcher so the project agent checks in regularly and kicks off workers without you
• Calendar (beta) — every enabled automation projected onto a week view, so scheduled work stays visible instead of firing invisibly
• Mobile supervision — manage agents from your phone via QR code pairing

Under the hood

• 14 built-in LLM providers — Anthropic, OpenAI, DeepSeek, Moonshot (Kimi), Groq, Google Gemini, xAI, Mistral, Together, OpenRouter, Zhipu, Qwen, TokenDance (词元跳动), plus custom endpoints
• Browser automation — 26 browser actions via Patchright with anti-detection

How Orbital compares

Memory, scheduling, and sub-agents are table stakes now — every tool below has them. These are the three questions where the answers still differ.

The short version: the difference isn't any one capability — it's that the project, not the session, is the unit that owns state, workers, and governance.

Feature Deep Dives

How the project stays under one manager

{workspace}/
+-- AGENTS.md                           # Onboarding signpost for external agents (seeded at creation, user-owned)
+-- 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 + per-worker MEMORY.md
    +-- tool-results/                   # Tool output artifacts
    +-- output/                         # Agent work artifacts
    |   +-- screenshots/                # Browser screenshots
    |   +-- pdfs/                       # Saved PDFs
    |   +-- shell-output/               # Shell command output
    +-- queue.json                      # Task queue (queued / running / completed / blocked)
    +-- PROJECT_STATE.md                # Current-state scratchpad (overwrite)
    +-- DECISIONS.md                    # Durable decisions + reasoning
    +-- LESSONS.md                      # Durable heuristics / playbooks
    +-- INDEX.md                        # Navigation map: file tree + one line per file
    +-- DECISIONS_ARCHIVE.md            # Demoted decisions (read-on-demand)
    +-- LESSONS_ARCHIVE.md              # Demoted lessons (read-on-demand)

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

Tools & execution

Control & safety

Architecture

Orbital is one persistent agent bound to a project — not a chat session. It acts as a local control plane for the project's workspace, instructions, state, queue, budget, and approval rules. It plans, delegates, supervises, and records outcomes; worker agents execute against the same project context. You supervise from anywhere.

flowchart TB
    UI["<b>Frontend (React SPA)</b><br/>Chat UI · Approval Cards · Settings · Files"]

    subgraph daemon["Daemon (FastAPI + uvicorn)"]
        direction TB
        AM["AgentManager<br/><i>lifecycle</i>"]
        SAM["SubAgentManager<br/><i>delegation</i>"]
        TM["TriggerManager<br/><i>cron · file watch</i>"]
        Loop["Agent Loop<br/><i>streaming · safety guards</i>"]
        TR["Worker Transports<br/>Codex app-server · SDK · PTY · ACP · Pipe"]
        LLM["LLM Provider<br/><i>OpenAI + Anthropic SDK</i>"]
        Tools["Tool Registry<br/><i>shell · file · browser · triggers</i>"]
        Auto["Autonomy Interceptor<br/><i>approve · deny · bypass</i>"]

        AM --> Loop
        SAM --> TR
        TM --> AM
        Loop --> LLM
        Loop --> Tools
        Loop --> Auto
    end

    Platform["<b>Platform Layer</b><br/>Windows sandbox user · macOS Seatbelt · Linux bubblewrap (planned)"]
    Relay["<b>Cloud Relay (Node.js, optional)</b><br/>REST proxy · Event forwarding · Push notifications · Pairing"]
    Phone["Phone"]

    UI <-->|REST + WS| AM
    UI <-->|REST + WS| SAM
    Tools --> Platform
    AM -.WebSocket tunnel.-> Relay
    Relay -.WebSocket.-> Phone

Key design decisions:

• The agent owns the project: it maintains structured state, decisions, lessons, and session history so planning and accountability remain in one place
• Isolation: OS-level sandboxing (Windows sandbox user, macOS Seatbelt, Linux bubblewrap planned)
• Fail-closed interceptor: Any approval system error results in DENY, never ALLOW
• Single daemon: PID file enforcement prevents multiple instances
• Local-first: Your files and project state live on your disk. The cloud relay, when enabled, proxies approvals and events — not your files.

Installation

Windows

1. Download the Orbital-Setup-*.exe from Releases (latest Windows build)
2. Run the installer and follow the prompts
3. Launch Orbital from the Start Menu or desktop shortcut

macOS

1. Download the Orbital-*-macOS.dmg from Releases
2. Open the DMG and drag Orbital to your Applications folder
3. Launch Orbital from Applications or Spotlight

Requires macOS 13 (Ventura) or later, Apple Silicon (M1 or newer). Intel Macs are not supported by this build (the bundle is arm64-only).

Release builds are Developer-ID signed and notarized by Apple, so the app opens normally on first launch — no Gatekeeper warning or "Open Anyway" workaround needed. (If you built Orbital from source or grabbed a CI branch artifact, that build is ad-hoc signed and macOS will still ask you to approve it once via right-click → Open.)

From Source

# Clone the repository
git clone https://github.com/zqiren/Orbital.git && cd Orbital

# Install Python dependencies (Python 3.11+)
pip install -e ".[desktop]"

# Install frontend dependencies (Node.js 18+)
cd web && npm install && cd ..

# Start the daemon
python -m uvicorn agent_os.api.app:create_app --factory --port 8000

# Start the frontend dev server (separate terminal)
cd web && npx vite --host 127.0.0.1 --port 5173

Open http://localhost:5173 in your browser. The setup wizard runs on first launch.

Note on Sleep/Shutdown

Orbital prevents system sleep while agents are actively working (via OS-level sleep inhibition on Windows and macOS). When all agents are idle, sleep is re-allowed. The system tray icon shows current agent activity status.

Development

Backend

# Start daemon
python -m uvicorn agent_os.api.app:create_app --factory --port 8000

# Restart with fresh code
bash scripts/restart-daemon.sh

Frontend

cd web
npm install
npx vite --host 127.0.0.1 --port 5173

Key Paths

Testing

# Unit + platform tests
python -m pytest tests/unit/ tests/platform/ -q

# TypeScript check (zero errors expected)
cd web && npx tsc -b

# Daemon integration test
bash scripts/restart-daemon.sh
curl http://localhost:8000/api/v2/projects

Known pre-existing test notes:

• test_e2e.py, test_user_stories.py — require a real LLM API key set via AGENT_OS_TEST_API_KEY

Roadmap

Shipped

• Multi-provider LLM routing with fallback rotation
• Three autonomy presets with cascade to sub-agents
• Streaming chat with real-time WebSocket events
• Browser automation with anti-detection (Patchright)
• Continuous operation via schedule and file-watch triggers
• Natural language trigger creation
• Cloud relay with push notifications and device pairing
• Context compaction with pre-compaction memory flush
• Prefix-cache-optimized prompt assembly (v0.4.2)
• Per-project budget limits and cost tracking
• Credential management (API keys + website credentials)
• Desktop app with system tray and native window
• Agent loop safety guards (iteration cap, repetition, ping-pong, circuit breaker)
• OS-level sleep prevention during agent activity
• Sub-agent delegation with @mention routing

Next

• Webhook triggers — HTTP endpoint that fires agent tasks on incoming webhooks
• Pipeline triggers — Chain project outputs as inputs to other projects
• Network isolation — Per-project domain allowlists enforced at OS level
• Linux sandboxing — bubblewrap enforcement
• Code signing — Eliminate SmartScreen warnings on Windows
• Auto-resume on daemon restart — Restore in-progress sessions

Why I built this

I loved Claude Projects. I hated that I couldn't let an agent update the project, and that it didn't live on my machine.

I loved OpenClaw. I hated the lack of control — no budget, no sandbox, no way to supervise from my phone when I stepped away.

Orbital is the thing I wanted. One agent accountable for the whole project: the plan, the decisions, the queue, the budget, and the approvals. The phone to check in when I'm not at my desk. Claude Code, Codex, and Gemini CLI as workers it can choose for the job without handing away the project's context.

Built nights and weekends while working full-time. Still very early. Feedback and issues welcome.

Sponsors

Orbital is proudly sponsored by Watcha (观猹) — the team behind TokenDance (词元跳动), the China-mainland LLM router built into Orbital. Thanks to this sponsorship, new users in mainland China can sign in to TokenDance with one tap during onboarding, claim free tokens, and start working immediately — no manual API-key setup.

Telemetry

Orbital sends one anonymous aggregate per day — counters, enums, and booleans only. Never prompts, files, paths, model output, or any project/session identifier. The exact outbound JSON is inspectable verbatim in Settings → Data & privacy, where a single toggle turns it off. The full published schema is in docs/TELEMETRY.md.

License

Orbital is licensed under the GNU General Public License v3.0.

Orbital — Every agent owns a session. Orbital owns the project.
Copyright (C) 2026 Orbital Contributors

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.