npm package: @jedimemo/ccproject
Description: Claude Code project metadata tool for managing agent files, slash commands, and more
Author: jedimemo
Latest version: 0.1.0

# ccproject

A TypeScript/Node.js CLI tool for managing Claude Code project metadata including agent files and slash commands.

## Features

- 🚀 **Interactive-first design** - Run commands without arguments for guided workflows
- 🔍 **Smart search** - Find and install items by name, description, or tags
- 📦 **Batch operations** - Install multiple items at once with quick-add mode
- 🔄 **Update detection** - Track changes and know when updates are available
- 🔗 **GitHub shortcuts** - Use `github:user/repo` instead of full URLs
- 📝 **Modification tracking** - Detect local changes and manage updates safely
- 🔼 **Upstream contributions** - Push changes back via pull requests
- ✨ **Auto-discovery** - Works with or without manifest files

## Installation

```bash
# Install globally
npm install -g @jedimemo/ccproject

# Or use directly with npx
npx @jedimemo/ccproject init github:awesome/claude-tools
```

## Quick Start

### 1. Initialize with a metadata repository:
```bash
# Using GitHub shorthand (recommended)
ccproject init github:awesome/claude-tools

# Using full URL
ccproject init https://github.com/awesome/claude-tools

# Interactive mode - prompts for repository
ccproject init
```

### 2. Browse and search for items:
```bash
# List all available items
ccproject list

# Search for items
ccproject list git              # Search for "git" in names/descriptions
ccproject list -t command       # Filter by type
ccproject list --install        # Search with interactive install
```

### 3. Install items - multiple ways:
```bash
# Interactive mode (recommended for new users)
ccproject add                   # Browse and select items interactively

# Quick-add for batch installation
ccproject quick-add             # Browse by category, install multiple items
ccproject qa                    # Short alias

# Direct installation (when you know what you want)
ccproject add command review-branch
ccproject add agent code-analyzer

# Search and install
ccproject add --search git      # Search for "git" and select from results
```

### 4. Check status and updates:
```bash
ccproject status                # See what's installed and check for updates
ccproject st -v                 # Verbose output with details
```

### 5. Update items:
```bash
# Interactive update (recommended)
ccproject update                # Shows available updates, select which to install

# Update everything
ccproject update --all

# Update specific item
ccproject update command review-branch
```

## Commands

### Main Commands

#### `init [repository-url]` - Initialize ccproject
- Supports GitHub shorthand: `github:user/repo` or `gh:user/repo`
- Options:
  - `-b, --branch <branch>` - Use specific branch
  - `-f, --force` - Overwrite existing configuration

#### `list [search]` (alias: `ls`) - List or search metadata items
- Without arguments: lists all items
- With search term: filters items by name, description, or tags
- Options:
  - `-t, --type <type>` - Filter by type (command/agent)
  - `-i, --installed` - Show only installed items
  - `-a, --available` - Show only available items
  - `-d, --detailed` - Show detailed information
  - `--install` - Interactive mode to install items

#### `add [type] [name]` (alias: `install`) - Add metadata items
- Without arguments: interactive mode with search and multi-select
- Options:
  - `-f, --force` - Force reinstall
  - `-y, --yes` - Skip confirmation prompts
  - `-s, --search <query>` - Search for items by name or description

#### `quick-add` (alias: `qa`) - Batch installation mode
- Browse items by category
- Multi-select interface
- Options:
  - `-t, --tags <tags>` - Filter by tags (comma-separated)
  - `-c, --category <category>` - Filter by category

#### `remove <type> <name>` (alias: `rm`) - Remove metadata items
- Options:
  - `-k, --keep-files` - Keep files but remove from tracking
  - `-y, --yes` - Skip confirmation

#### `status` (alias: `st`) - Show installation status and check for updates
- Shows installed items, modifications, and available updates
- Options:
  - `-v, --verbose` - Show detailed information

#### `update [type] [name]` - Update installed items
- Without arguments: interactive mode showing available updates
- Options:
  - `-a, --all` - Update all items
  - `-f, --force` - Force update even with local changes
  - `-y, --yes` - Skip confirmation prompts
  - `-i, --interactive` - Interactive selection mode

### Repository Commands

#### `repo create <path>` - Create a new metadata repository
- Options:
  - `-t, --template <template>` - Use template (basic, full)
  - `-g, --git` - Initialize as git repository

#### `repo push [type] [name]` - Push changes to repository (creates PR)
- Without arguments: interactive mode detects modified items
- Options:
  - `-m, --message <message>` - Commit message
  - `-n, --new <file>` - Push a new file
  - `-d, --delete` - Delete item from repository
  - `-y, --yes` - Skip confirmation prompts

### Configuration Commands
- `config show` - Show current configuration
  - `-g, --global` - Show global configuration

- `config set <key> <value>` - Set configuration value
  - `-g, --global` - Set in global configuration

## Repository Structure

Metadata repositories should follow this structure:

```
metadata-repo/
├── commands/              # Slash commands (*.md with frontmatter)
├── agents/                # Agent files
└── manifest.json         # Optional manifest file
```

Example command file with frontmatter:
```markdown
---
name: commit
description: Create git commits with conventional commit format
version: 1.0.0
author: Your Name
tags: [git, productivity]
---

# Commit Command

This command helps create well-formatted git commits...
```

## Configuration

Project configuration (`.ccproject.json`):
```json
{
  "repository": "https://github.com/your-org/claude-metadata",
  "branch": "main",
  "autoSync": false
}
```

User configuration (`~/.ccproject/config.json`):
```json
{
  "defaultRepository": "https://github.com/your-org/claude-metadata",
  "cachePath": "~/.ccproject/cache",
  "repositories": {
    "work": {
      "url": "https://github.com/company/claude-metadata",
      "branch": "main"
    }
  }
}
```

## Pushing Changes

The `repo push` command now features an interactive mode to reduce typing:

### Interactive Mode (Recommended)
```bash
# Let ccproject detect what to push
ccproject repo push

# The command will:
# 1. Detect modified items automatically
# 2. Let you choose what to push
# 3. Generate a default commit message
# 4. Create a pull request
```

### Direct Mode
```bash
# Push updates to an existing item
ccproject repo push command review-branch -m "Add Python support"

# Push a new file
ccproject repo push --new ./my-command.md

# Remove an item from the repository
ccproject repo push --delete
```

### Interactive Push Example
```bash
$ ccproject repo push
? What would you like to do?
  ❯ Push changes to modified items
    Add a new item to the repository
    Delete an item from the repository

? Select item to push:
  ❯ [command] review-branch

? Commit message: Update command "review-branch"

? Push changes to command "review-branch"? Yes

✓ Created pull request for command "review-branch"
```

## Usage Tracking

The `.ccusage` file tracks installed items:
```json
{
  "version": "1.0.0",
  "installations": [
    {
      "type": "command",
      "name": "commit",
      "source": "https://github.com/your-org/claude-metadata",
      "hash": "abc123...",
      "path": ".claude/commands/commit.md",
      "installed": "2024-01-01T00:00:00Z",
      "modified": false
    }
  ]
}
```

## Creating a Metadata Repository

Set up a new metadata repository:

```bash
# Basic setup
ccproject repo create ./my-metadata-repo

# With sample files and git initialization
ccproject repo create ./my-metadata-repo --template basic --git

# Full template with multiple examples
ccproject repo create ./my-metadata-repo --template full --git
```

## Repository URL Shortcuts

ccproject supports convenient shortcuts for common git providers:

| Shorthand | Expands to |
|-----------|------------|
| `github:user/repo` | `https://github.com/user/repo.git` |
| `gh:user/repo` | `https://github.com/user/repo.git` |
| `gitlab:user/repo` | `https://gitlab.com/user/repo.git` |
| `gl:user/repo` | `https://gitlab.com/user/repo.git` |
| `bitbucket:user/repo` | `https://bitbucket.org/user/repo.git` |
| `bb:user/repo` | `https://bitbucket.org/user/repo.git` |

## Complete Workflow Example

```bash
# 1. Initialize with GitHub shorthand
ccproject init github:jedimemo/cc-meta

# 2. Explore available items interactively
ccproject add                     # Interactive browse and install

# 3. Or use quick-add for batch installation
ccproject qa                      # Select multiple items by category

# 4. Search for specific functionality
ccproject list review --install   # Find and install review tools

# 5. Check for updates periodically
ccproject status                  # Shows what needs updating

# 6. Update interactively
ccproject update                  # Select which updates to install

# 7. Contribute improvements back
# Edit .claude/commands/review-branch.md locally, then:
ccproject repo push command review-branch -m "Add Python support"
```

## Interactive Mode Examples

### Installing Items
```bash
$ ccproject add
? What type of item would you like to add?
  ❯ Commands - Slash commands for Claude
    Agents - AI assistant configurations
    All - Browse all available items

? Select items to install (space to select, enter to confirm):
  ◯ [command] review-branch - Security-focused code review
  ◯ [command] git-commit - Create conventional commits
  ◯ [agent] code-analyzer - Analyze code quality

Items to install:
  - command: review-branch
  - command: git-commit
? Install 2 items? (Y/n)
```

### Updating Items
```bash
$ ccproject update
Checking for available updates...
? Select items to update (2 available):
  ◉ [command] review-branch
  ◯ [command] git-commit [modified]
```

## License

MIT