Metadata-Version: 2.4
Name: cyborgy
Version: 0.1.174
Summary: Extend coding-agent CLIs with skills, memory, and extension APIs via the Cyborgy MCP.
Author: Kizuna Intelligence
Project-URL: Homepage, https://github.com/kizuna-intelligence/cyborgy
Project-URL: Repository, https://github.com/kizuna-intelligence/cyborgy
Keywords: cyborgy,codex,claude,devin,grok,mcp,skills,agents
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.2
Requires-Dist: pynacl>=1.5
Requires-Dist: PyYAML>=6.0
Requires-Dist: segno<2,>=1.6
Requires-Dist: tomli>=2.0; python_version < "3.11"

# 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

```bash
pip install cyborgy
```

For local Cyborgy development tooling:

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

## Basic usage

```bash
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:

```text
${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:

```bash
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.

```bash
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.
