unlegacy-cli

Installable CLI for connecting local coding agents to Unlegacy MCP.

Unlegacy generates repository documentation, API references, knowledge graph data, and Vault investigation docs in the platform. This CLI configures external coding agents so they can consume that MCP surface.

Install

Published package:

uv tool install unlegacy-cli

or:

pip install unlegacy-cli

After install, the command is saved on the user's machine as:

unlegacy --help

From a checkout:

pip install .

or:

uv tool install .

One-shot setup without preinstalling:

uv tool run --from unlegacy-cli unlegacy setup --token mcp_live_xxx --endpoint https://app.unlegacy.ai/ai/mcp

Distribution

Build the package artifacts:

uv build

The build creates dist/unlegacy_cli-<version>.tar.gz and dist/unlegacy_cli-<version>-py3-none-any.whl. Publish those artifacts to the Python package index used by Unlegacy clients.

Setup

unlegacy setup

The flow:

1. Shows the Unlegacy logo.
2. Prompts for the MCP token from the Unlegacy frontend.
3. Prompts for the MCP endpoint. Press Enter to use the local app endpoint: http://localhost:5173/ai/mcp.
4. Lets the user select supported clients.
5. Writes or merges MCP config.
6. Installs the packaged Unlegacy and Forge skill bundle.
7. Runs unlegacy doctor.

Non-interactive usage:

UNLEGACY_MCP_TOKEN=mcp_live_xxx \
unlegacy setup --client claude-code --client codex --endpoint https://app.unlegacy.ai/ai/mcp

For local development:

UNLEGACY_MCP_TOKEN=mcp_live_xxx \
unlegacy setup --client claude-code --client codex --endpoint http://localhost:5173/ai/mcp

Supported client values:

• claude-code
• codex
• cursor
• vscode-copilot
• opencode
• all

Commands

unlegacy setup
unlegacy doctor
unlegacy install-skills --client codex
unlegacy status

Bundled skills

unlegacy setup and unlegacy install-skills install one versioned skill bundle:

• unlegacy - repository and Vault knowledge retrieval
• using-forge - Forge modernization routing and design readiness
• preparing-forge-build - complete artifact-only ledger and workspace gate
• executing-forge-build - lifecycle-first, bounded obligation slices and checkpoints
• developing-forge-obligations - behavior-preserving RED-GREEN-REFACTOR
• debugging-forge-build - root-cause-first failure investigation
• reviewing-forge-slices - separate specification and quality reviews
• verifying-forge-build - evidence and obligation reconciliation
• finishing-forge-build - assembled replacement and cutover verification
• using-forge-subagents - preferred fresh-context execution when supported

The bundle is self-contained; installing the external Superpowers plugin is not required. Subagents are strongly encouraged on clients that support them, while the sequential workflow enforces the same gates on every supported client. The methodology is inspired by obra/superpowers; attribution is packaged in assets/skills/NOTICE.md.

Forge builds maintain committed coordination state under .forge/, including a locked manifest, build state, obligation evidence, decisions, and slice reviews. This state is builder-owned local evidence, not independent Forge certification. Preparation cannot edit target files: an integrity-checked validator bundled with the skill reconciles fetched payloads against the authoritative manifest index and requires a stable digest, all-pending state, safe path boundaries, and an artifact-only Git diff from the captured preparation base before execution begins.

The CLI is not used during modernization. Its responsibility ends after it installs/updates the skills, configures MCP, and diagnoses bundle integrity. The coding agent performs modernization with the installed skills, Unlegacy MCP, Git, and the target repository's native toolchain.

unlegacy doctor validates every required skill and supporting executable against the packaged bundle and reports missing, stale, or modified files per client. Reinstall the bundle with unlegacy install-skills when doctor reports an integrity issue.

Vault-aware MCP tools

The packaged unlegacy skill now teaches agents how to use both repo-scoped and Vault-scoped tools.

Repo-scoped tools are still the right starting point for single-repository work:

• list_repos
• repo_brief
• list_docs
• search_docs
• doc_outline
• read_doc
• repo_info
• search
• symbol_context
• impact
• cypher
• get_code

Vault-scoped tools are the right starting point for product, migration, or system questions that cross repository boundaries:

• list_vaults
• vault_brief
• list_vault_repos
• list_vault_docs
• read_vault_doc
• search_vault_docs
• search_repo_kg
• list_needs_input

Typical Vault flow for an installed coding agent:

1. Call list_vaults unless the user gave an exact Vault id.
2. Call vault_brief(vault_id) to load the Vault summary, member repos, generated docs, missing evidence, and Needs Input.
3. Use list_vault_docs and read_vault_doc before drilling into source.
4. Use list_vault_repos to keep follow-up repo reads inside the Vault.
5. Use search_repo_kg for code-graph verification within a Vault member repo.
6. Use list_needs_input before presenting cross-repo conclusions that depend on missing docs, API refs, or KG evidence.

unlegacy doctor also validates that the connected MCP endpoint exposes the required repo and Vault tools.

Development

uv run pytest