@kaiba-cloud/orbital 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,130 @@
+# Orbital
+
+Orbital runs teams of agents on your machine. A team has a lead and members. You give the team a mission, and you watch it live in your terminal or in Claude Code.
+
+## Install
+
+1. Install the CLI. It needs Node 22.18 or later and Claude Code.
+
+   ```bash
+   npm i -g @kaiba-cloud/orbital
+   ```
+
+2. In your repository, connect Claude Code. This writes `.claude/orbital.yaml` and the Claude Code mod.
+
+   ```bash
+   orbital install claude
+   ```
+
+3. In Claude Code, run `/reload-plugins`, then `/orbital` to open the pane.
+
+## Skills
+
+- The orbital-team skill comes with the mod. It teaches Claude to work with teams and missions.
+- To build a plugin, install the plugin builder skill. Add `--global` to install it for every project.
+
+  ```bash
+  orbital skill install orbital-plugin-builder
+  ```
+
+## The harness folder
+
+Orbital reads the harness folders of a project: `.claude`, `.codex`, and the folders that a harness plugin adds.
+Each harness folder holds these files for orbital:
+
+- `orbital.yaml` holds the keys of the node, such as `plugins:`, `listen:` and `folders:`.
+- `agents/<name>.md` is an agent.
+- `teams/<team>/CHARTER.md` is a team.
+- `policies/<name>.json` is a policy.
+- `missions/<id>/MISSION.md` is a mission.
+
+An agent turn runs in a sandbox.
+The sandbox makes the `agents`, `teams`, `policies` and `skills` folders of each harness folder read-only.
+Every other file of the project is a normal project file that the agent can write.
+By default, an agent writes its memory to `memory/<agent>`, its plans to `plans/<agent>` and its session notes to `sessions/<agent>/<session>` in the harness folder.
+The `folders:` key of `orbital.yaml` changes these places.
+
+## Set up a team
+
+Paste this prompt into Claude Code in your repository:
+
+> Set up an orbital team for this repo. Read the agents in `.claude/agents/`. If there are none, create a lead agent and one worker agent that fit this project. Then write `.claude/teams/<team>/CHARTER.md` with `apiVersion: orbital/v1alpha1`, the team name, a one-line objective, the lead, and the members, each with `harness: claude`. The lead hands work to the members and never does the work itself. Run `orbital check` and fix every problem it reports. Then show me the charter.
+
+## Run a mission
+
+1. Check that the team and its agents load.
+
+   ```bash
+   orbital check
+   ```
+
+2. Start the node with the live view.
+
+   ```bash
+   orbital up
+   ```
+
+   To run only some teams, name them. Add `-d` to run in the background, and stop with `orbital down`.
+
+   ```bash
+   orbital up build
+   orbital up build review
+   ```
+
+   Teams load live. A node that you start with no team names serves every team of the project, and it watches the `teams` and `agents` folders of each harness folder (`.claude`, `.codex` and so on).
+   A new team, a changed charter and a removed team take effect in a few seconds, with no restart. The view, `orbital status`, `orbital mission new` and the pane of Claude Code show the change at once.
+   A node that you start with team names keeps only those teams, and it ignores a new team. A named team that changes or leaves still refreshes.
+   A change that fails `orbital check` is not loaded. The node keeps the last good version of the team, and the view shows the problem on the row of the team.
+   A team or a member that you remove keeps running until its active mission ends, and the view says so on the row of the team.
+
+3. Write a mission, then start it.
+
+   ```bash
+   orbital mission new <team> <id> --intent "…" --end-state "…" --limits "…"
+   orbital mission start <id>
+   ```
+
+4. In Claude Code, run `/orbital join <id>` to follow the mission, and `/orbital say <message>` to talk to the lead.
+
+## Keep it running
+
+Each node runs in the background under a supervisor. Closing the view (`q`, Ctrl+C or a closed terminal) stops no node. Only `orbital down` stops the nodes.
+
+- If a node crashes, its supervisor starts it again and the view says why. A mission that was active comes back paused. Resume it with `orbital mission resume <id>`.
+- A second `orbital up` shows the nodes that run. `orbital up --new` starts a separate node for a separate run, such as `<node>-2`.
+- To start the nodes at each login, install the login service. It uses launchd on macOS and systemd on Linux, and it needs no sudo.
+
+  ```bash
+  orbital service install
+  orbital service status
+  orbital service uninstall
+  ```
+
+## Browser
+
+Each agent session that starts its own chrome-devtools server makes Chrome ask you to allow remote debugging again. The shared browser holds one connection to your Chrome, so you allow it once.
+
+- Sessions that orbital runs on `claude` and on `codex` use the shared browser by themselves. Each session gets its own pages.
+- A session on `claude` or `codex` gets the shared browser in place of each chrome-devtools server of its config. Your config files stay as they are.
+- The `pi` harness has no browser tools. Pi has no MCP client for them yet.
+- A browser call that Chrome does not answer fails after 60 seconds with a clear error. It does not hang.
+- To let your own Claude Code and Codex sessions share the connection, run this once, then start a new session. Install changes the chrome-devtools entries in `~/.claude.json` and in `config.toml` of your Codex home (`CODEX_HOME`, else `~/.codex`). It backs up the old entries. `--revert` restores them.
+
+  ```bash
+  orbital browser install
+  orbital browser status
+  orbital browser install --revert
+  ```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `orbital up` | Run the nodes of this project with the live view |
+| `orbital up <team> [<team>…]` | Run only the nodes of the named teams |
+| `orbital mission list` | List the missions and their state |
+| `orbital mission show <id>` | Show a mission: brief, state, result and history |
+| `orbital mission say <id> "<message>"` | Talk to the lead of a mission |
+| `orbital mission pause <id>` / `resume <id>` | Pause or resume a mission |
+| `orbital telemetry watch` | Print the live event stream |
+| `orbital describe` | List every command |