Cyborgy CLI

cyborgy extends coding-agent CLIs such as Claude Code, Codex, and OpenCode with the Cyborgy MCP, workspace roles, skills, memory, extension APIs, and temporary tunnels.

This package provides:

• cyborgy: the main CLI.
• cyborgy-mcp: the MCP server used by supported coding agents.
• cyborgy-dev and cyborgy-mcp-dev: development-environment entry points.

The built-in profiles are authoritative: cyborgy uses production state in ~/.cyborgy, while cyborgy-dev uses development state in ~/.cyborgy-dev. A stale saved URL for the other built-in environment is ignored. Set CYBORGY_API_URL explicitly when intentionally targeting a custom endpoint.

Install

pip install cyborgy

For local Cyborgy development tooling:

pip install -e .
pip install -r requirements-dev.txt

Basic usage

cyborgy login
cyborgy mcp install --target codex
cyborgy codex exec "summarize this repository"
cyborgy devin -- "review this repository"
cyborgy grok "fix the failing test"

Sending files to the user

Agents send user-facing files with the MCP tool send_file_to_user(path). The file is delivered to the current session through the existing private View API and appears under “Files from AI” in the Cyborgy web app. Returning a local path or opening a local GUI does not deliver a file to a remote user. Files larger than 25 MiB must be reduced or converted so the relevant part can be sent.

The old show_file(path) name remains as a deprecated alias and delegates to the same delivery implementation. It will be retained until both at least two subsequent minor CLI releases have shipped and all active workers are confirmed updated; removal follows whichever milestone occurs later.

The CLI stores login state locally and resolves MCP/skills into user-owned runtime state outside the current repository. Agent wrappers are available for Claude Code, Codex, Cursor Agent, GitHub Copilot CLI, Devin CLI, and Grok Build.

Clean workspace runtime

Normal wrapper launches and sync/install commands do not create .claude, .codex, .cursor, .copilot, .devin, .grok, .cyborgy, .mcp.json, or plugins/ paths in the working tree. Persistent workspace settings use the XDG data directory and generated plugins/configuration use the XDG cache directory:

${XDG_DATA_HOME:-~/.local/share}/cyborgy/<profile>/workspaces/<workspace-key>/
${XDG_CACHE_HOME:-~/.cache}/cyborgy/<profile>/workspaces/<workspace-key>/

CYBORGY_DATA_HOME and CYBORGY_CACHE_HOME override those roots. Worker sessions receive a session-specific cache overlay so concurrent agents in the same repository cannot replace each other's supervisor skills.

Runtime loading is target-specific:

• Claude Code, Cursor Agent, and Copilot receive an external cyborgy-workspace bootstrap plugin through --plugin-dir.
• Copilot also receives the external MCP file through --additional-mcp-config.
• Codex receives the skill catalog and MCP definition through session config overrides while preserving existing developer_instructions.
• Devin receives an external declarative --agent-config; an explicitly supplied JSON/YAML agent config is merged with it.
• Grok receives the external skill catalog through --rules and uses an idempotent user-scoped MCP entry in ~/.grok/config.toml.

To intentionally create native project files for Git management, opt in:

cyborgy mcp install --target claude --project-local
cyborgy skills install <skill-id> --target claude --project-local
cyborgy workspace sync --target claude --project-local

Existing project-local files from older Cyborgy versions are never deleted automatically because they may already be tracked or user-edited. After upgrading, review and remove those legacy generated paths manually if they are not meant to remain in Git.

Agent model catalogs

cyborgy models list reports the model catalogs exposed by installed local agent CLIs. It prefers scriptable account-aware sources such as cursor-agent models, codex debug models, grok models, and opencode models. Claude, Copilot, and Devin use a bounded interactive /model probe when needed.

cyborgy models list
cyborgy models list --tool codex --json
cyborgy models list --no-fallback
cyborgy models list --no-interactive-probe

For tools that only expose account-specific choices through an interactive model selector, the CLI uses a short-lived PTY probe, waits for the tool prompt, answers terminal capability queries, and accepts rows only after the selector is visible. Worker registration caches the same structured catalog for 15 minutes so the web model picker stays aligned with what the local tool can actually show, including degraded/fallback source information. Agent quota/usage reporting follows the same rule: Cyborgy parses structured usage windows from short-lived interactive usage views when available, and reports unknown instead of guessing when a tool does not expose parseable limit, used, or remaining values.

Context rollover history

When a saved native conversation crosses its configured context threshold, the worker starts a fresh native agent session and builds portable continuation context from the authenticated Cyborgy session-event API. Production serves that canonical history from Firestore, so rollover does not depend on the next agent sharing the previous tool, host, HOME, or transcript layout. The worker flushes pending events, reads every history page, and retains both the first user request and the latest turns in the compact context. A local absolute transcript path remains only as a fallback when canonical history is unavailable.

Versioned Worker Runtime

cyborgy worker start is the launcher form: it starts or verifies one background worker for the current local logical-worker scope, then exits 0. That scope is the local device key, current profile, normalized Backend API URL, and resolved Cyborgy config directory. The display name and repository root are not part of the scope. Consequently, starting the same logical worker from another repository root or with another display name is a no-op (already-running) while the recorded Manager PID is alive; stale PID records are replaced safely.

Only the start, stop, and restart lifecycle actions are public. The worker runtime is internal to the managed launcher; use cyborgy worker start for normal operation.

cyborgy worker stop stops only the managed background worker recorded by cyborgy worker start for the same local logical-worker scope. It may therefore stop the Manager started from another repository root or under another display name; the command does not search by process name. Stale or unverified PID records are cleared/refused without sending a signal. If more than one live compatible legacy record is found for the scope, the launcher fails closed and does not choose or signal an arbitrary Manager. cyborgy worker restart uses the same managed-worker safety checks, then starts the worker again using the requested display name and repository root. The repository root remains the Manager/Runtime child execution cwd only; it is not a launcher, state, or runtime identity component.

Launcher ownership records fail closed. If a record is corrupt or cannot be read because of local permissions, start, stop, and restart refuse to spawn or signal a process and identify the record that must be inspected. An already-running start is an idempotent no-op and reports the exact Manager PID and log path.

The public launcher starts one persistent outer Manager in the selected Python. The Manager obtains the Backend's exact release metadata, verifies the SHA-256-pinned wheel, builds an immutable runtime under the user's XDG data directory, and launches the inner Worker with that runtime's absolute Python. The Worker never installs into itself, re-execs itself, or spawns a replacement Worker. cyborgy worker restart remains an explicit operator lifecycle action; the Manager owns normal version handoff, drain, rollback, and runtime GC. If the Backend rejects a Runtime's registration or poll because its identity or generation has been fenced, that Runtime exits instead of retrying the rejected registration indefinitely. It writes an exact PID/start/runtime fence for the Manager, which records the Backend's active Worker and route generation and does not automatically respawn the rejected runtime. That fence survives a Manager replacement or restart; an explicit cyborgy worker restart remains the manual lifecycle override. Transient transport and server failures continue to use bounded retry behavior.

The Backend release configuration must advertise all of these values before a managed Worker can build a runtime:

• CYBORGY_CLI_LATEST_VERSION
• CYBORGY_CLI_ARTIFACT_URL
• CYBORGY_CLI_ARTIFACT_SHA256
• CYBORGY_CLI_ARTIFACT_INDEX_URL (normally https://pypi.org/simple)
• CYBORGY_CLI_ARTIFACT_FILENAME (optional when the URL has a wheel filename)
• CYBORGY_CLI_ARTIFACT_SOURCE_SHA (dev only: exact source commit for the wheel)

Runtime state and manifests contain identity facts and hashes only. A runtime directory is never overwritten; failed candidates are quarantined and retried at bounded intervals before GC considers unreferenced generations.

Status

This is an alpha package. The public CLI surface is expected to evolve with the Cyborgy service.