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-devandcyborgy-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-workspacebootstrap 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
--rulesand 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_VERSIONCYBORGY_CLI_ARTIFACT_URLCYBORGY_CLI_ARTIFACT_SHA256CYBORGY_CLI_ARTIFACT_INDEX_URL(normallyhttps://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.
1 maintainer
Release files for cyborgy 0.1.213
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cyborgy-0.1.213.tar.gz | 22.6 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cyborgy-0.1.213-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 45.3 MB
Release files / cyborgy-0.1.213.tar.gz
| Download URL | cyborgy-0.1.213.tar.gz |
|---|---|
| Size | 22.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9bdb922dda51001bc85e51d4d965e12aa836adaf0e694570223407cd5de9d53d
|
|
BLAKE2b-256 checksum How to use checksums |
e8f2140fd7609cac0a2374f4db14348f8c07dbd18d8e19b5420171b2e0f0dbea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / cyborgy-0.1.213-py3-none-any.whl
| Download URL | cyborgy-0.1.213-py3-none-any.whl |
|---|---|
| Size | 22.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9472dfd330e41e43d3671ad014723442213c819006c8586e471f418cefa25d6e
|
|
BLAKE2b-256 checksum How to use checksums |
00fc56cfb74c1469ac1ba0415cb9a6270f00ed14eec72382cf3f5321df364efc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
