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 thirteen skills: clean-branches, code-simplifier, commit, generate-wiki, github-skills-pdf, help, hud, learning, local, my-weekly, one-by-one, pair-write, pr.

Version 7.5.0 groups skills by purpose. Invocation names stay unchanged:

Directory under plugins/smart/skills/	Skills
git/	commit, pr, clean-branches
coding/	code-simplifier, learning, one-by-one, pair-write
docs/	generate-wiki, github-skills-pdf, my-weekly
utilities/	hud, local
help/	help stays at the root

Each skill keeps its own resources. Help reads both directory levels dynamically.

Some workflows require Git, gh, glab, 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 commit workflow to one low-reasoning Luna worker.
• 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.

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.
• Skill Guide — /smart:help lists every skill, including itself, with one short sentence about its capability and purpose. Legacy arguments still show the full guide.
• 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; after upstream updates it prints only the changed chapters as an update pack.
• 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:code-simplifier [paths-or-diff]	Use one fresh-context worker to simplify recent code while preserving observable behavior
/smart:generate-wiki	Distill source material into a guarded GitLab, GitHub, or local Wiki
/smart:github-skills-pdf <repo> [full=true]	Build a verified English-Chinese A4 handbook from a GitHub skills repository; once printed, later runs print only changed chapters unless full=true
/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	Show every skill with a one-sentence explanation of its capability and purpose
/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 workflow to one low-reasoning worker on the latest Luna model and relays its result; the worker never delegates again.

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
• 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