ziku (軸) — the axis around which things revolve. Your template is the axis; every project builds on it, and improvements flow back to keep it turning.

Why

Templates go stale the moment you scaffold them. Each project improves upon the original — better configs, new workflows, refined settings — but those improvements never flow back.

ziku solves this with bi-directional sync:

• init — Pull the latest template into your project
• push — Push your improvements back to the template
• pull — Sync latest template updates with 3-way merge
• status — See pending pull/push counts and what to do next
• diff — See what's changed
• track — Add file patterns to the sync whitelist

Your template stays alive, fed by every project that uses it.

Getting Started

ziku has two roles: template author (setup) and template user (init). If someone else has already set up the template, skip to Step 2.

Step 1: Create the template (setup) — template author

ziku setup initializes a template repository by creating .ziku/ziku.jsonc. This file defines which file patterns ziku manages.

# In your template repository
npx ziku setup

This creates .ziku/ziku.jsonc with default patterns. Edit it to match your needs:

{
  "$schema": "https://raw.githubusercontent.com/tktcorporation/ziku/main/schema/ziku.json",
  "include": [
    ".claude/settings.json",
    ".claude/rules/*.md",
    ".claude/skills/**",
    ".mcp.json",
    ".devcontainer/**"
  ]
}

You can also set up a remote template repository:

# Create a PR to add .ziku/ziku.jsonc to a remote repo
npx ziku setup --remote --from my-org/my-templates

By default, ziku looks for {your-org}/.ziku, then {your-org}/.github based on your git remote. If the repository doesn't exist, npx ziku will offer to create it interactively.

Step 2: Apply the template (init) — template user

ziku init (or just npx ziku) downloads the template and lets you select which directories to sync.

# Auto-detect template from git remote
npx ziku

# Use a specific template
npx ziku --from my-org/my-templates

# Use a local directory as template (no GitHub needed)
npx ziku --from-dir ../my-template

ziku copies the matching files into your project and creates:

• .ziku/ziku.jsonc — selected sync patterns (same format as the template)
• .ziku/lock.json — template source + sync state (hashes, refs)

Step 3: Keep it in sync

# Push local improvements back to the template
npx ziku push -m "Add new workflow"

# Pull latest template updates (includes new patterns)
npx ziku pull

# Check what's different
npx ziku diff

# Add file patterns to the sync whitelist
npx ziku track '.eslintrc.*'

push works with both GitHub (creates a PR) and local templates (copies files directly). pull also syncs new patterns added to the template's ziku.jsonc.

How it Works

graph TB

  subgraph Template["Template Repository"]
    ZIKU_TPL[".ziku/ziku.jsonc"]
    T_FILES["synced files"]
  end

  subgraph User["User Project"]
    ZIKU[".ziku/ziku.jsonc"]
    LOCK[".ziku/lock.json"]
    U_FILES["synced files"]
  end

  setup([setup]) -->|create| ZIKU_TPL
  init([init]) -->|read| ZIKU_TPL
  init -->|create| ZIKU & LOCK & U_FILES
  push([push]) -->|read| ZIKU & LOCK
  push -->|update| T_FILES
  pull([pull]) -->|read| ZIKU & LOCK
  pull -->|update| U_FILES & ZIKU & LOCK
  diff([diff]) -.->|read| ZIKU & LOCK & U_FILES
  status([status]) -.->|read| ZIKU & LOCK & U_FILES
  track([track]) -.->|update| ZIKU

For detailed file operations per command, see File Lifecycle.

The config file

Both the template and user project share the same .ziku/ziku.jsonc format — just include and exclude patterns:

{
  "include": [
    ".claude/rules/*.md",
    ".mcp.json",
    ".github/workflows/**"
  ]
}

Command overview

| Command | Who runs it | What it does | |---|---|---| | setup | Template author | Initialize a template repository | | init (user project) | Template user | Initialize user project from template | | pull | Template user | Pull latest template updates to local project | | push | Template user | Push local changes to template (GitHub: PR / local: direct copy) | | diff | Template user | Show differences between local and template | | status | Template user | Show pending pull/push counts and recommend next action | | track | Template user | Add file patterns to the sync whitelist |

Template source info (owner/repo or local path) is stored in .ziku/lock.json, separate from patterns. When you pull, new patterns added to the template's .ziku/ziku.jsonc are automatically merged into yours.

For detailed file operations per command, see File Lifecycle.

Commands

setup

Initialize a template repository with .ziku/ziku.jsonc

Initialize a template repository with .ziku/ziku.jsonc (setup vdev)

USAGE setup [OPTIONS] [DIR]

ARGUMENTS

  DIR    Template repository directory (Default: .)

OPTIONS

       --remote    Create a PR to set up a remote template repository instead of local (Default: false)
  --from=<from>    Remote template repository as owner/repo (used with --remote)

init

Apply dev environment template to your project

Apply dev environment template to your project (ziku vdev)

USAGE ziku [OPTIONS] [DIR]

ARGUMENTS

  DIR    Target directory (Default: .)

OPTIONS

                                        --force    Overwrite existing files (Default: false)
                                      -y, --yes    Non-interactive mode (accept all defaults) (Default: false)
                              -d, --dirs=<dirs>    Comma-separated directory names to apply (non-interactive)
  -s, --overwrite-strategy=<overwrite_strategy>    Overwrite strategy: overwrite, skip, or prompt
                                  --from=<from>    Template source as owner/repo (e.g., my-org/my-templates)
                          --from-dir=<from_dir>    Local directory to use as template source (skips GitHub download)

push

Push local changes to the template (PR for GitHub, direct copy for local)

Push local changes to the template (PR for GitHub, direct copy for local) (push)

USAGE push [OPTIONS] [DIR]

ARGUMENTS

  DIR    Project directory (Default: .)

OPTIONS

             -n, --dryRun    Preview only, don't push (Default: false)
  -m, --message=<message>    PR title (GitHub only)
            -y, -f, --yes    Skip confirmation prompts (Default: false)
                   --edit    Edit PR title and description before creating (GitHub only) (Default: false)
          --files=<files>    Comma-separated file paths to include (skips file selection prompt)
       --includeDeletions    Include locally deleted files (default: unselected in interactive mode) (Default: false)

pull

Pull latest template updates

Pull latest template updates (pull)

USAGE pull [OPTIONS] [DIR]

ARGUMENTS

  DIR    Project directory (Default: .)

OPTIONS

  -f, --force    Skip confirmations (Default: false)
   --continue    Continue after resolving merge conflicts (Default: false)

diff

Show differences between local and template

Show differences between local and template (diff)

USAGE diff [OPTIONS] [DIR]

ARGUMENTS

  DIR    Project directory (Default: .)

OPTIONS

  -v, --verbose    Show detailed diff (Default: false)

status

Show pending pull/push counts and recommend next action

Show pending pull/push counts and recommend next action (status)

USAGE status [OPTIONS] [DIR]

ARGUMENTS

  DIR    Project directory (Default: .)

track

Add file patterns to the tracking whitelist in ziku.jsonc

Add file patterns to the tracking whitelist in ziku.jsonc (track)

USAGE track [OPTIONS] [PATTERNS]

ARGUMENTS

  PATTERNS    File paths or glob patterns to track (e.g., .cloud/rules/*.md)

OPTIONS

  -d, --dir=<dir>    Project directory (default: current directory) (Default: .)
       -l, --list    List all currently tracked patterns (Default: false)

What You Get

The files you get depend on the patterns configured in your template's .ziku/ziku.jsonc. After running ziku init, your selected patterns are saved in your own .ziku/ziku.jsonc — you can customize them anytime with ziku track.

ziku also creates:

• .ziku/ziku.jsonc — Your sync patterns (which files to include/exclude)
• .ziku/lock.json — Sync state + template source (hashes, base refs, source info)

Contributing

See CONTRIBUTING.md.

License

MIT License © tktcorporation