ai-toolkit

ai-toolkit

AI coding toolkit with machine-enforced safety, 116 skills, 44 agents, lifecycle hooks, persona presets, opt-in plugin packs, and benchmark tooling.

What's New in v5.0.1

• The fallback pre-commit hook blocks on a failed linter. It used to print "Pre-commit checks passed" even when PHPStan crashed, because the checker it called always exited 0. It now fails on a failed or crashed checker and says when nothing ran. PHPStan gets an explicit memory limit.
• Releases gate locally. npm run release -- X.Y.Z runs validate, the audits, ShellCheck, bats on macOS and in Linux, and the Python floor, then tags and pushes. GitHub Actions only publishes the tag.
• Still in v5.0.0: user-level rules and constitution, a complete uninstall, DSH retired.

See CHANGELOG.md for full history.

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 116 skills, 44 agents, quality hooks, and the safety constitution automatically.

Language knowledge skills (rust-rules, kotlin-patterns, ...) are scoped to the languages your registered projects use: once you have run ai-toolkit install --local in at least one project, the global install turns the other languages' skills off through skillOverrides in ~/.claude/settings.json so their descriptions stop loading into every session. A new project in a new language turns its skills back on. ai-toolkit install --language-skills all keeps every language skill on and remembers that choice; ai-toolkit doctor shows the resulting context budget.

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

DeepSeek Harness (DSH) support is retired: --editors dsh is ignored with a warning and ai-toolkit dsh ... only prints manual cleanup steps. ai-toolkit update --local cleans up old DSH project skills, and DSH profiles are removed with DSH itself. See DSH Compatibility (retired).

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; within the Claude app, hooks and sub-agents run in Cowork. Account-enabled plugins also sync to Claude Code terminal sessions from 2.1.273. The doctor reports possible collisions with the global install; required organization plugins need an administrator decision.

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. The archive contains portable root plugin.json with OpenAI metadata under extensions.com.openai, plus the .codex-plugin/plugin.json compatibility manifest for older clients. Verification checks that both manifests agree. 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/          # 116 skills (task / hybrid / knowledge)
│   ├── rules/           # Source rules synced into Claude/editor rule files
│   ├── hooks/           # Hook scripts (28 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
└── 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.

29 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, secrets-at-rest reminders, 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.