@alessandroraffa/tangyr

CLI for the Tangyr discipline — install and manage operating kits for AI coding tools.

An operating kit is a self-contained package of agents, skills, commands, rules, and templates that implements the Tangyr discipline for a specific AI coding context. The CLI places kit artifacts into the environments consumed by supported tools.

Install / run

npx @alessandroraffa/tangyr <command>

Or install globally:

npm install -g @alessandroraffa/tangyr
tangyr <command>

Commands

Kit management

| Command | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------- | | tangyr install --kit <name> | Install a kit resolved from configured search paths (kitSearchPaths/kit in tangyr.config.yaml) | | tangyr install --kit-path <path> | Install a kit from an explicit kit root path | | tangyr uninstall | Remove Tangyr from the target scope | | tangyr sync | Synchronize installed kit to the latest version | | tangyr verify | Check installation integrity against the manifest | | tangyr cleanup | Remove managed artifacts; delegates to uninstall if manifest exists | | tangyr assess | Pre-installation conflict analysis | | tangyr list | Display kits discovered in configured search paths and any installed manifests |

Environment

| Command | Description | | --------------- | -------------------------------------------------- | | tangyr detect | Detect supported AI tool runtimes | | tangyr status | Show managed artifact status per tool | | tangyr doctor | Run environment diagnostics with optional auto-fix | | tangyr probe | Probe configured platform paths |

Configuration

| Command | Description | | ----------------- | ----------------------------------------------------- | | tangyr init | Create a tangyr.config.yaml interactively | | tangyr config | Display or edit Tangyr configuration | | tangyr validate | Validate the kit against kitFormat 1 conformity rules |

Global flags

| Flag | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------------- | | --config <path> | Use an explicit configuration file | | --kit-path <path> | Use an explicit operating kit root | | --dry-run | Report actions without modifying files | | --yes | Skip confirmation prompts | | --verbose | Detailed output | | --quiet | Errors only | | --no-color | Disable colors | | --claude-config-dir <path> | Claude Code global root directory (repeatable). Overrides claudeCodeGlobalPaths in the config file. |

Supported tools

• Claude Code — artifacts placed in scope-resolved Claude Code paths
• GitHub Copilot — agents and commands compiled to VS Code user directories
• OpenAI Codex — AGENTS.md, agent TOML files, rules, hooks, and MCP compiled to Codex paths
• OpenCode — instructions, agents, commands, skills, and MCP placed in XDG config paths
• Cursor — instructions, subagents, rules, commands, skills, hooks, and MCP
• Cline — instructions, rules, workflows, skills, and MCP

Quick start

# Initialize a configuration in your project
npx @alessandroraffa/tangyr init

# Install a kit by path (preview with --dry-run first)
npx @alessandroraffa/tangyr install --kit-path ./path/to/operating-kit --dry-run
npx @alessandroraffa/tangyr install --kit-path ./path/to/operating-kit

# Check installation status, then sync after a kit update
npx @alessandroraffa/tangyr status
npx @alessandroraffa/tangyr sync

Scope

Every write command accepts --scope global or --scope project. The CLI flag overrides config.scope for that invocation.

| Scope | Manifest location | Claude Code artifacts | | --------- | ------------------------- | ----------------------------------- | | global | ~/.tangyr/manifest.json | ~/.claude/ | | project | .tangyr/manifest.json | repo root (AGENTS.md, .claude/) |

Multiple Claude Code global roots

If you maintain more than one Claude Code account (e.g. ~/.claude and ~/.claude-work), you can keep them identical with a single sync operation.

Via config (tangyr.config.yaml):

claudeCodeGlobalPaths:
  - ~/.claude
  - ~/.claude-work

Via environment variable (TANGYR_CLAUDE_CONFIG_DIRS):

A colon-separated list of Claude Code global root directories. Entries support ~/ expansion. This layer is designed for machine-specific configuration that must not be committed to a shared kit config.

export TANGYR_CLAUDE_CONFIG_DIRS="~/.claude:~/.claude-work"
tangyr sync

Auto-sync use case: if a kit-change hook or automation runs tangyr sync, exporting TANGYR_CLAUDE_CONFIG_DIRS in the shell environment keeps multiple Claude configs in sync automatically — without putting machine-specific paths in a shared tangyr.config.yaml.

Via CLI flag (repeatable):

tangyr sync --claude-config-dir ~/.claude --claude-config-dir ~/.claude-work

Precedence: --claude-config-dir flag > TANGYR_CLAUDE_CONFIG_DIRS env > claudeCodeGlobalPaths in config > default ~/.claude.

Per-root artifacts (instructions, agents, skills, commands, rules, output-styles, hooks settings) are written under each root. Shared artifacts (~/.claude.json for MCP, ~/.agents/hooks for hooks) are resolved from the platform default and written once regardless of how many roots are configured.

The manifest records the full set of roots written so that verify and uninstall operate on all of them.