Overview

Orbicus is an on-device AI system designed for deliberate, reliable software engineering. It reads your codebase, forms structured multi-step plans, executes edits through safe tools, and verifies its own work against tests and linters.

Powered by Orbicus Core, it runs independently in the background on your machine, even after you close your editor or terminal.

Core Architecture

Orbicus decouples the agent engine from the user interface. A single background engine connects seamlessly to whichever client fits your development flow:

Component	Format	Primary Use Case
Orbicus Core	Background Engine	Orchestrates state, task planning, token compaction, and provider connections.
Orbicus Workspace	Desktop App	Dedicated visual workspace for side-by-side diff review, planning, and task tracking.
Orbicus for VS Code	IDE Extension	In-editor agent chat, inline diff reviews, and task management inside VS Code & Cursor.
Orbicus CLI	Terminal Tool	Global executable for interactive terminal TUI and headless shell scripting.

Key Principles

1. Local-First & Private

Your source code, project files, and development environment remain entirely on your local machine. Orbicus transmits prompt contexts directly to your configured AI model provider over encrypted connections, with zero intermediary servers processing your code.

2. Universal Model & Protocol Freedom

Orbicus is completely model-agnostic and never locks you into a predefined list. You can supply any model ID and connect to any supported provider or custom endpoint:

Anthropic Protocol: Official Claude endpoints and Anthropic-compatible proxies.
OpenAI Protocol: Official OpenAI endpoints and compatible APIs (DeepSeek, MiniMax, Groq, Mistral, Together AI, OpenRouter).
Google Gemini Protocol: Official Gemini AI Studio endpoints and enterprise gateways.
Custom Compatible Endpoints: Full support for custom baseUrl endpoints across OpenAI, Anthropic, and Google api formats.
Local & Offline Execution: 100% offline inference using Ollama, vLLM, or LM Studio.

3. Security, Risks & Control Model

Orbicus runs directly on your machine with your user privileges to read files, edit code, and run terminal commands. Understanding this execution model helps you configure the right level of autonomy:

Security & Privacy Boundaries:
- Zero Intermediaries for Code & Keys: Your source code, workspace context, and API credentials never touch Orbicus servers. Communication occurs directly between your device and your chosen AI endpoint.
- Local State Storage: Configuration, credentials, and conversation history remain stored in your home directory (~/.orbicus/).
- Opt-In Diagnostics: Any future product analytics or crash reporting is disabled by default, requires explicit opt-in, and strictly excludes code context or API keys.
Risks of Autonomous Execution:
- Host Permission Scope: Orbicus tools execute with the permissions of your logged-in user. Unchecked commands could accidentally modify system files or run unwanted shell scripts.
- Prompt Injection & Third-Party Code: Reading untrusted external files, dependencies, or web content could attempt to instruct the model to execute unexpected commands.
Mitigations & Autonomy Trade-offs:
- Configurable Protection Rules: You can require manual approval prompts for file modifications, destructive terminal commands, or sensitive tool calls.
- Full Autonomy vs. Supervised Mode: You choose the balance between fast unattended execution and strict step-by-step confirmation.

4. Functional Definition of an Agent

In Orbicus, an agent is treated strictly as an engineered execution runtime rather than an anthropomorphized entity:

"An agent is defined solely by the ongoing tasks of its session, the knowledge and skills provided to it, and the tools and plugins available to execute work. It possesses no identity or persona beyond that scope."

Session & Task Scope: An agent coordinates multi-step workflows, tracks sub-goals, and adapts dynamically across your development session.
Knowledge & Skills: The agent's reasoning is grounded in your workspace codebase, project documentation, rules, and specialized skill packages (.skills/).
Tools & Plugins: It interacts with your environment exclusively through configured tools, custom plugins, shell interfaces, and external Model Context Protocol (MCP) servers.
No Artificial Persona: The system focuses purely on transparent, deterministic execution without simulated emotions or artificial persona layers.

Next Steps

Ready to get started? Follow the step-by-step setup instructions in the Installation Guide to install the Desktop App, CLI, or VS Code extension on your machine.