# Install Uscha

Uscha installs as a machine-level helper for coding agents. The recommended path
is npm/npx because it works the same on a fresh Codex or Claude Code machine.

The method itself — the paradigm, the five rules, the skills and the library — lives at
**[uscha.dev](https://uscha.dev)**.

## Quick path

### Codex Desktop

```bash
npx --yes @andresmassello/uscha@latest version
npx --yes @andresmassello/uscha@latest install --target codex --dry-run
npx --yes @andresmassello/uscha@latest install --target codex
npx --yes @andresmassello/uscha@latest doctor --target codex
```

Then restart Codex or open a new thread. The installer registers Uscha as a
personal local plugin under `~/plugins/uscha` and updates
`~/.agents/plugins/marketplace.json`. It preflights that marketplace before replacing the plugin tree and writes the install marker last.

### Claude Code

```bash
npx --yes @andresmassello/uscha@latest install --target claude --dry-run
npx --yes @andresmassello/uscha@latest install --target claude
npx --yes @andresmassello/uscha@latest doctor --target claude
```

This installs the `uscha-*` skills and registers a portable Python `PreToolUse` hook under `~/.claude` while preserving unrelated `settings.json` entries. Restart or reload Claude Code after installing.

### Same machine uses both

```bash
npx --yes @andresmassello/uscha@latest install --target both --dry-run
npx --yes @andresmassello/uscha@latest install --target both
npx --yes @andresmassello/uscha@latest doctor --target both
```

## Prepare a project repo

After the machine install, initialize each project where Uscha should govern the
workflow:

```bash
npx --yes @andresmassello/uscha@latest init --repo . --dry-run
npx --yes @andresmassello/uscha@latest init --repo .
# Existing differing files are preserved; use --force only to replace them deliberately.
npx --yes @andresmassello/uscha@latest init --repo . --force
```

`init` exits nonzero and reports conflicts for differing `uscha.config.json`, `CLAUDE.md`, `CONSTITUTION.md`, or `.gitattributes`; `--dry-run` performs the same conflict check without writing.

`init` also installs the **progress statusline** (kit 1.46.0): it copies
`.claude/scripts/uscha_{statusline,progress}.py` and merges a `statusLine` + a `Stop` hook into
`.claude/settings.json` (never clobbering an existing `statusLine`). Add a `label`, `roadmap`
and `build_priority` to your `repos[]` entry to drive it; with no data it stays hidden.

Project state stays in the project: `uscha.config.json`, `QA-LEDGER.json`,
`ACCEPTANCE.md`, and approved golden fixtures when used.

## See the dashboard (mirador)

From the root of any project that has a `QA-LEDGER.json`, one command renders the mirador and
opens it — no python, no paths:

```bash
npx --yes @andresmassello/uscha@latest mirador           # one glance: render + open
npx --yes @andresmassello/uscha@latest mirador --watch   # live second-screen view (auto-refresh)
```

It defaults to the `QA-LEDGER.json` convention in the current directory (pass `--ledger` to
point elsewhere) and prints the absolute path it wrote. `--watch` re-renders every `--interval`
seconds (default 30) into one self-reloading tab.

## Requirements

| Requirement | Why |
|-------------|-----|
| Node.js + npm | Runs the universal `npx` entrypoint. |
| Python 3.8+ | Runs the canonical stdlib installer and engine. |
| Git | Used by the method and by project setup checks. |
| Codex Desktop and/or Claude Code | The agent runtime you want to install Uscha into. |

No `pip install` is required. The engine is Python stdlib-only.

## Other install options

| Option | Use when | Tradeoff |
|--------|----------|----------|
| `npx @andresmassello/uscha@latest ...` | Normal install/update on any machine. | Requires npm registry access. |
| Git checkout + `python uscha-kit/install-uscha.py ...` | Developing Uscha itself or testing unreleased changes. | You must clone/pull the repo yourself. |
| `--mode link` from a checkout | This machine develops the kit and installed skills should follow local edits. | Links are great for development, risky for normal users. |
| Claude Code plugin commands | You specifically want Claude Code's native plugin flow. | Codex still needs the npm/git installer path. |
| Manual copy | Debugging the installer. | Easy to drift; not recommended for adoption. |

Development checkout example:

```bash
git clone https://github.com/andresmassello/uscha.git
cd uscha
python uscha-kit/install-uscha.py install --target both --mode link --dry-run
python uscha-kit/install-uscha.py install --target both --mode link
```

Claude Code plugin option:

```text
/plugin marketplace add andresmassello/uscha
/plugin install uscha@uscha
```

## Update and verify

```bash
npm view @andresmassello/uscha version
npx --yes @andresmassello/uscha@latest version
npx --yes @andresmassello/uscha@latest install --target both
npx --yes @andresmassello/uscha@latest doctor --target both
```

`doctor` exits 1 for any unhealthy target in either text or `--json` mode. It checks installed skill presence, manifest/marketplace or hook registration, marker, and version; it does not measure file-content integrity.

`install` (after its transaction commits) and `doctor` (as an advisory section) also report the
extras (ADR-052, kit 2.7.0): how the dev loop's QA tools resolve on the target machine and whether
the optional engram is present, with the commands to add it. engram is present when it is usable
from Claude (the plugin installed and enabled, or an `engram` MCP server in the Claude
configuration); a bare binary on PATH reads "binary found, not wired into Claude". They only
report: nothing is installed, no command is run, and neither exit code changes.

If `npm view` returns `404` immediately after a new release, wait a few minutes:
npm search/dist-tags can propagate before the package metadata endpoint used by
`npx`. Do not republish the same version while propagation is in progress.