code-kits

Universal CLI for scaffolding AI agent configurations across Claude Code, OpenCode, and Droid CLI platforms.

Features

• Multi-Platform Support: Generate configurations for Claude Code, OpenCode, and Droid CLI
• Intelligent Scaffolding: Automatically detects project context (tech stack, testing, CI/CD)
• Rich Templates: 12 agent templates, 18 command templates, and 15 skill templates
• Cross-Platform Migration: Convert configurations between platforms
• Idempotent Operations: Safe to re-run without duplicating configurations

Installation

npm install -g codekits-cli

Quick Start

# Initialize configuration
codekits init

# Scaffold agents and commands for Claude Code
codekits create --cli=claude

# Or for OpenCode
codekits create --cli=opencode

# Or for Droid CLI
codekits create --cli=droid

Commands

codekits init

Initialize .codekits.json configuration in your project.

codekits init
codekits init --interactive

codekits create

Scaffold AI agent configurations for a project.

codekits create --cli=claude
codekits create --cli=opencode --template=backend
codekits create --cli=droid --target=/path/to/project
codekits create --cli=claude --defaults  # Skip prompts

Options:

• --cli <platform> - Target platform (claude, opencode, droid) required
• --target <path> - Target directory (default: current directory)
• --template <type> - Template type (full-stack, backend, frontend, data, security)
• --defaults - Skip prompts and use defaults

codekits add-agent

Add a new agent to existing configuration.

codekits add-agent --cli=claude
codekits add-agent --cli=droid --name=reviewer --role="Code review specialist"

Options:

• --cli <platform> - Target platform required
• --name <name> - Agent name (prompted if not provided)
• --role <role> - Agent role/description
• --target <path> - Target directory

codekits add-command

Add a new command to existing configuration.

codekits add-command --cli=claude
codekits add-command --cli=opencode --name=deploy --type=utility

Options:

• --cli <platform> - Target platform required
• --name <name> - Command name (prompted if not provided)
• --type <type> - Command type (planning, building, fixing, git, utility)
• --target <path> - Target directory

codekits list

List installed agents and commands.

codekits list
codekits list --cli=claude
codekits list --type=agents --format=json

Options:

• --cli <platform> - Filter by platform
• --type <type> - Filter by type (agents, commands, all)
• --format <format> - Output format (table, json)
• --target <path> - Target directory

codekits validate

Validate configuration syntax and completeness.

codekits validate
codekits validate --cli=claude
codekits validate --fix  # Auto-fix common issues

Options:

• --cli <platform> - Validate specific platform
• --fix - Auto-fix common issues
• --target <path> - Target directory

codekits migrate

Migrate configurations between platforms.

codekits migrate --from=claude --to=droid
codekits migrate --from=opencode --to=claude --no-backup

Options:

• --from <platform> - Source platform required
• --to <platform> - Target platform required
• --no-backup - Skip creating backup
• --target <path> - Target directory

codekits export

Export configurations to portable format.

codekits export --format=json
codekits export --cli=claude --format=markdown --output=./docs

Options:

• --cli <platform> - Export specific platform
• --format <format> - Output format (json, markdown)
• --output <path> - Output file or directory
• --target <path> - Target directory

codekits upgrade

Check for and install code-kits updates.

codekits upgrade
codekits upgrade --check  # Check only, don't install

Options:

• --check - Check for updates without installing
• --force - Force upgrade even if on latest version

Templates

Agent Templates

| Agent | Role | Best For | |-------|------|----------| | plan | Strategic planning and task breakdown | Feature planning, PRD generation | | build | Primary implementation | Feature development, TDD | | code-auditor | Code quality and security | Code review, security scanning | | oracle | Complex debugging | Bug investigation, root cause analysis | | explore | Codebase navigation | Understanding new codebases | | brainstorm | Idea exploration | Design decisions, architecture | | research | Deep investigation | Documentation analysis, best practices | | quick-build | Fast iteration | Small changes, bug fixes | | security-auditor | Vulnerability scanning | Security audits, compliance | | docs | Documentation | API docs, README, guides | | design | UI/UX implementation | Frontend, accessibility | | librarian | External code search | GitHub repositories, documentation research |

Command Templates

Planning:

• task-with-spec - Structured task with PRD, spec, review
• plan - Implementation plan generation
• plan-and-build - Combined planning and implementation
• research - Deep research workflow
• brainstorm - Multi-perspective idea exploration
• design - UI/UX design specification

Building:

• quick-build - Fast implementation
• complete-task - Validate and close task
• integration-test - Run integration tests

Fixing:

• fix - Auto-select fix strategy
• fix-types - TypeScript error resolution
• fix-ui - UI/UX issue fixes
• fix-ci - CI pipeline troubleshooting

Git:

• commit - Stage and commit with auto-message
• pr - Create pull request
• issue - Create GitHub issue

Review:

• review-codebase - Full codebase audit
• analyze-project - Project structure analysis

Skill Templates

Planning: brainstorming, writing-plans, executing-plans
Development: subagent-driven-development, dispatching-parallel-agents, using-git-worktrees
Testing: test-driven-development, condition-based-waiting, testing-anti-patterns
Debugging: systematic-debugging, root-cause-tracing, defense-in-depth
Collaboration: requesting-code-review, receiving-code-review, sharing-skills

Configuration

Create a .codekits.json in your project root:

{
  "version": "1.0.0",
  "platforms": {
    "claude": {
      "enabled": true,
      "template": "full-stack"
    },
    "droid": {
      "enabled": true,
      "template": "backend"
    }
  },
  "shared": {
    "description": "My awesome project",
    "techStack": ["typescript", "react", "node"]
  }
}

Platform Output

Claude Code (.claude/)

.claude/
├── agents/
│   ├── @plan.md
│   ├── @build.md
│   └── @oracle.md
├── commands/
│   ├── fix.md
│   ├── commit.md
│   └── pr.md
└── README.md

OpenCode (.opencode/)

.opencode/
├── agents/
│   ├── plan.md
│   ├── build.md
│   └── oracle.md
├── commands/
│   ├── fix.md
│   └── commit.md
└── README.md

Droid CLI (.factory/)

.factory/
├── droids/
│   ├── plan.md
│   ├── build.md
│   └── oracle.md
├── commands/
│   ├── fix.md
│   └── commit.md
└── README.md

Troubleshooting

Command not found

# Ensure npm bin is in PATH
export PATH="$(npm bin -g):$PATH"

# Or use npx
npx code-kits --help

Permission denied

# Fix npm permissions
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

Existing configuration

If you have existing configurations, codekits create will:

1. Detect existing agents/commands
2. Skip duplicates (idempotent)
3. Only create new items

Use --defaults to skip confirmation prompts.

FAQ

Q: Can I use multiple platforms simultaneously?
A: Yes! Run codekits create for each platform. They use separate directories.

Q: Will this overwrite my existing configurations?
A: No. The tool is idempotent - it skips existing agents/commands.

Q: How do I customize the generated agents?
A: Edit the generated files directly. They're standard Markdown with YAML frontmatter.

Q: Can I add my own templates?
A: Use codekits add-agent and codekits add-command for custom configurations.

Contributing

Contributions are welcome! Please read our contributing guidelines.

License

MIT License - see LICENSE for details.