smart-codex-plugin

🌐 English | 简体中文

Finished coding? Run /smart:commit in Claude Code or $smart:commit in Codex.

A dual-host plugin for Claude Code and Codex with focused developer workflows, content tools, session utilities, and engineering rules.

---

Quick Start

The plugin ships both manifests (.claude-plugin/ for Claude Code and .codex-plugin/ for Codex), so it installs natively in either host. Pick yours:

Claude Code

Add the marketplace, then install the plugin — run these inside Claude Code:

/plugin marketplace add hinson0/smart-claude-code-plugins
/plugin install smart@smart

Already cloned locally? Point the marketplace at your clone instead: /plugin marketplace add /path/to/smart-claude-code-plugins. After installing, restart the session so skills, hooks, and the statusline load.

Codex

The friendliest way is right inside a Codex session — no clone needed:

1. Run /plugins
2. Select [Add Marketplace]
3. Paste the source — hinson0/smart-claude-code-plugins (owner/repo) or the full git URL — and press Enter
4. Open the Smart marketplace, then install the smart plugin

Prefer the CLI? It fetches straight from Git — no clone needed:

codex plugin marketplace add hinson0/smart-claude-code-plugins
codex plugin add smart@smart

---

Plugin in This Marketplace

This repository publishes one dual-host plugin:

Plugin	Install	Purpose
Smart	smart@smart	Developer workflows, PDF/Wiki tools, weekly reports, and session utilities

Claude Code uses /smart:*; Codex exposes the corresponding $smart:* skills.

# Claude Code, after adding the marketplace
/plugin install smart@smart

# Codex, after adding the marketplace
codex plugin add smart@smart

Smart includes fifteen skills: clean-branches, close-issue, code-simplifier, commit, generate-wiki, github-skills-pdf, help, hud, learning, local, matt-implement-all-tickets, my-weekly, one-by-one, pair-write, pr. Some workflows require Git, gh, glab, Node.js, Python/PDF tooling, browser access, or document capabilities; each skill checks its own prerequisites. commit and pr allow model invocation on both hosts. All other skills are user-invoked only: start them explicitly with their /smart:* or $smart:* names. Codex displays each skill as smart:<name>, preserving its Claude Code invocation name without the leading slash or a separate title.

---

Features

Smart Commit

• Low-Cost Execution — Claude Code uses Haiku; Codex delegates the complete commit workflow to one low-reasoning GPT-5.6 Luna worker, with one default-subagent fallback.
• Semantic Grouping — Type is a hard boundary and purpose is a soft boundary, so independent changes become independent commits.
• Repository-Aware Messages — Respects project rules, recent Git history, then Conventional Commits.
• Commit Only — No CI checks, version changes, push, or pull request creation.

Protection & Automation

• Session Hooks — Greet on session start (via macOS say TTS).
• Session Logs — Every tool call is logged to .smart/session-logs/ with full input data for post-session debugging and audit.
• Serial Ticket Delivery — /smart:matt-implement-all-tickets, explicitly loaded with Matt /implement, keeps one orchestrator session while fresh workers implement, verify, record, and close the current /to-tickets output one Ticket at a time. It supports configured GitHub, GitLab, and local Markdown trackers and stops on the first incomplete closeout.
• Auditable GitLab Issue Closeout — After /implement has committed and reviewed the work, /smart:close-issue verifies the implementation commit on the current branch, acceptance evidence, and review conclusion. With explicit close authorization, it publishes those development assets before closing; target-branch integration is disclosed but is not a close gate. It uses glab and never implies push, merge, MR/PR creation, checklist edits, or label changes.

Utilities

• HUD / Statusline Installer — One command to install a feature-rich statusline showing model, git branch, context usage, rate limits, system stats, and tool call counts. Two install levels (minimal / full) plus restore from backup, user scope.
• Help Overview — /smart:help dynamically scans and lists all skills, hooks, and agents with descriptions.
• Fresh-Context Code Simplification — /smart:code-simplifier sends the complete run to one serial, non-recursive worker with no conversation history. The primary stays out of the target code while the worker scopes recent changes, follows repository standards, and proves behavior equivalence.
• One-Cycle TDD — /smart:one-by-one validates one minimal Red test, then guides the user through the matching Green implementation.
• Pair Writing — /smart:pair-write gives one user-written coding step a comment skeleton and directly expanded reference, then checks only transcription and agreement with that guidance by default.
• Wiki Generation — /smart:generate-wiki turns source material into a GitLab, GitHub, or local Markdown Wiki with guarded publishing.
• Bilingual Skills PDF — /smart:github-skills-pdf pins a GitHub skills repository and builds a verified English-Chinese A4 handbook.
• Personal Weekly Report — /smart:my-weekly summarizes the current user's commits for a selected natural week.
• Bundled Coding Rules — Pre-written rule files (e.g. Pydantic V2 standards) in rules/. Symlink any file to your project's .claude/rules/ to activate it.
• Learning Mode — /smart:learning 1 enables a persistent user-writes, agent-reviews loop; 0 disables it and no argument shows status. Only the managed block in .claude/CLAUDE.local.md is changed.

---

Usage

💬 Explicit invocation — every skill starts only when you name it: /smart:* in Claude Code or $smart:* in Codex.

⌨️ Skill commands — replace /smart: with $smart: in Codex:

Command	What it does
/smart:commit	Stage & commit only (smart grouping, auto message)
/smart:pr [branch]	Create or update a PR; omitted branch requires confirmation of main, explicit branch skips confirmation; no auto-merge
/smart:clean-branches [branch]	Delete local and remote branches fully merged into the target; omitted target requires confirmation of main; protected and checked-out branches are kept
/smart:close-issue <IID-or-URL>	Check one GitLab Issue read-only; with explicit close authorization, publish an auditable development asset note and then close it
/smart:code-simplifier [paths-or-diff]	Use one fresh-context worker to simplify recent code while preserving observable behavior
/smart:matt-implement-all-tickets	With Matt /implement explicitly loaded, implement and close the current /to-tickets output serially
/smart:generate-wiki	Distill source material into a guarded GitLab, GitHub, or local Wiki
/smart:github-skills-pdf [--notes 2|4]	Build a verified English-Chinese A4 handbook from a GitHub skills repository
/smart:hud [0|1|2|reset|normal|all]	Install statusline (1/normal=minimal, 2/all=full) or restore backup (0/reset), user scope
/smart:help [skill|hook|agent]	Show overview of all plugin components (or filter by category)
/smart:learning [0|1]	Persistent learning mode: 1 enables, 0 disables, empty shows status; the user writes and the agent reviews one step at a time
/smart:local	Create a git-ignored personal configuration file without overwriting existing notes
/smart:my-weekly <repo> [-N]	Summarize the current user's commits for a selected natural week
/smart:one-by-one	Run one minimal Red-to-Green cycle at a time
/smart:pair-write	Guide one user-written step, then compare the landed code with its skeleton and reference

---

Smart Commit

commit and pr allow implicit invocation in Codex metadata. clean-branches still requires explicit user invocation.

/smart:commit reads status, staged and unstaged diffs, untracked file contents, and recent history; splits by type and independent purpose, including hunks within a file; and lists each group’s message and files before committing.

Claude Code runs the turn on haiku. Codex delegates the complete workflow to one low-reasoning gpt-5.6-luna worker. If Luna is unavailable, it retries once with the user's configured default subagent. The primary agent never performs grouping or commit work itself.

Every group stages only explicit paths or hunks and verifies its staged diff before committing; bulk staging is prohibited. The skill reports commit hashes, messages, and remaining changes. It never runs checks, changes versions, pushes, or creates pull requests.

---

Bundled Rules

The plugin ships pre-written coding rule files in rules/. Activate any rule in your project by symlinking it to .claude/rules/:

ln -s /path/to/plugin/rules/pydantic-v2.md .claude/rules/pydantic-v2.md

Available rules:

Rule file	What it enforces
pydantic-v2.md	Pydantic V2 standards: ConfigDict, validators, discriminated unions, TypeAdapter, RootModel, SecretStr, pydantic-settings, V1→V2 migration
python-3.14.md	Python 3.14 standards: deferred annotations, [T] generics, @override, Self, TaskGroup, StrEnum, datetime.UTC, subinterpreters, match guards
fastapi.md	FastAPI 0.115+ standards: Annotated dependencies, lifespan, APIRouter organization, BackgroundTasks, dependency_overrides, security scopes
sqlalchemy-v2.md	SQLAlchemy 2.0 standards: DeclarativeBase, Mapped[T], naming conventions, async sessions, AsyncAttrs, selectinload, UPSERT, Alembic

Rules are inactive by default — symlink only what's relevant to your project.

---

HUD (Statusline)

Install a feature-rich statusline with one command:

/smart:hud

What it shows (6 lines):

Line	Content
1	Session ID / session name, model-effort@version, total cost (USD)
2	Directory, git branch (dirty/ahead/behind/stash), last commit time, worktree name, battery
3	Context progress bar + tokens + cache, rate limits (5h/7d) with reset countdown, session duration, agent name
4	CPU, memory, disk, uptime, runtime versions (Node/Python/Go/Rust/Ruby), local IP
5	Tool call stats (Bash/Skill/Agent/Edit counts, parsed from transcript in real time)
6	Output style, vim mode (shown only when enabled)

Commands:

Command	Action
/smart:hud · /smart:hud 1 · /smart:hud normal	Install minimal statusline (session + ctx only) to user scope, auto-backup
/smart:hud 2 · /smart:hud all	Install full statusline (all 6 lines)
/smart:hud 0 · /smart:hud reset	Restore your previous statusline from backup

Note: Cross-platform (macOS + Linux/WSL/Ubuntu) — auto-detects the OS and picks the right tools for battery, CPU, memory, and IP. Requires jq; if it's missing, /smart:hud auto-installs it (apt/dnf/pacman/apk/brew).

---

Session Hooks

The plugin includes hooks that trigger at session boundaries and tool calls:

Hook	Trigger	What it does
greet.sh	SessionStart	Plays a welcome message via macOS TTS (say)
session-logs.py	PreToolUse (all tools)	Logs every tool call's full input to .smart/session-logs/<date>/<session_id>.json

The bundled hook config uses ${CLAUDE_PLUGIN_ROOT} for path resolution in Claude-compatible hosts. TTS hooks run in the background (nohup &) to avoid blocking the host process.

---

Requirements

• Claude Code or Codex (with plugin support) — the plugin ships both manifests and runs natively in either
• git
• Matt Pocock Skills with /implement — required by /smart:matt-implement-all-tickets
• gh CLI — for /smart:matt-implement-all-tickets with GitHub Issues
• glab CLI — for /smart:close-issue and /smart:matt-implement-all-tickets with GitLab Issues
• Node.js — for closeout scripts
• Python 3 with reportlab and an embeddable CJK font — for /smart:github-skills-pdf
• jq — for HUD statusline only (optional otherwise)

---

Author

Hinson · GitHub

License

MIT