ai-toolkit

Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 109 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude Code, Claude Chat/Cowork, Cursor, Devin, Copilot, Gemini, Cline, Roo/Zoo Code, Aider, Augment, Google Antigravity, Codex CLI, and opencode.

What's New in v4.29.2

v4.29.2 makes install --dry-run tell the truth about Codex hooks:

• Selecting codex always installs Codex lifecycle hooks -- .codex/hooks.json plus the scripts under .codex/hooks/ -- at every profile. The dry-run branch listed only agents and skills, so the preview silently omitted a whole surface, and the one you are asked to review and trust with /hooks.
• Both previews now name it: project installs announce .codex/hooks.json + .codex/hooks/, global installs add $CODEX_HOME/ai-toolkit-hooks/ next to $CODEX_HOME/hooks.json.
• Four tests pin the preview against what the live install actually writes, so a surface cannot go missing from the dry-run again. Test count: 1671 -> 1675.

Table of Contents

• Install
• Platform Support
• What You Get
• Architecture
• Key Features
• Key Slash Commands
• Getting Started
• Documentation
• Contributing
• Security
• License
• Changelog

Install

Requirements: Node.js >= 18 and Python >= 3.11.

macOS: /usr/bin/python3 is Python 3.9 and will not run the toolkit. Install a supported one with brew install python@3.13 and make sure which python3 no longer points at /usr/bin/python3.

# Option A: install globally (once per machine)
npm install -g @softspark/ai-toolkit
ai-toolkit install

# Option B: try without installing (npx)
npx @softspark/ai-toolkit install

That's it. Claude Code picks up 109 skills, 44 agents, quality hooks, and the safety constitution automatically.

Windows: WSL is the recommended runtime. Native Windows works when Git Bash is available for hook scripts; dependency hints cover winget, Chocolatey, and Scoop. See Windows Support.

Update

npm install -g @softspark/ai-toolkit@latest && ai-toolkit update

Per-Project Setup

cd your-project/
ai-toolkit install --local                        # Claude Code only
ai-toolkit install --local --editors all          # + all editors
ai-toolkit install --local --editors cursor,aider # + specific editors
ai-toolkit update --local                         # auto-detects editors

Plugin Management

ai-toolkit plugin list                            # show available packs
ai-toolkit plugin install --editor all --all      # install all for Claude Code + Codex
ai-toolkit plugin status --editor all             # show what's installed

Claude Chat / Desktop / Cowork

The Claude app does not read Claude Code's ~/.claude/rules/ or CLAUDE.md. Export and upload the app-native plugin instead:

ai-toolkit claude-app export --verify
# Claude > Customize > Plugins > + > Upload plugin
# Paste the generated *-global-instructions.md into:
# Settings > Cowork > Global instructions

Re-export and re-upload after toolkit or registered-rule updates. Skills work in Chat and Cowork; hooks and sub-agents are active only in Cowork.

Native Codex Plugin

Build or validate the marketplace-ready Codex package without changing ~/.agents or ~/.codex:

ai-toolkit codex-plugin export --output ai-toolkit-codex-plugin.zip
ai-toolkit codex-plugin verify

Extract the ZIP into a local marketplace under plugins/ai-toolkit/, add that marketplace with codex plugin marketplace add <marketplace-root>, then install from /plugins in Codex CLI and start a new session. Review and trust the bundled hooks before use. The ZIP includes plugin-local persona definitions, the briefing helper, the skill-audit helper and its local imports, and other referenced skill resources. Export rejects symlinked output paths and ancestors. Codex IDE does not support plugins.

Install Profiles

ai-toolkit install --profile minimal    # agents + skills only
ai-toolkit install --profile standard   # full install (default)
ai-toolkit install --profile strict     # full + git hooks

Verify & Repair

ai-toolkit validate          # check integrity
ai-toolkit doctor --fix      # auto-repair

See CLI Reference for all commands and options.

Platform Support

Claude Code is always installed (primary platform). Other editors are selected with --editors; the Claude app uses the separate claude-app export flow because its customization store is UI/plugin-managed, except for MCP servers, which ai-toolkit mcp install --editor claude-app --scope global writes straight to claude_desktop_config.json. The Hooks column marks platforms with lifecycle enforcement. Platforms marked — receive guidance without blocking hooks.

What You Get

Architecture

ai-toolkit/
├── app/
│   ├── agents/          # 44 agent definitions
│   ├── skills/          # 109 skills (task / hybrid / knowledge)
│   ├── rules/           # Source rules synced into Claude/editor rule files
│   ├── hooks/           # Hook scripts (29 entries, 14 lifecycle events)
│   ├── claude-app/      # Generated Chat/Cowork plugin rules, hooks, instructions
│   ├── plugins/         # 2 experimental plugin packs (opt-in)
│   ├── output-styles/   # System prompt output style overrides
│   ├── constitution.md  # 7 immutable safety articles
│   └── ARCHITECTURE.md  # Full system design
├── kb/                  # Reference docs, procedures, plans
├── scripts/             # Validation, install, evaluation scripts
├── tests/               # Bats and Python test suite (1659 tests)
└── CHANGELOG.md

Distribution: Symlink-based for agents/skills, copy-based for hooks. Run ai-toolkit update after npm install — all projects pick up changes instantly. See Distribution Model.

Key Features

Machine-enforced constitution — 7-article safety constitution enforced via PreToolUse hooks that actually block rm -rf, DROP TABLE, and irreversible operations. Not just documentation.

28 lifecycle hook entries: Executable handlers across 14 events (SessionStart → SessionEnd, plus InstructionsLoaded + ConfigChange). Guards, governance, quality gates, session persistence, MCP health checks, revert protection, test-cohesion enforcement, loop guard, and search-first discipline. See Hooks Catalog.

Security scanning — /skill-audit for code-level risks, /cve-scan for dependency CVEs. Both CI-ready with exit codes.

Iron Law enforcement — /tdd, debugging-tactics, and verification-before-completion enforce non-negotiable gates with anti-rationalization tables. 15 skills total include rationalization resistance.

Multi-language quality gates — Stop hook runs lint + type checks across Python, TypeScript, PHP, Dart, Go after every response.

Agent verification checklists — 10 agents include exit criteria that must be met before presenting results.

Two-stage review — /subagent-development runs Implementer → Spec Review → Quality Review per task.

Persistent memory — memory-pack plugin: SQLite + FTS5 search across past sessions.

Local product telemetry — ai-toolkit stats --summary reports total invocations, skill coverage, unused catalog skills, recent activity, and top skills from local usage data.

Persona presets — 4 roles (backend-lead, frontend-lead, devops-eng, junior-dev) adjust style and priorities.

Config inheritance — Enterprise extends system with constitution immutability and enforcement constraints. See Enterprise Config Guide.

70 language rules — 13 languages + common, 5 categories each. Auto-detected or explicit --lang. See Language Rules.

26 MCP templates — Ready-to-use configs for GitHub, PostgreSQL, Slack, Jira, Sentry, and more. See MCP Templates.

See Unique Features for detailed descriptions of all differentiators.

Key Slash Commands

/workflow Types

feature-development    backend-feature       frontend-feature
api-design             database-evolution    test-coverage
security-audit         codebase-onboarding   spike
debugging              incident-response     performance-optimization
infrastructure-change  application-deploy    proactive-troubleshooting

Multi-Agent Skill Selection

Need multi-agent coordination?
├── Know your domains? → /orchestrate (ad-hoc, 3-6 agents)
├── Have a known pattern? → /workflow <type> (15 templates)
├── Need consensus/map-reduce? → /swarm <mode>
├── Want Agent Teams API? → /teams (experimental)
└── Executing a plan? → /subagent-development

Getting Started

1. Customize CLAUDE.md — add your project's tech stack, commands, and conventions at the top (above toolkit markers).

2. Start using skills:

   /onboard     # guided setup interview
   /explore     # understand your codebase
   /plan        # plan a feature
   

3. Verify your install:

   ai-toolkit validate
   

Documentation

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for responsible disclosure policy.

License

Apache License 2.0 — see LICENSE and NOTICE.

Fork it, modify it, ship it commercially. Three things the licence asks in return:

• Keep the attribution. Redistributions must carry the contents of NOTICE (§4d) — that is where the project name, copyright and source URL live.
• Say what you changed. Modified files must carry a prominent notice stating that you changed them (§4b).
• Names are not included. The licence grants no rights to the "ai-toolkit" or "SoftSpark" names or marks (§6).

Releases up to and including v4.20.0 were published under MIT and stay available under MIT; the change applies going forward and revokes nothing already granted. Contributions received while the project was MIT-licensed remain their authors' copyright and are redistributed under Apache 2.0 with the original MIT notice preserved in NOTICE, as MIT requires.

Changelog

See CHANGELOG.md.

Extracted from production use at SoftSpark. Built to be the toolkit we wished existed.