Freeflow

A feedback-based control system for coding agents.

Memory. Context. Compute.

Freeflow helps coding agents do consequential work without turning every task into a rigid ceremony. It gives the active agent a clear Interaction Contract, one adaptive Workflow, durable task memory, focused engineering methods, and controlled delivery boundaries.

The host agent still owns tools, permissions, and execution. Freeflow helps it understand the request, choose the right next action, preserve continuity, use evidence honestly, place compute deliberately, and know when to continue, ask, defer, or stop.

• New to Freeflow? Read Using Freeflow Effectively.
• Installing it? Start with Getting Started.
• Using Cognitive Routing? Read the detailed Cognitive Routing reference.
• Using Freeflow on Pi? Read Tool Execution and Compaction.

Memory · Context · Compute

The former Freeflow Context (freeflow_context, /freeflow context), Context Virtualization, and Conversation History surfaces are removed as a breaking change. Context Control v2 is planned but unavailable in this release; it does not replace those operations yet. See the Unreleased changelog for the required config-key cleanup.

Selected OpenAI model cache-aware reuse

Freeflow's Pi extension includes cache-aware request history and a qualified effort-history adapter for selected GPT-6 models: gpt-6-astra, gpt-6-luna, and gpt-6-sol.

• compatible Freeflow-generated state stays at stable historical positions where possible;
• changed runtime state is appended instead of rewriting earlier generated context;
• supported OpenAI Responses and OpenAI-Codex Responses routes can retain a request-level effort baseline and insert trusted effort changes at validated historical positions;
• unsupported or uncertain requests fall back to the untouched native request.

The adapter uses freeflow-openai-effort-v1. Older freeflow-astra-effort-v1 entries remain in native session history but are not replayed; no migration is provided. This is request-construction and compatibility behavior—not proof of a provider cache hit, billing reduction, model quality improvement, or universal provider support. See the Pi cache reuse boundaries.

Why Freeflow

Coding agents commonly fail at control boundaries:

How it works

Freeflow uses one active agent and one adaptive Workflow:

Interaction Lifecycle
└─ Workflow Feedback Loop
   ├─ interpret authority and establish the work agreement
   ├─ choose the narrowest current owner
   ├─ discuss, act, test, or observe
   ├─ determine what the evidence supports
   ├─ self-review the supported result
   └─ continue, correct, diagnose, ask, defer, or stop

Focused methods own different results: Discuss, Track Work, Execute Work, Diagnose Failure, Verify Work, Review Work, Review Artifact, Write Spec, Write Plan, Release Work, and others. They compose when their conditions apply; they are not mandatory phases.

On a qualified native Pi host, automatic Cognitive Routing sits inside the current Workflow owner:

Coordinator receives user direction
-> Helper handles normal supporting assignments when enabled
-> Executor handles substantive or consequential assignments
-> assigned worker returns actual work and evidence
-> Coordinator assesses, continues, corrects, or closes

Only one worker assignment runs at a time. A profile switch is not another agent or independent review. A worker report does not complete a Track Work Slice, task, commit, integration, release, or launch.

Cognitive Routing modes

The labels describe intended optimization direction and potential, not guarantees.

A comparatively economical but capable Helper can contribute much of Both mode's potential savings because many routine assignments go through it. The detailed guide includes recommended OpenAI subscription starting presets and the limits on those recommendations.

Availability

Configuration or installation alone does not establish runtime delivery.

Host support

Freeflow is one package with different host boundaries:

Freeflow owns workflow policy, portable prompts, skills, capability source, host adapters, and the Pi extension. Each host owns launch, package installation, session state, trust, and updates. Freeflow's PiFlow integration was removed as a breaking change; use native Pi for the Freeflow extension. Freeflow does not change or uninstall a separate PiFlow installation. See the Unreleased changelog.

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.

Use Freeflow effectively

A clear prompt normally needs:

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. Direct calls such as /discuss, /execute-work, /diagnose-failure, /verify-work, /review-work, /track-work, and /release-work are useful when they make the intended method clear. A skill is a method, not an authority grant or required phase.

Read Using Freeflow Effectively for prompt examples, Workflow management, Track Work, settings, mode selection, preset recommendations, cache/cost boundaries, and troubleshooting.

Commands

Canonical Pi direct calls include:

/discuss
/action-selection
/track-work
/write-spec
/review-artifact
/write-plan
/write-docs
/execute-work
/simplify-code
/migration-work
/diagnose-failure
/verify-work
/review-work
/commit-work
/handoff
/finish-branch
/release-work
/launch-work
/bypass

Contributor calls:

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

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

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

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.

Cognitive Routing remains experimental pending broader behavioral acceptance. Context Control v2 remains planned. The deprecated Output Router is removed and archived outside the active runtime.

Documentation

• Using Freeflow Effectively
• Getting Started
• Workflow
• Cognitive Routing
• Tool Execution
• Compaction
• Pi integration
• Architecture
• System prompt architecture
• Skill routing
• Capabilities
• 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.