Stay fluent in the code your AI agent writes. FluencyLoop turns each feature into a documented design, teaches the decisions at your level, tracks the rationale, and produces a reviewer-ready summary. A private knowledge base keeps that teaching calibrated across features.
The code and your fluency in it are produced together, or not at all.
Initialize the project once, then run one feature loop per branch. Use plan only when the work is too large for a single feature.
| Step | Claude Code | Codex | What it does |
|---|
- Initialize |
fluencyloop init|fluencyloop init| Creates the project state and an empty constitution. Plan and feature also do this automatically if needed. | - Plan (optional) |
/fluencyloop:plan <initiative description>|$fluencyloop:plan <initiative description>| Designs the architecture and breaks a large initiative into feature-sized tasks. | - Build + learn |
/fluencyloop:feature <feature description>|$fluencyloop:feature <feature description>| Creates a feature branch and design, builds in slices, teaches each real decision, and journals it. | - Review |
/fluencyloop:review|$fluencyloop:review| Assembles the branch's sessions and decisions into a reviewer-facing PR view. |
For normal-sized work, the practical path is init → feature → review. For a large initiative, run plan first, then repeat feature → review for each task in its roadmap.
If work was merged without the loop, use /fluencyloop:backfill
in Claude Code or
$fluencyloop:backfill
in Codex to reconstruct and verify its design and decisions.
The constitution is a short set of checkable engineering principles for the project. It starts from the first real plan or feature and grows when a decision reveals a repeatable stance. Every later design and review is checked against it, but it never blocks a conventional merge.
FluencyLoop teaches at the moment a meaningful decision is made. It explains the mechanism, the reason for the chosen path, and the rejected alternative, then checks that the explanation landed before continuing when the topic is unfamiliar.
It maintains a private, per-developer knowledge base of domain familiarity and demonstrated engagement. That profile carries across projects and features, keeping explanations concise on familiar ground and deeper where knowledge is still forming. It is never committed to a project; only person-neutral knowledge-transfer notes about the software enter the documentation.
Plans, Mermaid design diagrams, feature sessions, and review summaries live beside the code under
docs/fluencyloop/
. They are created from the actual branch and its changes, so documentation is produced during delivery rather than reconstructed after context has been lost.
Each real fork records what was chosen, where it applies, why it was chosen, which alternative was rejected, how it relates to the constitution and design, and whether the rationale was verified. Reviewers get the decisions that shaped the feature instead of only a list of changed files.
docs/fluencyloop/
├── constitution.md
├── plans/<initiative>/plan.md
└── features/<feature>/
├── design.md
└── sessions/*.md
.fluencyloop/
contains project workflow state. The per-developer calibration profile lives in
~/.fluencyloop/
; it controls teaching depth and is never committed. Session documents describe the work, never the person.
/plugin marketplace add baokhang83/fluencyloop
/plugin install fluencyloop@fluencyloop
Use the namespaced slash commands shown above. The plugin bundles its deterministic CLI, so there is no separate system-wide FluencyLoop installation.
Claude Code updates and Windows approvals #
FluencyLoop's startup hook checks its own marketplace on each new session and, when an update is
available, installs it for the next session without changing the active one. Run
/reload-plugins
to activate it in the current session instead. The check runs at startup only; resuming, clearing, or compacting a session does not repeat it.
To update at any time by hand, run /plugin marketplace update fluencyloop
, then
/plugin update fluencyloop@fluencyloop
, and finally /reload-plugins
.
The startup check is best-effort and deliberately silent, because a session must never fail to
start over an update it could not fetch. If the claude
CLI is absent from the PATH
, or the
network or a policy blocks the marketplace, the session starts normally and reports nothing. Run
claude plugin list
to see the version you are actually running, and use the manual commands above if it looks stale.
Claude Code's own Enable auto-update toggle (/plugin
→ Marketplaces → fluencyloop) is a separate control that stays off by default. FluencyLoop refreshes only its own package and does not read or change that setting.
On native Windows, use the project-scoped setup in Claude Code approvals to reduce routine FluencyLoop, editing, and read-only Git prompts without granting broad Git or Bash access.
codex plugin marketplace add baokhang83/fluencyloop
codex plugin add fluencyloop@fluencyloop
Use the $fluencyloop:<stage>
skills shown above. The plugin maintains its own fluencyloop
command shim on macOS, Linux, Git Bash, and WSL; no separate runtime installation is required.
Codex updates #
Codex asks you to review FluencyLoop's startup hook once. Approve it from /hooks
to enable automatic updates. Each new session checks only FluencyLoop's marketplace and, when an update is available, installs it for the next session without changing the active one.
Like the Claude Code check, this one is best-effort and silent: an unapproved hook, a missing
codex
CLI, or a blocked marketplace leaves the session running its current version without
reporting anything. Run fluencyloop version
to see the version the Codex install is actually
running. To update by hand, run codex plugin marketplace upgrade fluencyloop
, then
codex plugin add fluencyloop@fluencyloop
; the next session picks it up.
FluencyLoop requires Claude Code or
Codex, git
, and either Bash on macOS/Linux/Git Bash/WSL
or PowerShell (pwsh
) on native Windows.
Read MANIFESTO.md for the product principles, calibration and privacy model, and the boundary between deterministic tooling and agent reasoning. See CONTRIBUTING.md for the repository layout, test commands, and distribution notes.