KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #react #mcp #rust

ccsk-cli

★ 61 Open GitHub ↗

Claude Code Starter Kit CLI — scaffold Claude-ready projects

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# @ccsk/cli

**Install a complete Claude Code kit — and pick the version — in one command.**

`ccsk init`

[![npm version](https://img.shields.io/npm/v/@ccsk/cli.svg?color=D97757)](https://www.npmjs.com/package/@ccsk/cli)
[![downloads](https://img.shields.io/npm/dm/@ccsk/cli.svg?color=3F9B6B)](https://www.npmjs.com/package/@ccsk/cli)
[![node](https://img.shields.io/node/v/@ccsk/cli.svg)](https://nodejs.org)
[![license](https://img.shields.io/npm/l/@ccsk/cli.svg?color=1A1A1A)](https://raw.githubusercontent.com/ccsk-org/ccsk-cli/main/)
[![platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-6B7280.svg)](https://raw.githubusercontent.com/ccsk-org/ccsk-cli/main/)

> Stop hand-rolling `CLAUDE.md`, agents, rules, and docs for every repo. `ccsk init` installs the [**ccsk-kit**](https://github.com/ccsk-org/ccsk-kit) Claude Code harness as a **plugin** and materializes its contract into your project — with a **version picker** so you choose the stable kit or opt into a beta.

</div>

---

## Highlights

- 🚀 **One command to productive** — `ccsk init` and your repo is Claude-ready.
- 🎚️ **Pick your kit version** — an interactive picker lists available versions; stable by default, prereleases opt-in (`--pre` / `--version`). Discover with `ccsk versions`.
- 🧩 **Plugin + materialized contract** — installs the `ccsk@ccsk-kit` Claude Code plugin (the `/ccsk:` commands, agents, skills) and copies `CLAUDE.md`, `.claude/rules`, `docs/`, and `.ccsk/` into your project.
- 📦 **Fetches & caches** — shallow-clones the kit and caches it at `~/.ccsk/kit/<version>` for fast re-installs.
- 🔐 **Auth-aware** — detects SSH / `gh` CLI and guides you if access is missing (the kit repo is private).
- 🛟 **Non-destructive re-init** — never silently overwrites: an existing file is backed up to `.bak` (or kept, with the ccsk copy written alongside as `.ccsk.bak`). Your `.ccsk/` memory is always preserved; `uninstall` keeps it by default (and backs it up before any purge).
- 🎨 **Optional extras** — tool setup (gh · RTK · context-mode · Serena MCP), ADD methodology, and design references — all skippable.
- 💻 **Cross-platform & CI-friendly** — macOS / Linux / Windows; `-y` for non-interactive runs.

---

## Quick start

> A global CLI tool, not a project dependency. Requires **Node ≥ 20**.

```bash
npm i -g @ccsk/cli
# or: pnpm add -g @ccsk/cli · yarn global add @ccsk/cli · bun add -g @ccsk/cli

ccsk auth          # verify GitHub access (kit repo is private)
ccsk versions      # see available kit versions (stable + beta)
ccsk init          # install — pick a version when prompted
claude             # open Claude Code
/ccsk:plan <goal>  # start the Build Cadence (v2 kit)
```

---

## How it works

`ccsk init` is auth-aware, cached, and **non-destructive** — it never silently overwrites a file you've edited (it asks how to handle conflicts and always keeps a copy — see [Safe re-init & backups](#safe-re-init--backups)), **preserves your `.ccsk/` memory**, and never touches your code. It also writes a fenced block to your `.gitignore` (AI artifacts ignored by default) and installs a Claude Code plugin.

Two things land — the **plugin** provides the `/ccsk:` commands, agents, and skills; the **contract** (`CLAUDE.md`, `.claude/rules`, `docs/`, `.ccsk/`) is materialized into your project (a plugin can't own project-root files):

See the [**ccsk-kit**](https://github.com/ccsk-org/ccsk-kit) repo for the Build Cadence (`Frame → Forge → Prove → Sign-off`) and the full method.

---

## Safe re-init & backups

Re-running `ccsk init` in an existing project is safe: it **never silently overwrites** a file you've touched. When kit files already exist, you get a **three-way choice** — applied to every conflicting file — and the install always proceeds (it never aborts midway):

- **Overwrite** — your existing file is backed up to `<name>.<ext>.bak`, then the ccsk version is written in its place. Your edits stay recoverable.
- **Keep mine** — your file is left untouched and the ccsk version is written alongside as `<name>.<ext>.ccsk.bak`, so you can diff or merge on your own terms.
- **Cancel** — abort the install (the escape hatch); your project is left exactly as-is.

Non-interactive runs (`--yes`, `--force`, or CI) default to the safe **Overwrite-with-backup** behavior — a file is never destroyed without a `.bak` copy first. Your `.ccsk/` memory (plans, journals, ADRs, retros, milestones) is **always preserved** — never overwritten, never backed up away.

---

## Kit versions & channels

The CLI is version-aware: **stable by default, prereleases opt-in.** A plain `ccsk init` (or `--yes`/CI) installs the latest **stable** kit; you reach a beta only via the interactive picker, `--pre`, or an exact `--version`.

```bash
ccsk versions                       # list available (remote) + cached + current
ccsk versions --all --pre           # include every prerelease
ccsk init                           # interactive: pick a version (default = latest stable)
ccsk init --pre                     # newest prerelease (e.g. the v2 beta)
ccsk init --version 2.0.0-beta-01   # an exact version (a leading v is fine too)
```

> **Heads-up (current state):** the v2 kit (`/ccsk:` colon commands) ships as the prerelease **`2.0.0-beta-01`**; the latest **stable** is **v1.1.0** (older `/ccsk-plan` hyphen commands). So a default `ccsk init` installs v1.1.0 — use `--pre` / `--version 2.0.0-beta-01` / the picker to get v2. A bare `ccsk update` never auto-downgrades: if you're on a newer beta it stays put.

---

## Command reference

| Command | What it does | Key flags |
|---|---|---|
| `ccsk init [path]` | Install the kit (picker + plugin + materialize) | `--version <v>` · `--pre` · `--force` · `--no-plugin` · `--plugin-scope <project\|user>` · `--no-setup` · `--no-add` · `-y, --yes` |
| `ccsk versions` | List available + cached + current kit versions | `--all` · `--pre` · `--json` |
| `ccsk auth` | Check GitHub auth (kit repo is private) | — |
| `ccsk update [version]` | Update **CLI + kit templates + plugin** together | `--path <dir>` · `--force` · `--kit-version <v>` · `--pre` · `--plugin-scope <…>` · `--no-templates` · `--no-plugin` |
| `ccsk cache` | Manage cached kit versions (annotates current/(beta)/cached) | `-l, --list` · `--version <v>` · `--clear` · `--clear-all` |
| `ccsk uninstall [path]` | Remove the kit (preserves memory by default) | `--purge-memory` (backs up to `.ccsk.bak-<ts>/` first) · `-y, --yes` |
| `ccsk doctor` | Diagnose Node / git / auth / cache | — |
| `ccsk design [path]` | Add a `DESIGN.md` reference (70+ design systems) | — |
| `ccsk donate` | Support the maintainer via VietQR | — |

Global: `-h, --help` · `-v, --version`. Env: `CCSK_DEBUG=1` (stack traces) · `CI=1` (disable prompts).

```bash
ccsk init --version 1.2.0 --no-add -y   # pin a kit version, skip ADD, non-interactive
ccsk init --pre                          # opt into the newest prerelease kit
ccsk update --no-plugin                  # refresh CLI + templates, leave the plugin
ccsk uninstall --purge-memory            # remove everything (memory backed up first)
```

`update` is a three-layer, non-aborting operation: it self-updates the CLI, re-materializes the kit templates (preserving your memory), and runs `claude plugin update ccsk` — all pinned to one resolved version so the plugin and templates never drift. The **CLI self-update always runs**, but the kit layers (templates + plugin) are materialized **only in an existing ccsk project** (a dir with `.ccsk/` or materialized `.claude/skills/ccsk-*`) — so running `ccsk update` in an unrelated directory won't scatter kit files there. To install into a fresh dir anyway, name it with `--path <dir>` or pass `--force`.

---

## Tool setup

`ccsk init` offers an optional setup pass (skip with `--no-setup`) that wires, idempotently and without aborting on failure:

- **`gh` CLI** — installed if missing (for GitHub auth to the private kit repo).
- **RTK-AI** — installs `rtk` and runs `rtk init` to enable its Claude Code hook.
- **context-mode** — registers the `context-mode` MCP server (+ prints the manual plugin steps).
- **Serena** — registers the Serena MCP server (skipped if `uv`/`uvx` is absent).

The `ccsk` plugin itself is installed by `init` (skip with `--no-plugin`); if the `claude` CLI isn't found, init prints a hint and you can re-run later.

---

## Works with ADD

[**ADD (AI-Driven Development)**](https://github.com/pilotspace/ADD) is a methodology where AI writes the code while humans own direction and verification — **Specify → Scenarios → Contract → Tests → Build → Verify**. `ccsk init` can install it (`npx @pilotspace/add`; skip with `--no-add`):

- **ccsk** scaffolds Claude Code's plugin (commands/agents/skills) + rules, docs, and `.ccsk/` memory.
- **ADD** adds the specification-first, test-driven loop on top.

---

## Privacy

- `init` writes a fenced block to your project `.gitignore` that ignores AI artifacts (`.ccsk/`, loop logs, …) by default, with commented opt-in lines to commit the contract/memory for team sharing.
- `init` records the installed version locally (`~/.ccsk/install.json`) and sends **optional**, fire-and-forget install telemetry (GitHub username + an email you may decline). No code is ever read or uploaded.

---

## Troubleshooting

| Issue | Fix |
| --- | --- |
| `command not found: ccsk` | Add your global bin to PATH. npm: `$(npm prefix -g)/bin`. bun: `~/.bun/bin`. |
| `Permission denied (publickey)` / `GitHub authentication required` | Run `ccsk auth` and follow the steps (SSH keys, or `gh auth login`). |
| Plugin step skipped | The `claude` CLI wasn't found — install Claude Code, then re-run `ccsk init`. |
| `No stable kit release yet` in CI | A non-interactive run won't auto-pick a prerelease — pass `--version <v>` or `--pre`. |
| Spinner shows raw text | Expected in CI or when piped — animations degrade gracefully. |
| Something else is off | Run `ccsk doctor`, or `CCSK_DEBUG=1 ccsk <cmd>` for stack traces. |

---

## Contributing

Contributions welcome — open an issue first for anything beyond small fixes.

- **Conventional commits**: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
- **Cross-platform**: test on macOS / Linux / Windows when possible.
- **Keep it tight**: no new global tooling without discussion.

See [docs/architecture.md](./docs/architecture.md) for module-level details and [RELEASING.md](./RELEASING.md) for the release flow.

---

## Support the project

```bash
ccsk donate    # buy the maintainer a coffee via VietQR
```

---

## Links & license

- Kit → [**ccsk-kit**](https://github.com/ccsk-org/ccsk-kit) · Issues → [ccsk-cli/issues](https://github.com/ccsk-org/ccsk-cli/issues) · Discussions → [ccsk-cli/discussions](https://github.com/ccsk-org/ccsk-cli/discussions)
- License → **MIT** (see [LICENSE](./LICENSE))

ccsk-cli

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README