Metadata-Version: 2.4
Name: cyborgy
Version: 0.1.34
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.

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 "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. It prefers scriptable account-aware sources such as
`cursor-agent models`, `codex debug models`, and `grok 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.

## 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 enable pip package auto-updates by default. Set the variable to `0`,
`false`, or `off` only when an operator needs to disable them:

```bash
CYBORGY_WORKER_AUTO_UPDATE=0 cyborgy worker start
```

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.
