Freeflow

A feedback-based control system for coding agents.

Freeflow gives the coding agent you already use (Codex, Claude Code, Pi and others) what it needs at the moment it decides. On every host its prompts and skills work as a portable layer; on Pi a native extension adds the runtime parts.

• A short method, always loaded. One cycle: agree before building, build and verify, review and hand over. Each step checks what actually happened (a script's output, a test, your answer) before the next one, rather than trusting the plan.
• Ten capability skills that bring scripts and structured artifacts, not just advice: a script that maps what a change touches, a self-review report, a decision list for your choices, a Working Record that survives context loss.
• On Pi, a runtime that pushes the right lines of a skill at the tool call that needs them, and adds compaction, tool handling, task memory and multi-model routing.

The agent keeps its own tools, permissions and execution. Freeflow does not grant permission, enforce a pipeline, or replace your repository's instructions, tests or review.

• New to Freeflow? Read Using Freeflow Effectively and How Freeflow Works.
• Installing it? Start with Getting Started.

Why

Agents often act without opening the skill that describes the step they are taking. In Freeflow's own runs, the old Workflow and Action Selection skills were rarely opened, so their guidance rarely reached the work. Version 0.9.0 is built around that finding. The few rules that must always hold live in a short always-loaded prompt; each skill's description says when it applies; and the skills hand the agent facts and checks (script output, a list of choices, a review brief) instead of more prose to remember.

How it works

1. Agree             before the first edit on a task that builds or changes behavior:
                     what I'll do, where I stop, your decisions with defaults; wait
2. Build and verify  within the agreement; check on the path you will use
3. Review, hand over self-review; independent review when the gate calls for it;
                     report what done looks like against what was done
When evidence changes the picture, go back only to the step it affects.

A question gets an answer, an exact one-line edit gets made, and a large change gets the whole cycle. Only your request or a still-valid approval authorizes work; commit, push and release each need their own yes.

Skills

Version 0.9.0 replaced twenty-five skills with these ten; removed names have no aliases. What changed in 0.9.0 says where each one went.

Commands

Natural language works: the agent opens the skill whose description matches. A direct call helps when it makes the intended method clear. A skill is a method, not a permission.

Skill commands on Pi (Claude Code uses /freeflow:<skill>, Codex a skill mention):

/discuss-work
/execute-work
/verify-work
/review-work
/deliver-work
/track-work
/write-docs

Contributor calls:

/setup-freeflow
/write-skill
/evaluate-behavior

Native Pi controls:

/freeflow
/freeflow status
/freeflow settings
/freeflow settings session
/freeflow settings local
/freeflow settings repo
/freeflow profile coordinator
/freeflow profile helper
/freeflow profile executor
/freeflow profile auto
/freeflow profile history
/freeflow resume
/freeflow compact
/freeflow task
/freeflow project

Profile changes and resume require an idle host. These commands do not prove installed-host delivery or authorize task work.

Host support

Freeflow owns its prompts, skills, capability source, host adapters and the Pi extension. Each host owns launch, package installation, session state, trust and updates.

Pi capabilities

Native fixtures and live sessions exercise these capabilities; their effect on task results, cost and long real use is not yet measured. Freeflow's Pi extension also keeps request history cache-friendly and has a qualified effort-history route for gpt-6-astra, gpt-6-luna and gpt-6-sol; that is request-construction behavior, not proof of a provider cache hit or a billing reduction (Pi cache reuse boundaries).

Quick start

For complete instructions and delivery checks, use Getting Started.

Codex

codex plugin marketplace add https://github.com/hassan-mohiddin/freeflow.git
codex plugin marketplace upgrade freeflow
codex plugin add freeflow@freeflow

Trust the Freeflow hook from /hooks, then start a new session.

Claude Code

/plugin marketplace add hassan-mohiddin/freeflow
/plugin install freeflow
/reload-plugins

Gemini CLI

gemini extensions install https://github.com/hassan-mohiddin/freeflow

Restart Gemini CLI after installation or updates.

Cursor, GitHub Copilot, VS Code, Kiro, OpenCode, and Hermes

These hosts consume the root Agent Plugins 1.0 manifest and canonical skills/ surface through their documented plugin or skill-source workflows. Copilot CLI can install directly:

copilot plugin install hassan-mohiddin/freeflow

OpenCode can point its skills array at the installed package's skills/ directory. Hermes can install the portable package with:

hermes plugins install hassan-mohiddin/freeflow --no-enable
hermes plugins enable freeflow

See Getting Started for host-specific claims and limits.

Pi

pi install npm:@hassangameryt/freeflow

Or:

pi install git:github.com/hassan-mohiddin/freeflow

Restart Pi or use /reload after installation or updates.

Activate a repository

Run:

/setup-freeflow

This creates the required shared .freeflow/config.json activation boundary. Minimal activation is {}. Optional .freeflow/local.json personal overrides cannot activate Freeflow alone. Configuration or installation alone does not establish runtime delivery; setup reports delivery as confirmed, unavailable or unconfirmed.

Use Freeflow effectively

A clear prompt for consequential work names:

Outcome: what should be true?
Scope: what may change?
Exclusions: what must not happen?
Sources and constraints: what governs?
Evidence: what should support the result?
User-owned choices: what must come back to me?
Stop and return: where should the agent stop?

Natural language is preferred. Answer the agent's agreement with "go" to accept its defaults, or correct the line you disagree with. Read Using Freeflow Effectively for prompt examples, steering the agreement, Track Work, settings, Cognitive Routing modes and presets, cache and cost boundaries, and troubleshooting.

Evidence and limits

Freeflow is explicit about what observations prove:

• deterministic checks can establish source structure, prompt assembly, schemas, package boundaries, and named fixtures;
• package shape does not prove native host dispatch, trust UI, or marketplace availability;
• request-prefix compatibility does not prove a provider cache hit;
• model/profile availability does not prove quality or cost improvement;
• local release preparation is not publication;
• publication is not production deployment.

Documentation

• Using Freeflow Effectively
• How Freeflow Works
• Getting Started
• Settings
• Capabilities
• Pi integration
• Architecture
• System prompt architecture
• Skill routing
• Release process
• Release evidence
• Changelog
• Contributing

For local Pi extension development, refresh a development snapshot only from a committed Freeflow revision with npm run snapshot:refresh. A snapshot is not a production install or release.

What Freeflow is not

• Not a new agent or workflow engine.
• Not a rigid phase pipeline.
• Not a permission or enforcement framework.
• Not a replacement for repository instructions, tests, policies, or review culture.
• Not proof that a configured model, cache path, or candidate is behaviorally ready.

License

MIT License. Copyright (c) 2026 Hassan Mohiddin.