flowcode

flowcode edits the git repository you run it in. It does not need Foundry, the broker, or a database. A pull request it opens starts with an Agent heading and the git user.email. When that is empty and FLOWCODE_ACTOR is an email, the heading uses that instead. With neither, the heading is left off.

go run ./services/foundry/cmd/flowcode
go run ./services/foundry/cmd/flowcode -p "explain how invoices are posted"

A one-shot run exits 0 when the task completed, 3 when it needs review, and 1 when it is blocked or fails.

Configuration

~/.config/flowcode/config.yaml is read first. .flowcode.yaml in the repository overrides it. The API key is the environment variable named by api_key_env. The program does not read a .env file.

model: gpt-5-mini
api_key_env: OPENAI_API_KEY

A platform block can set workspace_url. Sending tools stay off unless you pass --allow-send. --trust-repo-config accepts programs named in flowcode.yaml. az stays denied either way.

Programs

The agent runs programs by name, never by path and never through a shell. flowcode finds each program on PATH, then in /opt/homebrew/bin, /usr/local/bin, /usr/local/go/bin, ~/go/bin, and ~/.local/bin. This matters when the desktop app starts flowcode: an app opened from Finder gets a PATH of only /usr/bin:/bin.

git may run fetch, pull, merge, rebase, stash, grep, and the usual read and commit subcommands. git config and git clone are refused, as are options that make git start another program, such as --upload-pack and rebase --exec. Git uses your SSH agent through SSH_AUTH_SOCK.

A program outside the built-in set runs only when it is approved. --allow approves a comma-separated list up front. In a terminal, flowcode asks for anything else. Without a terminal, it refuses the program and tells the agent how the user can approve it. The desktop app runs flowcode this way and passes the list from Settings > Agents as --allow.

Commands

/plan and /agent switch mode. /diff shows the working tree. /undo restores tracked files. /model sets the model for the next task. /clear starts the next task with a fresh transcript. /quit exits.

Plans

-plan reads the repository and writes a plan. It does not edit files. The file is markdown with YAML front matter: name, overview, todos, and isProject. The body is the write-up, including a mermaid diagram when the change has a flow. A generated task checklist at the end is what a markdown preview shows. The todos in the front matter are the list the agent builds.

The first save writes .flowcode/plans/<name>_<id>.plan.md. That directory is gitignored. Later plan-mode prompts revise the same file when you pass -plan-file. Agent mode with the same -plan-file builds that plan and checks the todos off as it goes. In the terminal, /plan and /agent switch mode. Pass -plan-file again in agent mode to build.

--publish also uploads the plan when WORKSPACE_URL is set.