cyborgy 0.1.37

Extend coding-agent CLIs with skills, memory, and extension APIs via the Cyborgy MCP.

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

pip install cyborgy

For local Cyborgy development tooling:

pip install "cyborgy[dev]"

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"

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, and grok 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 BigQuery, 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.

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:

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.