iroko

My Claude Code configuration. 25 components I use every day across 4 production SaaS projects.

Named after the West African hardwood: durable, solid, the foundation everything else builds on.

npx @james10192/iroko init

What you get

| Type | Count | What it does | |------|-------|-------------| | Rules | 5 | Loaded in every conversation. Shape how Claude behaves. | | Skills | 15 | Slash commands: /commit, /plan-and-confirm, /find-doc... | | Agents | 3 | Specialized subagents for review, research, search. | | Hooks | 2 | Automatic triggers on session events. | | Sounds | 2 | MP3 notifications when Claude finishes or needs input. |

Release notes live in CHANGELOG.md.

Rules

Rules are always active. You don't invoke them, they just work.

| Rule | What it does | |------|-------------| | pre-commit-quality-gate | Audits every commit on 4 axes: architecture, quality vs speed, production-readiness, SOLID. Blocks if critical issues found. | | parallel-agents | Enforces max 4 parallel agents, launched in a single message. Synthesize results, don't relay. | | token-efficiency | When to use agents (multi-file exploration) vs direct tools (Grep, Glob, Read). Saves context. | | use-available-tools | Always check docs via ctx7 CLI before coding with external APIs. Never guess. | | marcel-global-preferences | Personal config: pnpm, French UI, no AI slop. Deselect during init unless you share these preferences. |

Skills

Type /command in Claude Code. These are the commands I built.

| Skill | What it does | |-------|-------------| | /commit | Quality-gated commit. Runs the 4-axes audit on your diff, generates a conventional message, pushes. Blocks on critical issues. | | /plan-and-confirm | Ultraplan v3 — depth-variable (1–5) planning pipeline. Auto-detects complexity, runs up to 5 parallel agents (critic + research + Devil's Advocate), presents alternatives with confidence scores, premortem, and the 5 ultrathink lenses. Waits for explicit OKAY before any code. | | /find-doc | Looks up library documentation via ctx7 CLI, Context7 MCP, and WebSearch. Use before writing code with any external API. | | /linkedin-post | Generates a LinkedIn post from your current work context: git history, conversation, tech trends. Publishes via MCP if configured. (optional) | | /visual-check | Opens dev-browser (sandboxed Chromium), navigates to a URL, takes screenshots to verify your implementation visually. | | /create-pr | Creates a PR with auto-generated title and structured description. Analyzes the full diff, not just the last commit. | | /create-issue | Creates a GitHub issue with labels, scope detection, and epic linking. | | /worktree-start | Starts isolated work on a GitHub issue using a git worktree. Issue number to branch to worktree in one command. | | /worktree-finish | Cleans up after a worktree PR is merged. Removes the worktree directory and local branch. | | /merge | Merges branches with context-aware conflict resolution. Reads the PR, understands the feature, resolves conflicts. | | /fix-errors | Fixes all ESLint and TypeScript errors using parallel agents. Groups errors by file area, max 5 per agent. | | /fix-grammar | Fixes grammar and spelling in one or multiple files while preserving formatting. | | /fix-pr-comments | Fetches all unresolved PR review comments and implements the requested changes. | | /npm-publish | Bumps version, builds, publishes to npm, creates a git tag, pushes. One command for a full release. (optional) | | /convex-cli | Initializes and manages Convex projects non-interactively. For Convex users only. (optional) |

Agents

Subagents used by skills under the hood. You can also invoke them directly via the Agent tool.

| Agent | What it does | |-------|-------------| | critic | Technical reviewer. Auto-detects which lenses to apply: CTO, UX, Security, Performance, Cost. Gives a verdict: PROCEED, RETHINK, or REJECT. | | explore-docs | Documentation research via ctx7 CLI (primary), Context7 MCP (fallback), WebSearch (complement). | | linkedin-post | Content generation agent for LinkedIn. Positions as expert, never as learner. Respects reputation rules. |

Hooks

Triggered automatically by Claude Code session events.

| Hook | Trigger | What it does | |------|---------|-------------| | monitor-session | Stop, Permission, Notification | Monitors session state, sends notifications via OpenClaw/Telegram. | | notify-workflow | PostToolUse (Bash) | Sends a notification after Bash command execution completes. |

Use cases

| Workflow | Components | |----------|-----------| | Before coding | /find-doc, explore-docs agent | | During coding | /visual-check, /fix-errors | | Before committing | /commit (quality gate), critic agent | | Collaboration | /create-pr, /create-issue, /worktree-start, /worktree-finish, /merge, /fix-pr-comments | | Content (optional) | /linkedin-post — requires LinkedIn MCP or typefully-cli | | Publishing (optional) | /npm-publish, /convex-cli | | Always active | Rules (quality gate, parallel agents, token efficiency, tool usage) | | Notifications | Sounds (finish.mp3, need-human.mp3) — cross-platform |

The quality gate

The /commit skill blocks commits that fail a 4-axes audit:

| Axis | Checks | Blocks if | |------|--------|-----------| | Architecture | God class, mixed responsibilities | File >300 lines with 3+ concerns | | Quality | N+1 queries, debug code, duplication | dd(), console.log in the diff | | Production | Exposed stack traces, unprotected routes | Traces in JSON responses, routes without auth | | SOLID | Liskov violations, hardcoded roles | Contract broken in an override |

PASS = commit. WARN = show warnings, ask confirmation. BLOCK = fix first.

Skipped for trivial diffs: markdown, config, less than 5 lines changed.

Notification sounds

Two MP3 files that play when Claude Code triggers hooks:

• finish.mp3 plays when Claude completes a task (Stop hook)
• need-human.mp3 plays when Claude needs your input (Notification hook)

Adapted from AI Blueprint's Mac-only afplay pattern. This version works cross-platform: PowerShell on Windows, afplay on Mac, paplay on Linux. See song/README.md for setup.

Auto-update

iroko checks npm for new versions on every run. If an update is available:

  Update available 1.4.0 → 2.0.0
  Run pnpm add -g @james10192/iroko@latest to update

iroko update pulls the latest config files from GitHub and re-installs your selected components.

Install

Option 1: npx (no install)

npx @james10192/iroko init

Option 2: global install

pnpm add -g @james10192/iroko
iroko init

Option 3: Claude Code plugin

/plugin marketplace add James10192/iroko
/plugin install iroko@iroko

Option 4: manual

git clone https://github.com/James10192/iroko.git
cp -r iroko/rules/* ~/.claude/rules/
cp -r iroko/skills/* ~/.claude/skills/
cp -r iroko/agents/* ~/.claude/agents/
cp -r iroko/hooks/* ~/.claude/hooks/

Commands

iroko init      # Interactive setup — select components to install
iroko list      # Show installed vs available components
iroko update    # Pull latest from GitHub and re-install
iroko --help    # All commands

The installer shows an interactive checklist grouped by type. Everything is selected by default. Deselect what you don't need.

Recommended plugins

Tools I use alongside iroko. Not bundled, install them separately.

| Plugin | Author | What it does | |--------|--------|-------------| | AI Blueprint | Melvynx | APEX workflow, ralph-loop autonomous coding, ultrathink deep thinking, oneshot fast implementation | | Impeccable | Paul Bakaus | Design quality and adaptation skills | | Superpowers Laravel | JP Caparas | 50+ Laravel patterns: TDD, controllers, policies, queues, Horizon | | Claude Plugins Official | Anthropic | feature-dev, pr-review-toolkit, code-review, frontend-design, vercel, slack |

claude plugins add anthropics/claude-plugins-official
claude plugins add pbakaus/impeccable

Structure

iroko/
├── .claude-plugin/       Plugin marketplace manifest
├── src/                  CLI source (TypeScript)
├── rules/                5 global rules
├── skills/               15 slash commands
├── agents/               3 subagents
├── hooks/                2 event hooks
├── song/                 Notification sounds (cross-platform)
└── templates/            settings.json template

Context

Built by Marcel DJEDJE-LI in Abidjan, Cote d'Ivoire. Used daily on:

• KLASSCI : multi-tenant school management SaaS (Laravel, 5 tenants, 3000+ students)
• MailPulse : email marketing platform (Next.js 16, Convex, Resend)
• E-pagne : collaborative savings fintech (Next.js, Convex)

This is the result of months of daily iteration with Claude Code on production software.

License

MIT