Quick Start

# Clone and set up
git clone https://github.com/ndizazzo/saddle-cli.git ~/dev/ai
cd ~/dev/ai && pnpm install

# Launch the interactive installer
npx saddle-cli

# Or run non-interactively
npx saddle-cli --yes --all        # apply everything
npx saddle-cli --dry-run --all    # preview first
npx saddle-cli --check            # verify sync
npx saddle-cli --uninstall        # clean removal

The interactive TUI detects which AI tools are installed and walks you through linking skills, agents, commands, and config files for each.

What Gets Synced

| Tool | Home | Skills | Agents | Commands | Root File | Config Files | |------|------|:------:|:------:|:--------:|:---------:|:------------:| | Claude Code | ~/.claude | ✓ | ✓ | ✓ | — | — | | Codex | ~/.codex | ✓ | ✓ | ✓ | AGENTS.md | — | | Copilot | ~/.copilot | ✓ | ✓ | ✓ | — | — | | Cursor | ~/.cursor | ✓ | ✓ | ✓ | — | — | | Gemini | ~/.gemini | ✓ | ✓ | ✓ | GEMINI.md | configurations/gemini/ → ~/.gemini/ | | OpenCode | ~/.config/opencode | ✓ | ✓ | ✓ | AGENTS.md | opencode/ → ~/.config/opencode/ |

Features

Interactive TUI — A beautiful terminal interface built with Ink. Browse tools, preview diffs, toggle individual actions — all from your terminal.

Headless-ready — Full non-interactive mode for CI/CD. --dry-run, --yes, --all, --check — automate everything.

Smart Symlinks — Creates relative symlinks, detects existing content, shows diffs before replacing, and backs up what was there.

Lockfile Tracking — Know exactly what Saddle installed. Verify sync status with --check. Safely uninstall with --uninstall.

YAML Rules — Declarative per-tool rules define what gets linked where. Add new tools by writing a single YAML file.

Zero Config — Detects installed tools automatically. Grays out what's missing. Just run saddle and go.

How It Works

1. Define — Keep agents, skills, commands, and configs in one canonical repo.

2. Detect — Saddle finds which AI tools are installed on your machine.

3. Link — Symlinks wire each tool to your canonical definitions. Done.

Canonical Layout

saddle/
├── agents/              # Per-tool instruction files and shared agent definitions
│   ├── codex/AGENTS.md
│   ├── gemini/GEMINI.md
│   └── opencode/AGENTS.md
├── commands/            # Slash command files → each tool's commands/
├── skills/              # Skill subdirectories → each tool's skills/
├── configurations/
│   └── gemini/          # Gemini-specific config → ~/.gemini/
├── opencode/            # OpenCode-specific config → ~/.config/opencode/
├── rules/               # Per-tool installer rules (YAML)
│   ├── claude.yaml
│   ├── codex.yaml
│   ├── copilot.yaml
│   ├── cursor.yaml
│   ├── gemini.yaml
│   └── opencode.yaml
└── scripts/             # Repo maintenance helpers

Keep the real files in this repo and rebuild tool-specific links on each machine. Do not sync ~/.claude, ~/.codex, ~/.cursor, ~/.gemini, ~/.copilot, or ~/.config/opencode symlinks directly between machines.

CLI Reference

saddle [options]

| Flag | Description | |------|-------------| | --dry-run | Preview changes without writing to disk | | --yes | Auto-confirm replacements without prompting | | --all | Select every available profile | | --profile id1,id2 | Apply specific profile IDs by name | | --list | Print available profiles and exit | | --check | Verify installed symlinks are in sync (exit 0 clean, 1 drift) | | --uninstall | Remove symlinks recorded in lockfile | | --verbose | Show extra detail (source paths, resolved targets) | | --quiet | Suppress ok/link/skip/mkdir output; errors and summary only |

Interactive Mode

The TUI is built with Ink and @inkjs/ui. It presents selectable profiles grouped by tool, with per-action toggling and diff previews.

Profiles for tools not detected on the system are shown grayed out with a "NOT INSTALLED" badge and cannot be selected.

Non-Interactive Mode

When piped or used with --yes, Saddle falls back to a plain-text installer. Ideal for CI/CD pipelines and headless environments.

# Preview all changes
npx saddle-cli --dry-run --all

# Apply everything, no prompts
npx saddle-cli --yes --all

# Apply specific profiles
npx saddle-cli --profile claude-skills-skills,cursor-directory-agents --yes

Configuration

| Variable | Default | Description | |----------|---------|-------------| | SADDLE_DIR | ~/.config/saddle | Base config directory | | SADDLE_CONFIG | ~/.config/saddle/config.yaml | Path to config file | | SADDLE_RULES_DIR | ~/.config/saddle/rules | Path to rules directory |

CLI Documentation Reference

Links to official documentation for each supported AI coding tool.

• CLI Reference — commands and flags
• Interactive Mode — slash commands and shortcuts
• Skills — custom slash commands via SKILL.md
• Subagents — agent delegation
• Agent Teams — multi-agent collaboration
• Settings — settings.json reference
• Memory / CLAUDE.md — project instructions
• Hooks — lifecycle event hooks
• MCP — MCP server integration
• Plugins — plugin system

• CLI Overview — getting started with the CLI
• Using Agent in CLI — interactive agent usage
• Parameters Reference — all CLI flags
• Slash Commands — in-session commands
• Agent Modes — plan, ask, and agent modes
• Rules — .cursor/rules/ configuration
• Skills — multi-step workflow files
• MCP in CLI — MCP server management
• Headless / CI — non-interactive scripting

• CLI Reference — all subcommands and flags
• CLI Features — feature overview
• Slash Commands — in-session TUI commands
• Config Basics — config.toml setup
• Config Reference — all config keys
• AGENTS.md Guide — agent instruction files
• Rules — rule system
• Skills — skill system
• MCP Integration — MCP server setup
• Non-interactive Mode — codex exec for CI/CD

• CLI Cheatsheet — launch flags and model flags
• Interactive Commands — slash, at, and shell commands
• Configuration Reference — settings.json schema
• GEMINI.md Context Files — agent memory and instructions
• Custom Commands — .toml custom slash commands
• Skills — agent skills system
• MCP Server Integration — MCP setup
• Plan Mode — read-only planning
• Headless / Non-interactive — CI/automation usage

• CLI Reference — all commands and flags
• Config Reference — opencode.json setup
• Agents — agent definitions and built-in agents
• Skills — SKILL.md skill system
• Custom Commands — slash command files
• Rules / AGENTS.md — project instruction files
• MCP Servers — MCP integration
• Providers — model provider configuration
• Plugins — plugin system
• TUI Usage — terminal UI reference

Validation

pnpm install
pnpm run lint:agents

The same validator runs from the Husky pre-commit hook.

Built With

• Ink — React for CLIs
• @inkjs/ui — Terminal UI components
• React — Component framework
• yaml — YAML parser

MIT License · Made by ndizazzo