CortexHawk

An open-source, community-driven development toolkit for Claude Code.

CortexHawk provides a modular collection of optimized agents, skills, commands, hooks, and behavioral modes that transform Claude Code into a full-stack development team. Every prompt has been written for maximum efficiency — less token bloat, sharper instructions, better agent coordination.

What's New in v3.3

• Gitflow strategy — full gitflow support in /cleanup: dual-target merge detection (feat→develop, release/hotfix→main), conditional branch protection, auto-resync develop ← main
• /cleanup command — unified post-merge cleanup with 4 strategies (direct-main, feature-branches, dev-branch, gitflow), --dry-run preview, native post-merge hook opt-in
• /review-pr command — fetch, triage, and fix PR review comments in batch (one commit, one notification)
• lint-guard hook — auto-detects formatters/linters on staged files; auto-fix for prettier/black/gofmt/rustfmt, check-only for eslint/flake8/mypy; parallel execution, pre-commit delegation
• install.sh modularized — extracted 5 modules into scripts/ (4114 → 3168 lines, -23%)
• MCP configs hardened — all packages pinned to exact versions, puppeteer package name fixed
• Security fixes — path traversal guards in codex-dispatcher and restore, python3 availability guards
• 10+ bug fixes — see CHANGELOG.md for full details

• /commit command — lightweight conventional commit + push without review or PR (use /ship for full workflow)
• --version flag — standard CLI version display
• PR/commit templates — auto-detected at install, generated if missing; agents read templates at runtime
• Settings.json merge — reinstall and --update now merge new hooks + permissions instead of skipping
• Security hardening — eliminated shell injection in all Python HEREDOC scripts, portable sed -i, input validation
• --init wizard — "Auto-detect" target option, improved multi-target support
• 15+ bug fixes — see CHANGELOG.md for full details

• npm install -g cortexhawk — available on npm, auto-resolves source from symlinked binary
• cortexhawk CLI wrapper — clean subcommands (init, install, update, doctor, validate, search, snapshot, etc.) instead of bash install.sh --flags
• --target auto — auto-detects installed CLIs (claude, kimi, codex) and installs for all found
• cortexhawk validate — post-install diagnostic verifying skills/agents discovery per target

• --init wizard overhaul — reordered flow with git workflow config, auto git init + .gitignore creation, branching strategies (direct-main, dev-branch, git-flow)
• /bootstrap --smart — researcher agent scans roadmap, compares stacks, recommends, then scaffolds
• Post-install gitignore — auto-adds .claude/, .kimi/, .codex/ to .gitignore, asks about docs/
• --update checksum detection — compares file checksums instead of just version numbers to detect changes
• Kimi CLI overhaul — agents, commands, hooks all converted to skills; AGENTS.md at project root; MCP optional; auto .envrc for local install
• --demo flag — sandbox project in /tmp/ with intentional bugs for testing
• /upgrade command — check for updates, show changelog diff, propose --update
• --publish-skill — publish local skills to GitHub with auto-generated README
• Cursor CLI removed — too unstable for maintained support

Quick Start

# Install (pick one)
npm install -g cortexhawk                          # via npm
git clone https://github.com/Spechawk94/CortexHawk.git ~/.cortexhawk && cd ~/.cortexhawk && ./setup.sh  # via git

# Set up your project
cd /path/to/your/project
cortexhawk init                       # interactive wizard (recommended)
cortexhawk install                    # direct install (all skills)
cortexhawk install --profile api      # install only API skills
cortexhawk install --target auto      # auto-detect installed CLIs
cortexhawk install --target kimi      # Kimi CLI (experimental)

# Useful commands
cortexhawk update                     # update installation
cortexhawk validate                   # verify skills/agents discovery
cortexhawk doctor                     # check installation health
cortexhawk search react               # search 87k+ community skills
cortexhawk self-update                # update CortexHawk source

git clone https://github.com/Spechawk94/CortexHawk.git /tmp/cortexhawk
cd /path/to/your/project
bash /tmp/cortexhawk/install.sh --init

# Skill packs (curated bundles)
bash /tmp/cortexhawk/install.sh --pack react-app
bash /tmp/cortexhawk/install.sh --pack security-suite

# Profiles: fullstack, api, data, autodetect
bash /tmp/cortexhawk/install.sh --profile autodetect

What's Inside

Agents (20)

Specialized AI agents that coordinate together instead of working in silos.

| Agent | Role | |---|---| | planner | Breaks features into executable tasks | | implementer | Writes production code from plans | | tester | Generates tests and validates coverage | | reviewer | Multi-pass code review (logic, security, perf) | | debugger | Root cause analysis and fix | | security-auditor | OWASP Top 10, CVE scanning, audit reports | | architect | System design, API design, infra decisions | | devops | CI/CD, Docker, deployment, monitoring | | researcher | Tech research, benchmarks, comparisons | | designer | UI/UX patterns, accessibility, responsive | | git-manager | Branching strategy, commits, PR management | | docs-manager | Documentation generation and maintenance | | project-manager | Progress tracking, roadmaps, milestones | | copywriter | Release notes, changelogs, technical comms | | journal-writer | Dev journals, decision logs, retrospectives | | brainstormer | Ideation, mind mapping, solution exploration | | code-simplifier | Complexity reduction, code clarification | | codebase-mapper | Generates architectural map of the codebase | | fullstack-developer | Full-stack orchestration front+back | | teacher | Teaches concepts with 3 pedagogical levels (guided, mentor, professor) |

Commands (35)

Slash commands for common workflows.

| Command | Description | |---|---| | /plan | Create implementation plan for a feature | | /build | Implement code from plan or description | | /test | Generate and run tests | | /review | Multi-agent code review | | /review-pr | Fetch, triage, and fix PR review comments in batch | | /ship | Commit + PR pipeline | | /commit | Lightweight commit + push (no review, no PR) | | /cleanup | Post-merge branch cleanup (auto-detects strategy) | | /debug | Debug and fix issues | | /scan | Full security audit | | /check | Pre-commit quality gate (lint + test + scan + review → GO/NO-GO) | | /refactor | Guided refactoring | | /research | Technology research and comparison | | /doc | Generate documentation | | /bootstrap | Initialize a new project with full setup | | /tdd | Test-driven development cycle | | /optimize | Performance analysis and improvement | | /migrate | Database migration generation | | /monitor | Monitoring, health checks, alerting | | /api-gen | Generate API endpoints from spec | | /changelog | Generate changelog from git history | | /journal | Write a dev journal entry | | /brainstorm | Structured brainstorming session | | /simplify | Simplify complex code | | /deploy | Deploy to production | | /export | Save session as structured markdown | | /backlog | Process brainstorms into prioritized backlog | | /pulse | Project health dashboard with agent analytics | | /map | Generate architectural map of the codebase | | /learn | Activate learn mode with level and topic | | /chain | Sequential agent execution with context passing | | /task | Execute a backlog item end-to-end via chain orchestration | | /ci | Generate CI/CD pipeline tailored to project stack | | /context | Manage persistent project context shared across all agents | | /upgrade | Check for updates, show changelog diff, propose update |

Agent Chaining

Chain multiple agents into automated pipelines. Each agent receives the output of the previous one.

Built-in presets:

| Preset | Sequence | |---|---| | default | plan → build → test → review | | security | scan → review | | ship | test → review → ship |

Usage:

/chain default auth-system           # run default preset
/chain security payment-module       # security audit pipeline
/chain plan,build,test api-endpoint  # explicit comma-separated list
/chain --gate default auth-system    # pause between each step for confirmation
/chain --replay auth-system          # re-execute previous chain with fresh context

Custom presets: Create .cortexhawk-chains.yml at project root to define your own:

# .cortexhawk-chains.yml
presets:
  api:
    steps: plan,build,test,scan
    description: "API feature pipeline with security scan"
  hotfix:
    steps: debug,build,test,ship
    description: "Quick fix pipeline"
  qa:
    steps: scan,test,review
    description: "Quality assurance pipeline"
    gate: true

Then use: /chain qa auth-module instead of /chain scan,test,review auth-module

Custom presets override built-in presets with the same name. See templates/cortexhawk-chains.yml for a full template.

Agent mapping: plan=planner, build=implementer, test=tester, review=reviewer, scan=security-auditor, debug=debugger, doc=docs-manager, ship=git-manager, refactor=code-simplifier, research=researcher

Agent delegation: Agents can invoke sub-agents mid-chain via @delegate(agent, context, return) — detected by /chain and executed as dynamic sub-steps.

/task command: Execute a backlog item end-to-end — reads docs/backlog.md, chains plan→build→test→review, then ships. Effort-based save rules: L=inline, M/H=save to docs/chains/.

Skills (36)

Domain-specific knowledge modules loaded on demand.

• Security: auth-analyzer, compliance-checker, container-security, dependency-auditor, encryption, incident-response, secrets, security-headers, security-logging, vulnerability-scanner
• DevOps: ci-cd, deployment, docker
• Databases: schema-designer, sql-optimizer
• Testing: e2e-testing, tdd, test-generator
• Quality: complexity-analyzer, error-handling, log-analyzer, pattern-detector
• Meta: mcp-builder, skill-creator
• Frameworks: api-design, sveltekit, fastapi, nextjs, tailwindcss, react, typescript, python
• Optimization: performance
• Workflow: commit, confidence-check, pr-review-comments

Skills support dependency declarations via requires: frontmatter, validated at install time and reported in /pulse.

SkillsMP — Community Skills (87k+)

Search and discover community skills from SkillsMP:

./install.sh --search react          # search 87k+ skills (requires API key)
./install.sh --add-skill user/repo   # install a skill from GitHub
./install.sh --publish-skill skills/my-skill  # publish to GitHub (requires gh CLI)

Set your SkillsMP API key in .env or via --init wizard:

# .env
SKILLSMP_API_KEY=sk_live_...

Without an API key, --search falls back to the local REGISTRY.md.

Skill Packs

Curated skill bundles for common stacks — install multiple skills in one command:

| Pack | Skills | |---|---| | react-app | frameworks/react, frameworks/nextjs, frameworks/tailwindcss, testing/e2e-testing, quality/error-handling | | python-api | frameworks/fastapi, frameworks/python, databases/sql-optimizer, security/auth-analyzer, testing/test-generator | | svelte-app | frameworks/sveltekit, frameworks/tailwindcss, frameworks/typescript, testing/e2e-testing | | devops-full | devops/ci-cd, devops/deployment, devops/docker, optimization/performance, quality/log-analyzer | | security-suite | All 10 security skills | | testing-full | testing/tdd, testing/test-generator, testing/e2e-testing, quality/complexity-analyzer, workflow/confidence-check |

./install.sh --pack react-app
./install.sh --pack security-suite --target kimi

Agent Personas

Create custom agents that inherit from base agents with rule/style overrides:

.cortexhawk-agents/
  strict-reviewer.md    # extends: reviewer — stricter rules
  fast-planner.md       # extends: planner — output format tweaks

Personas use extends: frontmatter and are auto-copied to .claude/agents/ on install/update.

Hooks (11)

Automatic lifecycle hooks that run during Claude Code sessions.

| Hook | Event | Description | |---|---|---| | file-guard | PreToolUse | Blocks access to .env, secrets, credentials | | branch-guard | PreToolUse | Prevents direct push to protected branches | | commit-guard | PreToolUse | Validates conventional commits, checks staged secrets | | lint-guard | PreToolUse | Auto-detects formatters/linters on staged files; auto-fix or check-only | | self-review | PostToolUse | Checks for TODO/FIXME, secrets, debug artifacts | | dependency-check | PostToolUse | Alerts when dependency files are modified | | test-reminder | PostToolUse | Reminds to update tests for modified source files | | agent-analytics | PostToolUse | Tracks agent invocations, tokens, timestamps to docs/.metrics/ | | session-telemetry | SessionEnd | Generates session summary (agents, tokens, duration, files) | | session-start | SessionStart | Project context injection, daily stats display | | post-merge | git post-merge | Auto-runs cleanup after git merge (opt-in native git hook) |

Hook pipelines are configured in hooks/compose.yml. Manage individual hooks:

./install.sh --list-hooks             # show all hooks with status (active/disabled)
./install.sh --enable-hook file-guard # enable a specific hook
./install.sh --disable-hook test-reminder  # disable a specific hook
./install.sh --test-hooks             # dry-run all hooks with synthetic inputs

Modes (7)

Behavioral presets that adapt Claude's responses.

| Mode | Behavior | |---|---| | default | Balanced, clear, actionable | | fast | Minimal tokens, direct answers | | research | Deep analysis, brainstorming | | review | Critical, thorough examination | | orchestration | Multi-agent coordination | | learn | Teaching mode with 3 levels (guided, mentor, professor) | | pair | Alternates implementer/reviewer on each change, max 2 cycles |

Multi-CLI Support

CortexHawk installs on 3 CLI tools:

| Target | Status | Directory | How | |---|---|---|---| | Claude Code (default) | Fully supported | .claude/ | ./install.sh | | Kimi CLI | Experimental | .kimi/ + AGENTS.md | ./install.sh --target kimi | | Codex CLI | Experimental | .codex/ + .agents/ | ./install.sh --target codex | | All at once | — | all of the above | ./install.sh --target all |

Note: Only Claude Code is fully supported. Kimi and Codex targets are experimental — some features are adapted to each CLI's architecture.

Each target adapts components to the CLI's native format:

| Component | Claude Code | Kimi CLI | Codex CLI | |---|---|---|---| | Agents (20) | .claude/agents/*.md | Skills (/skill:agent-*) + AGENTS.md | AGENTS.md | | Commands (35) | .claude/commands/*.md → /plan | Skills (/skill:cmd-*) | Skills ($cmd-*) | | Skills (36) | .claude/skills/ | .kimi/skills/ (auto-discovered) | .agents/skills/ | | Hooks (11) | settings.json (automatic) | Skills (/skill:hook-*, manual) | Dispatcher (partial) | | Modes (7) | .claude/modes/ (native) | Skills (/skill:modes/*) | Skills ($mode-*) | | MCP | settings.json | Optional (MCP-SETUP.md) | config.toml |

Installation Management

# Update to latest version (checksum-based detection, preserves customizations)
./install.sh --update
./install.sh --update --force          # force even if up to date

# Getting started
./install.sh --quickstart              # post-install guide (5 things to try)
./install.sh --demo                    # sandbox project with intentional bugs

# Simulate without writing files
./install.sh --dry-run                 # preview install
./install.sh --update --dry-run        # preview update delta

# Diagnostics
./install.sh --version                 # show CortexHawk version
./install.sh --doctor                  # check installation health
./install.sh --test-hooks              # dry-run all hooks with synthetic inputs
./install.sh --stats                   # installation overview (version, counts)

# Snapshots
./install.sh --snapshot                # save installation state
./install.sh --snapshot --portable     # self-contained .tar.gz archive
./install.sh --snapshots               # list all snapshots
./install.sh --restore <file>          # restore from snapshot
./install.sh --restore --latest        # restore most recent
./install.sh --diff <file>             # compare current vs snapshot
./install.sh --diff <a> <b>            # semantic diff between two snapshots

# Uninstall
./install.sh --uninstall               # clean removal (creates snapshot first)
./install.sh --uninstall --force       # skip confirmation

# Community skills
./install.sh --add-skill user/repo     # install from GitHub

Team Sharing

# Export current config as team preset
./install.sh --export-team             # generates .cortexhawk-team.yml
./install.sh --export-config           # alias for --export-team

# Install from team config
./install.sh --team                    # reads .cortexhawk-team.yml
./install.sh --import-config           # alias for --team

Team members can override with .cortexhawk-local.yml.

Docs Workspace

install.sh creates a docs/ directory for persisting agent outputs across sessions.

| Directory | Agent | Command | |---|---|---| | docs/brainstorms/ | brainstormer | /brainstorm | | docs/plans/ | planner | /plan | | docs/decisions/ | journal-writer | /journal | | docs/research/ | researcher | /research | | docs/audits/ | security-auditor | /scan | | docs/conversations/ | — | /export | | docs/chains/ | chain agents | /chain, /task | | docs/.context/ | all agents | /context, (auto — agent memory) | | docs/.metrics/ | analytics hooks | (auto — JSONL telemetry) |

Files are saved as YYYY-MM-DD-[topic].md. Agent memory files in .context/ are free-form markdown, created automatically.

Post-Install Security Audit

After installation, CortexHawk runs a lightweight security audit on your project:

1. .gitignore covers .env
2. No .env files committed to git
3. No hardcoded secrets in source files
4. Dependency vulnerabilities (npm audit / pip-audit if available)
5. No sensitive files tracked (.pem, .key, id_rsa, etc.)

Warnings only — never blocks installation. Skip with --no-scan. Run /scan for a full AI-powered audit.

Benchmark Framework

tests/ contains synthetic repos and agent expectations for validating agent output quality.

| Directory | Purpose | |---|---| | tests/fixtures/ | 3 synthetic repos with intentional bugs and security flaws | | tests/expectations/ | JSON checklists per agent (required sections, keywords, forbidden patterns) |

Run bash scripts/benchmark.sh to validate fixture integrity and expectation schemas.

Philosophy

• Open-source and free forever
• Optimized prompts — no verbosity eating your context
• Modular — install only what you need
• Framework agnostic — works with any stack
• Community-driven — PRs welcome

Contributing

See CONTRIBUTING.md for guidelines, templates/ for creating new components, and TROUBLESHOOTING.md for common issues.

License

MIT License — see LICENSE for details.