Skip to main content
A flow is a directory whose entry file is action.yaml. You can run that file directly, or place the directory in a discovery tier so navi run <name> finds it.

​
Run a flow without installing it

Use an absolute path when the flow lives outside the repository you are working on:
--shape checks the YAML and prints the resolved steps without calling a model. Use --help to see the flow’s arguments:
This route leaves nothing in the target repository. Remove --shape when the plan is correct and supply the arguments shown by --help.

​
Give a shared flow a short name

To make a shared flow available by name, put its complete directory under .agents/workflows/:
The catalog identifies it as pinned:
Keep the directory name and the name: inside action.yaml the same. Name resolution uses the directory; run output uses the YAML name.
A pinned flow is a project-owned snapshot. Update or remove its directory yourself. Use an explicit path for a zero-copy flow. navi install connects Navi to a coding agent; flow directories remain separate.

​
Keep a flow in one project

Put a flow that belongs only to the current repository under .navi/workflows/:
Command steps can reach a sibling parser through $NAVI_ACTION_DIR. Navi sets that variable to the absolute directory containing the active action.yaml:
The command still runs from the workspace, so repository commands such as git diff operate on the repository selected by -w.

​
Override a builtin for one repository

Create a project flow with the same directory name as the builtin:
Then inspect the catalog:
The relevant rows look like this:
npx --no-install navi-cli run code-review now resolves the project flow. Delete only the project directory you added to expose the builtin again.

​
Flow precedence

Navi checks these directories in order: An explicit path bypasses name lookup. npx --no-install navi-cli catalog is the check for which named flow is active. Next, write the action.yaml. To make its result drive session state and gate-aware exits, return a gate.