Skip to main content
Each flow is stored as a single JSON file at ~/.config/flow/<name>.json. When you run progflow on <name>, Progflow reads this file to determine which directory to use, which editor to launch, which URLs to open, and which environment variables to set.

​
Config directory

All flow configs and lockfiles live under ~/.config/flow/. Progflow creates this directory automatically the first time you save a config. 
~/.config/flow/
├── backend.json       # flow config
├── backend.lock       # active lockfile (present only while the flow is running)
├── docs.json
└── monitoring.json
The name field inside the JSON is used as the identifier for the flow. When saving a config, Progflow derives the filename from config.name, so keep this field consistent with the filename you want. Loading a config reads the file by name and then deserializes the name field from JSON.

​
Creating and editing flows

​
Complete example

{
  "name": "backend",
  "directory": "/home/user/projects/api",
  "editorCmd": "code .",
  "urlList": ["http://localhost:3000", "http://localhost:5432/admin"],
  "shell": "/bin/bash",
  "env": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgres://localhost/mydb"
  },
  "note": "Was working on the auth middleware, JWT validation failing for refresh tokens"
}

​
Fields

​
name
string
required
The name of the flow. Must match the JSON filename exactly (e.g., a file named backend.json must have "name": "backend"). Used to look up configs, lockfiles, and notes by name.
​
directory
string
Absolute path to the working directory for this flow. Progflow changes to this directory before spawning the editor.If omitted, defaults to . (the directory where progflow on is invoked).
​
editorCmd
string
Shell command to launch your editor. Executed as sh -c "<editorCmd>" inside the configured directory.
"editorCmd": "nvim ."
If omitted, no editor is launched — useful for flows that only open URLs.
​
urlList
string[]
List of URLs to open when the flow activates. On Linux, Progflow tries xdg-open first, then falls back to gio open, firefox, chromium, and brave. On Termux, it uses termux-open-url, with an am start fallback.
"urlList": ["http://localhost:3000", "https://docs.example.com"]
If omitted or empty, no URLs are opened.
​
shell
string
default:"/bin/sh"
Path to the shell binary. Currently stored in the config and reserved for future use — Progflow does not use this field to launch the editor command today.
​
env
object
Key-value pairs of environment variables to set when spawning the editor command. These variables are layered on top of the existing process environment — they do not replace it.
"env": {
  "NODE_ENV": "development",
  "DATABASE_URL": "postgres://localhost/mydb"
}
These variables apply only to the editor process. They have no effect on URL opening.If omitted, the editor inherits the environment unchanged.
​
note
string
default:"\"\""
A free-text context note saved automatically by progflow off. When you stop a flow and choose to save a note, Progflow writes your input into this field.Read the saved note at any time with:
progflow note backend
You can also edit the note field directly in the JSON file.

​
Field summary

FieldTypeRequiredDefaultDescription
namestringYes—Flow name; must match filename
directorystringNo.Working directory path
editorCmdstringNo—Editor shell command
urlListstring[]No—URLs to open on activation
shellstringNo/bin/shShell path (reserved)
envobjectNo{}Editor environment variables
notestringNo""Saved context note

​
Lockfile

While a flow is active, Progflow writes a lockfile at ~/.config/flow/<name>.lock. This file is a JSON object containing the PIDs of processes spawned during progflow on: 
{"pids": [12345, 12346]}
When you run progflow off, Progflow reads this lockfile, sends SIGTERM to each listed PID, then deletes the .lock file. If no lockfile exists, Progflow reports that no active flow was found.
Do not edit or delete lockfiles manually while a flow is running — doing so will prevent progflow off from terminating the spawned processes correctly.

Build docs developers (and LLMs) love

Get started for freeTalk to us