Metadata-Version: 2.4
Name: cyborgy
Version: 0.1.28
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>=1.2
Requires-Dist: pynacl>=1.5
Requires-Dist: PyYAML>=6.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: websocket-client>=1.8; extra == "dev"

# Cyborgy CLI

`cyborgy` extends coding-agent CLIs such as Claude Code and Codex 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.

## Install

```bash
pip install cyborgy
```

For local Cyborgy development tooling:

```bash
pip install "cyborgy[dev]"
```

## 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"
```

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. By default it first opens a short-lived PTY and parses each tool's
interactive `/model` selector, because some tools only expose account-specific
choices there. Scriptable sources such as `cursor-agent models`,
`codex debug models`, and documented fallback aliases are used only when the
interactive selector cannot be parsed.

```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 by default and parses the
visible `/model` selector. Worker registration uses the same bounded probe so
the web model picker stays aligned with what the local tool can actually show.
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.

## Worker auto-update

`cyborgy worker start` is the launcher form: it starts or verifies one
background worker for the current profile, worker name, and repository root,
then exits 0. A second `cyborgy worker start` for the same context is a no-op
when that worker PID is still alive; stale pid records are replaced safely.

`cyborgy worker` and `cyborgy worker run` remain the foreground form for
supervised shells and debugging.

`cyborgy worker stop` stops only the managed background worker recorded by
`cyborgy worker start` for the same profile, worker name, and repository root.
It does not stop foreground `worker run` processes or search by process name;
stale or unverified PID records are cleared/refused without sending a signal.
`cyborgy worker restart` uses the same managed-worker safety checks, then starts
the worker again for that context.

Workers can opt into pip package auto-updates:

```bash
CYBORGY_WORKER_AUTO_UPDATE=1 cyborgy worker start
```

When enabled, the worker periodically asks the Cyborgy backend for the latest
`cyborgy` package version. If a newer version exists, it runs `python -m pip install
--upgrade cyborgy` in a waited subprocess. The Python is resolved from
`CYBORGY_WORKER_PYTHON`, the configured/current `cyborgy` executable's shebang,
the active pyenv Python when the executable is a pyenv shim, or the current
`PATH` before falling back to `sys.executable`. After a
successful install, the worker stops polling for new commands, lets any current
agent subprocess finish, and re-execs itself at the next idle boundary through
`CYBORGY_WORKER_EXECUTABLE` or the current `PATH`'s `cyborgy` wrapper. It does
not broad-kill processes or interrupt running agent commands.

To keep a development-extra install on the same release track, start the worker
with `CYBORGY_WORKER_AUTO_UPDATE_PACKAGE=cyborgy[dev]`. Version checks still use
the `cyborgy` distribution reported by the Cyborgy backend, while pip upgrades the configured package
spec (`cyborgy` by default, or `cyborgy[dev]` when requested).

Optional knobs:

- `CYBORGY_WORKER_AUTO_UPDATE_INTERVAL`: seconds between checks, default 300 (5 minutes), minimum 60.
- `CYBORGY_WORKER_AUTO_UPDATE_INITIAL_DELAY`: seconds before the first check.
- `CYBORGY_WORKER_AUTO_UPDATE_TIMEOUT`: seconds before the pip install attempt times out.
- `CYBORGY_WORKER_AUTO_UPDATE_PACKAGE`: pip package spec, default `cyborgy`.
- `CYBORGY_WORKER_AUTO_UPDATE_INDEX_URL`: pip index URL for installation.
- `CYBORGY_WORKER_EXECUTABLE`: explicit `cyborgy` wrapper to use for worker re-exec.
- `CYBORGY_WORKER_PYTHON`: explicit Python interpreter to use for auto-update installs.

## Status

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