ai-toolkit

AI coding toolkit with machine-enforced safety, 116 skills, 44 agents, lifecycle hooks, persona presets, opt-in plugin packs, and benchmark tooling. DSH is available as a separate explicit developer-preview target.

What's New in v4.34.1

• Working MCP URLs: native editor configs receive resolved endpoint addresses from ${NAME} and ${NAME:-default} template expressions.
• Local template refresh: ai-toolkit update re-reads registered local MCP templates, repairing stale generated configuration such as rag-mcp-legal.
• Source preservation: portable templates, credential placeholders, unrelated settings and missing-source configurations remain intact.

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

DSH Developer Preview

DSH has separate project and profile ownership:

# Generic local outputs plus DSH-specific .agents/skills. No DSH_HOME write.
ai-toolkit install --local --editors dsh

# Explicit profile lifecycle.
ai-toolkit dsh install --profile web
ai-toolkit dsh update --profile web
ai-toolkit dsh doctor --profile web
ai-toolkit dsh uninstall --profile web --yes

DSH is excluded from --editors all, auto-detection, and defaults. Its only DSH-specific project output is .agents/skills; the normal --local Claude files, detected language rules, and other generic project outputs still apply. Project and profile --dry-run commands are read-only. The lifecycle targets DSH 0.1.2-rc.1, @softspark/dsh-codex@1.5.0, and @softspark/dsh-orchestrator@2.0.0. Update the DSH runtime before updating this profile integration. Codex, Claude Code, and GitHub Copilot own their logins. ai-toolkit accepts no provider API keys, and GitHub AI credits apply to the Copilot Gemini route. See DSH Compatibility for the exact contract and version-specific qualification evidence.

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

Platform	Config Files	Hooks	Scope
Claude Code	~/.claude/agents, ~/.claude/skills, ~/.claude/rules/*.md, ~/.claude/settings.json	✅	global
Claude Chat / Cowork	uploaded plugin ZIP + UI global/folder instructions + claude_desktop_config.json (MCP)	Cowork only	account/app
Cursor	.cursor/rules/*.mdc + .cursor/mcp.json + .cursor/skills/*	✅	project (~/.cursor/mcp.json for MCP only)
Windsurf (Devin Desktop)	~/.config/devin/AGENTS.md + .devin/rules/*.md + .devin/hooks.v1.json + .windsurf/skills/*	✅	global + project
Gemini CLI	~/.gemini/GEMINI.md + .gemini/settings.json + .gemini/{commands,skills,agents}/	✅	project + user
GitHub Copilot	Project: AGENTS.md + .github/copilot-instructions.md + .github/{instructions,prompts,agents,skills,hooks}/ + .github/mcp.json; user: $COPILOT_HOME/copilot-instructions.md + $COPILOT_HOME/{instructions,agents,skills,hooks}/ + $COPILOT_HOME/mcp-config.json	✅	project + user
Cline	Project: .cline/{rules,hooks,skills}/ + .clinerules/{hooks,workflows}/; user: ~/.cline/{rules,hooks,skills}/ + ~/Documents/Cline/{Rules,Hooks}/ compatibility	✅	global + project
Roo Code / Zoo Code	~/.roo/rules/*.md + .roomodes + .roo/rules/*.md	—	global rules + project
Aider	~/.aider.conf.yml + .aider.conf.yml + CONVENTIONS.md	—	global + project
Augment	~/.augment/rules/*.md + .augment/rules/ai-toolkit-*.md	✅	global + project
Google Antigravity	Project .agents/{rules,workflows,skills,agents,hooks}/; user ~/.gemini/config/{skills,agents,hooks}/; opt-in native plugin export	✅	project + user
Codex CLI	Project: AGENTS.md + .agents/skills/* + .codex/{agents,hooks}/ + .codex/{hooks.json,config.toml}; user: $CODEX_HOME/{AGENTS.md,agents,hooks.json,config.toml} + $HOME/.agents/skills/*	✅	project + user
opencode	AGENTS.md + .opencode/{agents,commands,plugins,skills}/* + opencode.{json,jsonc}	✅	project + global (~/.config/opencode/)
DeepSeek Harness	Project .agents/skills/*; explicit profile packages and $DSH_HOME/.agent-presets/softspark-orchestrator	no bridge	project + explicit named profile

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

Component	Count	Description
skills/ (task)	32	Slash commands: /commit, /build, /deploy, /test, /mcp-builder, ...
skills/ (hybrid)	33	Slash commands with agent knowledge base
skills/ (knowledge)	51	Domain knowledge auto-loaded by agents (includes 13 <lang>-rules skills)
agents/	44	Specialized agents across 10 categories
hooks/	28 entries / 14 events + statusLine	Quality gates, path safety, prompt governance, loop guard, session lifecycle
plugins/	2 packs	Opt-in packs that install files of their own (memory, enterprise)
constitution.md	7 articles	Machine-enforced safety rules
rules/	auto-synced	Global/project rule files for Claude and other editors
kb/	reference docs	Architecture, procedures, and best practices

---

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.

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.

28 MCP templates — Ready-to-use configs for GitHub, PostgreSQL, Slack, Jira, Sentry, general RAG, and Polish legal RAG. See MCP Templates.

See Unique Features for detailed descriptions of all differentiators.

---

Key Slash Commands

Command	Purpose	Effort
/workflow <type>	Pre-defined multi-agent workflow (16 types)	max
/autonomous-dev	Task-to-PR delivery with persistent state, review, QA and resume	high
/prepare-test-env	Prepare and verify the running app used by QA	high
/orchestrate	Custom multi-agent coordination (3–6 agents)	max
/swarm	Parallel Agent Teams: map-reduce, consensus, relay	max
/plan	Implementation plan with task breakdown	high
/review	Code review: quality, security, performance	high
/debug	Systematic debugging with diagnostics	medium
/refactor	Safe refactoring with pattern analysis	high
/tdd	Test-driven development with red-green-refactor	high
/commit	Structured commit with linting	medium
/pr	Pull request with generated checklist	medium
/docs	Generate README, API docs, architecture notes	high
/explore	Interactive codebase visualization	medium
/write-a-prd	Create PRD through interactive interview	high
/prd-to-plan	Convert PRD into vertical-slice implementation plan	high
/design-an-interface	Generate 3+ radically different interface designs	high
/grill-me	Stress-test a plan through Socratic questioning	medium
/triage-issue	Triage bug with deep investigation and TDD fix plan	high
/architecture-audit	Discover shallow modules, propose refactors	high
/council	4-perspective decision evaluation	high
/cve-scan	Scan dependencies for known CVEs	medium
/skill-audit	Scan skills/agents for security risks	medium
/repeat	Autonomous loop with safety controls	medium
/persona	Switch engineering persona at runtime	low

/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
autonomous-development

Multi-Agent Skill Selection

Need multi-agent coordination?
├── Know your domains? → /orchestrate (ad-hoc, 3-6 agents)
├── Have a known pattern? → /workflow <type> (16 routes)
├── Need task-to-PR delivery with resume? → /autonomous-dev
├── Need consensus/map-reduce? → /swarm <mode>
├── Want Agent Teams API? → /teams (experimental)
└── Executing a plan? → /subagent-development

---

Autonomous software delivery

/autonomous-dev setup
/autonomous-dev run "Add CSV export for filtered orders"
/autonomous-dev run PROJ-123
/autonomous-dev list
/autonomous-dev resume <run-id>
/autonomous-dev status <run-id>

The process takes a brief, specification, issue or existing PR through planning, implementation, project-specific validation, review, application QA and required CI. It reuses the same PR and resumes from durable state. The default endpoint is a ready PR; merge and deployment need separate authorization.

The current agent host performs the work. Bundled Python helpers maintain a transactional run journal and check QA environment identity/readiness. They do not launch an LLM or continue running after the host stops. Generated reports stay outside the target repository, while .ai-toolkit/autonomous.json records intentional project configuration. See the autonomous development guide for setup, ownership, recovery, evidence and supported runtime boundaries.

The optional SoftSpark stack profile separates Jira task tracking, code-host PR/CI and RAG knowledge. It refreshes task requirements and source-backed KB context on resume, reconciles Jira comment receipts before retries and treats Jira completion and KB indexing as explicit project lifecycle outcomes.

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

Topic	Link
CLI Reference	kb/reference/cli-reference.md
Unique Features	kb/reference/unique-features.md
Architecture Overview	kb/reference/architecture-overview.md
Hooks Catalog	kb/reference/hooks-catalog.md
Language Rules	kb/reference/language-rules.md
MCP Templates	kb/reference/mcp-templates.md
Extension API	kb/reference/extension-api.md
Manifest Install	kb/reference/manifest-install.md
Plugin Packs	kb/reference/plugin-pack-conventions.md
Enterprise Config	kb/reference/enterprise-config-guide.md
Distribution Model	kb/reference/distribution-model.md
Ecosystem Comparison	kb/reference/comparison.md
Codex CLI Compatibility	kb/reference/codex-cli-compatibility.md
opencode Compatibility	kb/reference/opencode-compatibility.md
GitHub Copilot Compatibility	kb/reference/copilot-compatibility.md
DSH Compatibility	kb/reference/dsh-compatibility.md
Maintenance SOP	kb/procedures/sop-maintenance.md

---

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.