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. The generators that flowcode.yaml lists are checked before a run finishes as completed; see Architecture.

FLOWCODE_MODEL_PLAN, FLOWCODE_MODEL_BUILD, and FLOWCODE_MODEL_EXPLORE choose a model per phase, the way a Foundry coding pod does; each falls back to FLOWCODE_MODEL. FLOWCODE_API_BASE is the chat completions endpoint, OpenAI's by default, and FLOWCODE_API_KEY_ENV names the variable that holds its key, OPENAI_API_KEY by default. For a Claude model, use Anthropic's OpenAI-compatible endpoint, https://api.anthropic.com/v1/chat/completions, with ANTHROPIC_API_KEY. For a model on OpenRouter, such as z-ai/glm-5.3, use https://openrouter.ai/api/v1/chat/completions with OPENROUTER_API_KEY.

When the phases use models from different providers, set the endpoint and key per phase: FLOWCODE_API_BASE_PLAN and FLOWCODE_API_KEY_ENV_PLAN, and the same with _BUILD and _EXPLORE. Each falls back to the variable without the phase suffix. codingeval run sets these for you.

With -p, --self-approve plans and then builds the plan without waiting, as a Foundry agent that approves its own plan runs. --no-push refuses git_push and open_pull_request, so the change stays on the local branch and the run finishes without a pull request. A one-shot run ends with a flowcode outcome: line and one flowcode usage: line per model on stderr, which is how codingeval run records the outcome and the tokens.

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.