Flow’s organizational system creates a hierarchical structure that scales from individual projects to complex multi-project ecosystems. The system balances discoverability with isolation, enabling both focused work within projects and cross-project composition.

Hierarchy Structure

Workspaces serve as the top-level organizational unit, typically mapping to Git repositories or major project boundaries. Each workspace contains its own configuration, executable discovery rules, and isolated namespace hierarchy.

Namespaces provide logical grouping within workspaces, similar to packages in programming languages. They enable organizational flexibility. A single workspace might have namespaces for frontend, backend, deploy, or tools. Namespaces are optional but recommended for workspaces with many executables.

Executables are the atomic units of automation, uniquely identified within their namespace by their name and verb combination. This allows multiple executables with the same name but different purposes (build api vs deploy api).

Reference System

Flow uses a URI-like reference system for executable identification:

workspace/namespace:name
    │         │       │
    │         │       └─ Executable name (Optional but unique within verb group + namespace)
    │         └───────── Optional namespace grouping
    └─────────────────── Workspace boundary

Reference Resolution Rules:

• my-task → Current workspace, current namespace, name=“my-task”
• backend:api → Current workspace, namespace=“backend”, name=“api”
• project/deploy:prod → workspace=“project”, namespace=“deploy”, name=“prod”
• project/ → workspace=“project”, no namespace, nameless executable

Reference Format Trade-offs:

• Chosen: Slightly more verbose for simple cases
• Avoided: Naming collisions, poor tooling support, brittle file/directory coupling

Verb System

Verbs describe the action an executable performs while enabling natural language interaction. Verbs can be organized into semantic groups with aliases:

# Executable definition
verb: build
verbAliases: [compile, package, bundle]
name: my-app

# With the above, all of these commands are equivalent:
flow build my-app
flow compile my-app
flow package my-app

This system allows developers to use whichever verb feels most natural while maintaining executable uniqueness through the [verb group + name] constraint.

I’ve significantly reduced the number of default verb groups to focus on the most common actions with the most semantic clarity. See the flow documentation for the latest default list.

Context Awareness

Flow maintains context awareness to reduce typing and improve ergonomics:

Current Workspace Resolution:

• Dynamic Mode: Automatically detects workspace based on current directory
• Fixed Mode: Uses explicitly set workspace regardless of location

Namespace Scoping:

• Commands inherit current namespace setting
• Explicit namespace references override current context

Note to self: Explicit command overrides of workspace / namespace may become an emerging need with the Desktop UI and MCP server usage.

Cross-Project Composition

The reference system enables powerful cross-project workflows:

executables:
  - verb: deploy
    name: full-stack
    serial:
      execs:
        - ref: "build frontend/"     # Different workspace
        - ref: "build backend:api"   # Different namespace
        - ref: "deploy"              # Current context

Finding the Workspace

Registration is an optimization, not a prerequisite. In dynamic mode flow finds its workspace by walking up from the current directory to the nearest flow.yaml, the same way make and bazel find their root. Clone a repo and its executables work immediately.

An unregistered workspace is named after its directory, runs normally, and is never written anywhere. Not to the config, not to the shared executable cache. What you give up is the ability to flow workspace switch to it, and other workspaces cannot reference its executables by name.

Resolution runs in this order:

1. --workspace or $FLOW_WORKSPACE, which accepts a registered name or a path
2. The nearest flow.yaml at or above the working directory (dynamic mode only)
3. A registered workspace whose directory contains the working directory
4. Whatever flow workspace switch last set

A directory containing its own flow.yaml is a boundary. The closest one wins, and a parent workspace does not scan into it. Discovery also walks past vendor/, node_modules/, third_party/, external/, .git/ and .claude/, because a flow.yaml in there belongs to that copy rather than to your project. The honest caveat is that there is no stopping point above your home directory, so a flow.yaml in ~ makes your entire home directory a workspace.

Git Workspaces

A workspace can be a git remote rather than a local path. Clones are cached under ~/.cache/flow/git-workspaces/, following Go module conventions, and can be pinned to a branch or tag. flow sync --git refreshes them. This is what lets a workspace of shared team executables be consumed the same way a dependency is.

The execution engine is the core of Flow, responsible for running executables defined in YAML files.

Runner Interface

The execution system uses a runner interface pattern where each executable type implements:

type Runner interface {
	Name() string
	Exec(
		ctx context.Context,
		exec *executable.Executable,
		eng engine.Engine,
		inputEnv map[string]string,
		inputArgs []string,
	) error
	IsCompatible(executable *executable.Executable) bool
}

Current runner implementations include:

• Exec Runner: Shell command execution
• Request Runner: HTTP request handling
• Launch Runner: Application/URI launching
• Render Runner: Markdown rendering
• Serial Runner: Sequential execution of multiple executables
• Parallel Runner: Concurrent execution with resource limits

Workflows (Serial and Parallel)

The serial and parallel runners allow for composing complex workflows from simpler executables. Steps are defined with a RefConfig that supports inline commands or references to other executables:

type SerialRefConfig struct {
  Cmd string
  Ref Ref
  Args []string

  If string          // Expression to conditionally skip the step
  Retries int
  ReviewRequired bool // Prompts the user before continuing
}

Execution and result handling is managed by the internal engine.Engine interface. The current implementation includes retry logic, error handling, and result aggregation.

Execution Environment and State

Environment Inheritance Hierarchy:

Environment variables are provided to the running executable in the following order:

1. System environment variables (lowest priority)
2. Dotenv files (.env, workspace-specific)
3. Flow context variables (FLOW_WORKSPACE_PATH, FLOW_NAMESPACE, etc.)
4. Executable params (secrets, prompts, static values)
5. Executable args (command-line arguments)
6. CLI --param overrides (highest priority)

State Management

There are two ways state can be managed when composing workflows:

• Cache Store: Key-value persistence across executions with scoped lifetime. Values set outside executables persist globally; values set within executables are cleaned up on completion. Uses bbolt for cross-process storage.
• Temporary Directories: Isolated scratch space (f:tmp) with automatic cleanup and shared access across serial/parallel workflow steps.

File System Access

By default, the working directory is the directory containing the flow file that defines the executable. This can be configured using special prefixes: // (workspace root), ~/ (user home), f:tmp (temporary).

There is no automatic sandboxing. Executables inherit full user permissions. Flow assumes users understand their workflows’ scope and potential for system modification, prioritizing automation flexibility over execution isolation. Containerized execution is a planned future improvement.

See the executable guide and state management for usage details.

Performance and Caching

Flow uses eager discovery with multi-level caching to keep response times fast. Workspace scanning runs up front and is cached to disk, with in-memory caching layered on top for quick lookups. The cache is invalidated and refreshed via flow sync or the --sync flag.

Note to self: Some performance testing needed to validate sub-100ms discovery targets across large workspace trees.

For implementation details, see the DeepWiki reference.

Getting Values Into a Process

Everything reaches an executable as an environment variable. There are four sources:

Each can write to envKey or, when something needs a real file on disk, to outputFile, which is cleaned up after the run.

Arguments are separate from parameters and come from the command line, either positionally (pos: 1) or as flags (flag: name), with a type and an optional default:

flow build container -- v1.2.3 --publish=true

Resolution runs highest to lowest: a --param override, then the executable’s params, then its args, then the surrounding shell environment. Parent values propagate into children in serial and parallel workflows.

Paths get their own small vocabulary, which keeps definitions portable: // is the workspace root, ~/ is home, ./ is relative to the flowfile, $VAR expands from the environment, and f:tmp is a temp directory created once per run and cleaned up after.

Containers

A step can declare an image and run there instead of on the host:

exec:
  cmd: pytest -q
  container:
    image: python:3.13-alpine

The runtime is Docker or Podman, auto-detected unless pinned. The workspace mounts at /workspace by default, additional volumes use the same path prefixes as everything else, and the FLOW_* variables come along automatically. Secrets go in through a temporary --env-file rather than the command line, so they never appear in the container’s argv.

Conditions and State

Steps can be skipped with an if expression evaluated against os, arch, env, store, and a ctx object carrying the current workspace, namespace and flowfile paths. Conditions are the one place where a $("command") shell escape is available.

The store is a small key-value cache with two lifetimes, and the distinction matters more than it looks:

• Global, set outside a run with flow cache set, persists until cleared.
• Execution, set from inside an executable, is cleared automatically when the parent finishes. A serial workflow can pass state between its own steps without leaking it.

Two more things exist at the step level because workflows meet reality: retries: N, and reviewRequired: true, which pauses for a human before continuing.

The vault system provides secure storage, management, and retrieval of secrets across workspaces and executables. It extends the executable environment with multiple encryption backends.

Implementation: github.com/flowexec/vault

Provider Architecture

The vault system supports multiple storage backends through a common Provider interface:

type Provider interface {
  ID() string
  GetSecret(key string) (Secret, error)
  SetSecret(key string, value Secret) error
  DeleteSecret(key string) error
  ListSecrets() ([]string, error)
  HasSecret(key string) (bool, error)
  Metadata() Metadata
  Close() error
}

Current Providers

• Unencrypted Provider: Simple key-value store for development and testing
• AES Provider: Symmetric file encryption using AES-256-GCM (single key management)
• Age Provider: Asymmetric file encryption using the Age specification (supports multiple recipients)
• Keyring Provider: Uses system keyring (macOS Keychain, Linux Secret Service)
• External Provider: Integration with external CLI tools (1Password, Bitwarden) via command execution

Vault Switching

Vaults can be switched using a context-based system:

flow vault switch development
flow secret set api-key "dev-value"

flow vault switch production
flow secret set api-key "prod-value"

Secret references support both current vault context (secretRef: "api-key") and explicit vault specification (secretRef: "production/api-key").

Backends

Key storage is configurable per vault, and an existing valid key in the target variable is reused rather than regenerated, which is how one key ends up shared across several vaults.

External Vaults

This is the design I am happiest with. An external vault holds links, not secrets. Each link pairs a name you choose with a reference the provider understands. Reading the name resolves the reference and reads through. Nothing is copied into flow and nothing is ever written back, so pointing a vault at a store you already use cannot damage it.

The configuration carries a get command, an optional metadata command, and two patterns that turn out to matter a lot:

• reference_pattern describes what a reference for this provider looks like, so a typo is caught when you link it rather than weeks later when you read it.
• not_found_pattern separates “this link is broken” from “the provider is unreachable”. Without it, an expired session is indistinguishable from a deleted secret.

Because it is read-through, flow secret set fails against an external vault and flow secret remove removes the link rather than the secret.

Injection

Secrets never appear in a command line. They are resolved at run time and handed to the process as environment variables:

params:
  - secretRef: api-key
    envKey: API_KEY
  - secretRef: production/db-password   # a different vault
    envKey: DB_PASSWORD

When something genuinely needs a file, outputFile writes one and deletes it afterwards. In container runs the same values go through a temporary --env-file, for the same reason.

flow already had the pieces to do better. It knows your workspace, it holds your secrets, it captures logs, and it records every run. Exposing that over MCP turns it from a task runner into somewhere an agent can work.

The Scope Boundary

Worth stating up front, because it shapes everything else:

flow is an AI tool provider, not an AI consumer.

The core exposes deterministic capabilities: an MCP server, published JSON schemas, an llms.txt. It does not make model calls. No LLM parsing of natural-language commands, no generation inside the CLI. That would put vendor keys, per-call cost, and non-determinism in the critical path of a task runner. Anything applying a model to flow does so from outside, through the MCP surface. Mochi is exactly that: a consumer built on top.

The Ladder

The run tools are deliberately ordered, closest fit first:

The reason run_python is its own tool rather than a flag on run_command is small and practical: agents select tools by name, and a tool called “run_command” is not what gets reached for when the task is Python.

Around those sit discovery and inspection tools (list_executables, get_executable, list_workspaces, get_workspace, switch_workspace, get_info), history (get_execution_logs), and authoring (write_flowfile, which validates against the schema server-side before writing). There are MCP resources for workspaces, executables, flowfiles and logs, and prompts for generating and debugging executables.

The server is built on mcp-go, and exposes Tools, Prompts and Resources. I discovered that client support for Resources is still thin but I have them for clients that do support them.

The boundary is stated honestly in the server instructions: fall back to a raw shell for things that genuinely should not be recorded, or that flow is not suited to, like anything needing a TTY.

What Running Through flow Buys You

Compared to a generic execute tool:

• Named work first. Discovery means the agent runs your actual test executable rather than its own approximation of one.
• Workspace resolution from a directory. Pass a path and flow walks up to the nearest flow.yaml. Works in a fresh clone or a git worktree with nothing registered.
• Secrets from the vault, injected as environment, never in the argv.
• Provenance on every run. source, clientName, sessionId, workingDir.
• Lifecycle-aware history. Written as running at start and upserted on completion, so a log can be read while the run is still going.
• Approval gates in the workflow, via reviewRequired on a step, rather than depending on the client to ask.
• Byte-capped structured output, so a runaway log cannot eat the context window.

Provenance Has Opinions

Three environment variables carry it: FLOW_RUN_SOURCE, FLOW_RUN_CLIENT, FLOW_RUN_SESSION. Two decisions behind that are worth repeating.

There is no client registry. flow does not sniff for CLAUDE_CODE_SESSION_ID or any other vendor’s variables. Those are undocumented internals that get renamed, and detection built on them fails silently, so history quietly stops grouping and nobody notices. Each tool maps its own variables onto the contract instead.

And identity is exported, not passed. Environment beats a flag the assistant has to remember on every call: a model can silently omit an argument, but it cannot omit a variable it never sees. Parameters are for intent, which is the only thing the model actually knows.

The Python Interpreter

You can run python alongside the built-in POSIX shell:

executables:
  - verb: run
    name: report
    exec:
      interpreter: python
      cmd: |
        import json, sys
        print(json.dumps({"python": sys.version_info[:2]}))

A .py file needs no interpreter field at all, since the extension implies it. The same field works on serial and parallel steps, and inside containers, where the entrypoint follows the interpreter rather than being hardcoded to a shell.

Nothing is embedded. There is no bundled CPython, no Starlark, no WebAssembly. flow resolves a real interpreter on the host, preferring a project’s virtualenv over bare system Python, so an agent running Python inside a repo gets that repo’s dependencies. The search order is FLOW_PYTHON_BIN, then $VIRTUAL_ENV, then the workspace’s .venv, then python3 on the path. An override that does not resolve fails rather than quietly falling back.

Two details I liked:

Inline code runs from a temporary file, never python -c. That keeps user code, which may have interpolated secrets, out of the process table; it produces tracebacks with real line numbers; and it sidesteps shell quoting for multi-line scripts.

PYTHONUNBUFFERED is set by default, because flow pipes stdout to a log writer rather than a terminal, and CPython block-buffers to a pipe. Without it a long run emits nothing until it exits, which looks hung to anyone watching, human or otherwise.

The MCP side is the reason the rest exists. run_python gives an assistant a Python runtime with the same workspace environment and secrets, the same captured logs, and the same attributable history entry it already gets for shell. It is the difference between an agent writing a scratch file and an agent doing work you can audit afterwards.

Flow includes a templating system for generating executables and workspaces from reusable templates, built on Go’s text/template and the Expr expression language. See the documentation for usage details and examples.

Where flow Plugs In

Two integration surfaces have their own pages, because both turned out to be more than a paragraph:

• The GitHub Action runs the same executables in CI that you run locally.
• flow as an agent runtime covers the MCP server and the tools it exposes.

There is also a Docker image at ghcr.io/flowexec/flow for other CI systems, though it has not been exercised nearly as hard as the Action has.

Schemas

The flowfile, workspace, template and config formats are published as JSON Schema (see the configuration reference), which is what gives editors completion and validation, and what lets an assistant author a valid flowfile without guessing. There is an llms.txt alongside them. The Go types are generated from those same schemas, so the contract has one source.

flowexec/action is how. It publishes to the Marketplace as flow-execute, and the smallest useful thing you can write with it is:

- uses: flowexec/action@v1
  with:
    executable: 'build app'

That is the whole point of it. The executable named there is the same one you run with flow build app at your desk. Every repository in the flowexec organization uses this on itself.

What It Actually Is

A composite action, not a container or a JavaScript action. It is a handful of bash steps in a trench coat, which is the right shape for something whose job is to install a binary and run it:

1. Resolve where flow should be installed, then restore it from the runner cache.
2. Install the CLI if the cache missed.
3. Register workspaces, cloning any that are git remotes.
4. Create a vault and load secrets into it, but only if secrets were passed.
5. Run the executable.
6. Upload logs as an artifact, but only on failure, and only if asked.

Keeping it composite means each step shows up separately in the workflow log, so a failure points at the thing that failed rather than at one opaque action.

Workspaces, Including Ones That Are Not There Yet

The interesting input is workspaces. A workspace can be a local path, but it can also be a git URL, which the action clones and registers before running anything:

- uses: flowexec/action@v1
  with:
    executable: 'deploy staging'
    workspaces: |
      backend: ./backend
      frontend: https://github.com/user/frontend-repo.git
      shared:
        repo: https://github.com/myorg/shared-flows.git
        ref: v1.0.0
    clone-token: ${{ secrets.GITHUB_TOKEN }}

This is the CI expression of flow’s cross-project composition. A workflow can pull in a shared workspace of common executables, pin it to a tag, and reference its executables the same way it would locally. Clone depth defaults to 1, because CI almost never needs the history.

Secrets and the Ephemeral Vault

Secrets were the part that needed real thought. flow reads secrets from a vault, and a CI runner has no vault, so the action makes one and throws it away.

When secrets are passed, it creates a vault named github-actions keyed to an environment variable, loads each secret in, and switches to it. The generated key is immediately masked in the log with ::add-mask:: and exposed as an output.

That output exists for one reason, and it is the nicest bit of the design: a vault can outlive a job. Emit the key from one job, pass it to the next, and the second job decrypts the same vault rather than re-loading every secret from GitHub:

jobs:
  setup:
    outputs:
      vault-key: ${{ steps.init.outputs.vault-key }}
    steps:
      - uses: flowexec/action@v1
        id: init
        with:
          executable: 'validate'
          secrets: |
            SHARED_SECRET=${{ secrets.SHARED_SECRET }}

  deploy:
    needs: setup
    steps:
      - uses: flowexec/action@v1
        with:
          executable: 'deploy production'
          vault-key: ${{ needs.setup.outputs.vault-key }}

The vault step is skipped entirely when there are no secrets and no key, so a plain build job does not pay for machinery it is not using.

Failing Usefully

A CI action that only tells you “exit code 1” is not much better than running the command yourself. This one parses flow’s structured JSON error output and surfaces the code:

Which means a workflow can branch on why something failed rather than just that it did:

- name: Handle failure
  if: steps.migrate.outputs.exit-code != '0'
  run: |
    if [ "${{ steps.migrate.outputs.error-code }}" = "TIMEOUT" ]; then
      echo "Consider increasing the timeout"
    fi

Captured output is truncated at 65,000 bytes, because that is GitHub’s limit on a step output, and the full log is available as an artifact instead.

The Unglamorous Parts

Most of the commit history is Windows and shell edge cases, which is what this kind of tool is actually made of:

• Windows runners need $HOME/bin pushed onto GITHUB_PATH, and workspace paths in native form rather than the POSIX form the rest of the script assumes.
• TERM=dumb on Windows, because flow’s TUI would otherwise try to render into something that is not a terminal and hang the job.
• The vault key is extracted from structured JSON output, with a fallback to scraping the plain text message for older CLI versions.
• The binary is cached between runs, keyed on the resolved version, so a workflow that runs the action several times installs flow once.

None of that is interesting to write about, and all of it is the difference between an action that works on your machine and one that works on someone else’s.

Resources

• flowexec/action
• flow-execute on the Marketplace
• flow’s own CI workflow, which uses it

Creative work you experience once. Development work you live in. That difference changes what you need from a partner.

The Bench

When I was at Recurse Center last summer, I started integrating AI more intentionally into how I build. Not for speed, for learning. I wanted to experiment with architectures I wouldn’t normally try, undo decisions cheaply, and see what held up. Flow was the natural workbench. It’s my own tool and I know every corner of it.

Over the last few months I’ve been building Flow Desktop and refactoring pieces of the core CLI with AI doing a lot of the implementation work. The experience has been different from vibe coding in ways that matter. In the HGSE projects, I was optimizing for something working. Here, I’m optimizing for something I can read six weeks later, find when I need it, and build on without second-guessing what’s underneath.

That changes what I actually delegate.

The Delegation Model

The architectural decisions stay with me. What the data model looks like, how executables get resolved, where state lives. What I hand off is the implementation of decisions I’ve already made. I describe the shape of what I want, review what comes back against that shape, and merge when it aligns. When it doesn’t, I say so explicitly.

A concrete example: I’ve been building an AI proxy backed by Cloudflare AI Gateway that sits across all of my tools. I decided on the architecture, what the proxy needs to do, how it integrates with the Cloudflare platform, what observability I want. AI implemented it. The Cloudflare MCP server made the feedback loop tight enough that I could test and iterate without switching contexts.

What makes this work is having a single place to see everything. Everything I’ve configured, discoverable from one surface.

One of the real risks of AI-assisted development is ending up with code you can’t navigate. Outputs that don’t connect to anything, a project that sprawls in ways you can’t audit. The workspace model keeps that from happening. I know where things live because I designed where they live.

I’ve also started using AI to enrich Flow itself, generating executable metadata, adding descriptions and tags, making the library more useful as it grows. Flow has an MCP server, so AI tools can interact with it directly. Watching an AI tool work with Flow rather than just producing files has been one of the more interesting parts of this.

Licklider’s framing from the last post still holds here. Set the goals, determine the criteria, perform the evaluations. That’s still your job. What’s changed is my confidence in what I can hand off once those things are set.

What It Produced

The review and iterate phase is where the real work happens. AI gets you to a first draft faster. Whether that draft is right is still a judgment call only you can make.

A few months of this produced Flow v2 and something I’ve been sitting on: Mochi. Development workflows have a way of becoming invisible. They exist, they’re just not anywhere you can see them. It’s a local-first dev ops dashboard built on Flow. Point it at a directory and it finds your development scripts and automations, turns them into a unified, AI-enriched dashboard. No cloud, no accounts, works with whatever you’re already running.

Executables view. Everything Mochi found across my workspaces, tagged and filterable.

Still early. If it sounds useful, the waitlist is at mochiexec.io.

I’m more convinced than I was last fall that the gap worth closing isn’t between what AI can produce and what you can prompt. It’s between what AI produces and what you actually understand. Building in a system you designed is one way to stay honest about that.

I introduced flow in another post a few months ago, but I’ve had the amazing opportunity to start a sabbatical at the Recurse Center, where I’ve been able to think more deeply about the problems I was solving and the technologies I wanted to learn about! As I mentioned in that post, flow has been my “learning platform” over the last 2 years and I knew I wanted to take it a step further at Recurse.

I’m at the halfway point of my time at RC and am excited to share how my first 6 weeks have been on my main coding project.

flow desktop

I’ve been itching to work on a frontend project for a while now. While building the flow TUI library, I had lots of fun thinking about how I could create a good experience through visuals and layout. Bubble Tea has been fun to use here, but I’ve wanted to do some UI development with more possibilities. Doing this in the “browser” and using new-to-me technologies sounded like a great plan.

Coming into RC, this was something I knew I wanted to work on, but my excitement grew as I started to learn about the fascinating world of frontend development through RC pair programming, events, and chats.

Architecture Decision: CLI as Single Source of Truth

Instead of duplicating business logic in my desktop app, I’ve been building it as a pure visualization layer over the existing CLI.

This felt risky at first - wouldn’t spawning processes be too slow? Turns out CLI commands execute pretty fast thanks to some caching I do on the CLI side. The whole round trip feels instant with my current usage.

Tech Stack

All of the resources, pairing, feedback, and individual research I’ve done has landed me on the following:

• Tauri: Gives me Rust backend + web frontend without Electron’s bloat. Bonus that it’s an opportunity to learn some Rust.
• TypeScript: I was able to get TS and Rust types generated from the same JSON schema that I use to generate Go code. This has been making development much smoother across the 3 languages that flow now uses.
• React & Mantine UI: VSCode-like components without building everything from scratch. Their Spotlight extension is what sold me - it could be a really cool search and command center for the UI!

Demo!

Here is a quick demo of me using my current implementation of the desktop. This shows the workspace and executable viewer/runner in action - you can see me running an executable directly from the UI and playing with the theme picker I prototyped for customization.

I still have more work to do here, but it’s been satisfying seeing my ideas come to life as I pick up these new technologies.

vaults v2

I had a couple of pain points with the vault that I initially built for flow. The UX was pretty simple but limiting. I’ve also been really wanting a way to integrate my Bitwarden secrets into flow seamlessly. This led me to brainstorm a new design for that feature. I spent my first 2 weeks at RC doing some light research on cryptography with Go, studying how other tools handle secrets, and building a simple POC.

I decided to introduce a “provider” concept that also improves the experience around having multiple vaults. I currently have an implementation for an updated version of my AES symmetrically encrypted vault, added an Age asymmetric encryption backend, and plan to add a backend for custom CLI-tool vault managers. You can see what I came up with in this repo. From the flow perspective, the experience would be like this:

Creating a vault

# Auto-generates everything for the AES vault
flow vault create development
# Create an Age vault with identity generated from age-keygen
flow vault create team --type age --recipients key1,key2,key3 --identityFile id.txt
# External needs CLI integration
flow vault create bitwarden --type external --interactive

Vault Switching as Primary UX

Borrowed the mental model from git/kubectl:

flow vault switch development    # Like git checkout
flow secret set api-key "dev-123"

flow vault switch production
flow secret set api-key "prod-456"

This allows for clean secret references in executables: secretRef: "api-key" uses current vault, secretRef: "production/api-key" is explicit.

Technical decisions

Executable composition

Executables aren’t just scripts - they’re composable units with conditional logic:

serial:
  failFast: true
  execs:
    - if: os == "darwin"
      cmd: "command -v mytool || brew install mytool"
    - if: env["PUSH"] == "true"
      cmd: make image
    - ref: deploy development
      reviewRequired: true  # Pauses for human confirmation
    - ref: launch app

The expression language (using Expr) has access to OS info, environment variables, and flow’s cache. It’s like having bash conditionals but declarative.

Process architecture

The desktop app’s process model is pretty simple. Each user action spawns a CLI process:

#[tauri::command]
async fn get_workspaces() -> Result<Vec<Workspace>, String> {
    let output = Command::new("flow")
        .args(["workspace", "list", "--output", "json"])
        .output().await?;

    serde_json::from_slice(&output.stdout)
}

This seems inefficient but has huge benefits:

• Desktop crashes don’t corrupt CLI state
• CLI updates immediately benefit desktop
• No state synchronization between processes
• Easy to debug - each operation is a discrete CLI command

RC moments that shaped the code

Pair Programming: I paired on setting up Tauri and trying to integrate it with the CLI. We came up with the great idea of using some of my existing CLI output formatting options to get data through the app. This turned out to be a great decision to make on the fly. Conversations with others helped me confirm that CLI-as-source-of-truth wasn’t a compromise - it was the right abstraction.

The Feedback Loop: RC’s culture of sharing work-in-progress meant getting feedback on half-baked ideas. I’ve enjoyed presenting and demoing my progress throughout my time. I’d thought extensions would be a neat feature but I never actually needed them myself. Hearing about the different ways that others think flow could be extended convinced me to reopen an issue I closed.

Community Inspiration: Seeing the variety of projects and approaches at RC has reinforced my belief that developer tools should be adaptable rather than prescriptive. Everyone has their own workflow, and the best tools are the ones that bend to fit how you think, not the other way around.

Next up

flow MCP server

I’ve started using Claude Code and this has inspired me to learn how to create a Model Context Protocol server that will allow AI to understand flow workspaces and executables natively. I’d love to eventually have something that enables:

• Browsing flow files and suggesting syntax improvements
• Generating new workflows from natural language
• Debugging failures with full workspace context 🚀

WASM plugin system

Extending flow with WASM-integrated extensions. I want to try to allow automations to be programmable in two ways:

• Executable template generator: Plugins that run template generation for flow-discoverable executables (from APIs, templates, external sources). I’m thinking of something like Taskfile/just → flow executable integrations to start
• WASM Runtime executable type: Plugin executables that run sandboxed through flow

This will be my first time getting hands-on with WebAssembly and I already have many ideas for cool plugins that will allow me to tinker with a variety of languages in the future.

Test & release improvements

The best way to try out some of these new and upcoming features would be to clone the flow repo and run the build binary executable to get a local go build. Note that the main branch is not guaranteed to be stable, though.

With a new component in the flow ecosystem, I need to level up the test and release process as I prepare for v1 over the next couple of months. This means learning frontend testing practices, updating my GitHub workflows to handle multi-language builds, and rethinking the installation process to bundle the desktop app alongside the CLI.

However, the challenges that I face at work and on my side projects aren’t quite the same as the ones faced by CarGurus product engineers. I started to find myself drowning in a sea of scattered commands, scripts, and tools. This, combined with my desire to find opportunities to learn more about Go patterns and libraries in a low-risk way, motivated me to invest some free time developing an “integrated development platform” - or at least the foundations for one!

Enter flow: my open-source task runner and workflow automation tool. What started as a simple itch to scratch has evolved into the foundations of a comprehensive platform for wrangling dev workflows across projects. Looking back, I realize it would have been easier to just migrate everything into a tool like Taskfile or Just, but my vision for my own personal platform doesn’t stop at the CLI. Taking that route also would have left my learning desires unmet. While much of my influence for flow comes from cloud-native projects and ideals, I’ve approached it from a local-first perspective - one where repeatable “micro-workflows” can be pieced together however you desire; making them easily discoverable, automated, and observable.

It’s ambitious, but that’s what excites me! There’s so much experimenting and learning ahead. This is my first blog post, but if this interests you, please return! I’ll be using it to document my learnings and progress on this project and some of my other side projects.

Building the Foundation

My first build of flow centered around two simple concepts driven by YAML files:

• Workspaces for organizing tasks across projects/repos
• Executables for defining those tasks

I included a simple tview terminal UI implementation to simplify the discovery of workspaces and executables across my system. While I’ve since moved away from that library, it helped me conceptualize much of the current TUI.

Through usage, I found myself iterating a lot. As I onboarded more workspaces and as those workspaces grew in complexity, flow’s feature set had to grow. My favorite components to implement have been the bubbletea TUI framework, an internal documentation generator for the flowexec.io site, the templating workflow, and the state and conditional management of serial and parallel executable types. ’ll dive deeper into those in follow-up posts, but I invite you to explore the guides at flowexec.io for a complete overview of where flow stands today.

At it’s core, the flow CLI is a YAML-driven task runner. Here is an example of a flow file that I have for my Authentik server deployed in my home cluster; it uses the exec executable type to define the command that’s run:

namespace: authentik # optional, additional grouping in a workspace
tags: [k8s, auth] # useful for filtering the `flow library` command
# this description is rendered as markdown (alongside other executable info)
# when viewing in the `flow library`.
description: |
  **References:**
  - https://goauthentik.io/
  - https://github.com/goauthentik/helm
executables:
  # flow install authentik:app
  - verb: install
    name: app
    aliases: [chart]
    description: Upgrade/install Authentik Helm chart
    exec:
      params:
        # secrets are managed with the integrated vault via the `flow secret` command
        - secretRef: authentik-secret-key
          envKey: AUTHENTIK_SECRET_KEY
        - secretRef: authentik-db-password
          envKey: AUTHENTIK_DB_PASSWORD
      cmd: |
        helm upgrade --install authentik authentik/authentik \
          --version 2024.10.4 \
          --namespace auth --create-namespace \
          --set authentik.secret_key=$AUTHENTIK_SECRET_KEY \
          --set authentik.postgresql.password=$AUTHENTIK_DB_PASSWORD \
          --set postgresql.auth.password=$AUTHENTIK_DB_PASSWORD \
          --set postgresql.postgresqlPassword=$AUTHENTIK_DB_PASSWORD \
          -f values.yaml

The flow CLI provides a consistent experience for all executable runs and searches. This includes automatically generating a summary markdown document viewable with the flow library command, log formatting and archiving, and a configurable TUI experience.

This will show up in the flow library as rendered markdown:

As my needs evolved, I added more executable configurations and types. Here’s an example of a common request executable I use to pause my home’s pi.hole blocking:

executables:
  # flow pause pihole
  - verb: pause
    name: pihole
    request:
      method: "POST"
      args:
        - pos: 1
          envKey: DURATION
          default: 300
          type: int
      params:
        - secretRef: pihole-pwhash
          envKey: PWHASH
      url: http://pi.hole/admin/api.php?disable=$DURATION&auth=$PWHASH
      validStatusCodes: [200]
      logResponse: true
      transformResponse: if .status == "disabled" then .status = "paused" else . end

Here’s an example of the log output:

Lessons Learned

Building flow has been an incredible opportunity to deepen my understanding of Go and its ecosystem. Here are a few key lessons that have significantly shaped how I write Go now:

Small Packages and Interfaces Made Testing a Breeze

This approach makes testing easier, improves code organization, and makes refactoring as ideas evolve a joy.

Each executable type has its own Runner, making it simple to extend the system with new types. Here’s a snippet that demonstrates the ease of using this type when assigning an executable to a Runner:

//go:generate mockgen -destination=mocks/mock_runner.go -package=mocks github.com/jahvon/flow/internal/runner Runner
type Runner interface {
    Name() string
    Exec(ctx *context.Context, e *executable.Executable, eng engine.Engine, inputEnv map[string]string) error
    IsCompatible(executable *executable.Executable) bool
}

This interface allows me to easily add new executable types by just implementing these three methods. The core execution logic remains clean and extensible:

func Exec(
    ctx *context.Context,
    executable *executable.Executable,
    eng engine.Engine,
    inputEnv map[string]string,
) error {
    var assignedRunner Runner
    for _, runner := range registeredRunners {
       if runner.IsCompatible(executable) {
          assignedRunner = runner
          break
       }
    }    if assignedRunner == nil {
       return fmt.Errorf("compatible runner not found for executable %s", executable.ID())
    }
    if executable.Timeout == 0 {
       return assignedRunner.Exec(ctx, executable, eng, inputEnv)
    }
    done := make(chan error, 1)
    go func() {
       done <- assignedRunner.Exec(ctx, executable, eng, inputEnv)
    }()
    select {
    case err := <-done:
       return err
    case <-time.After(executable.Timeout):
       return fmt.Errorf("timeout after %v", executable.Timeout)
    }
}

For testing, I use ginkgo for its expressive BDD-style syntax and GoMock to generate a mock runner. This mock simulates serial and parallel execution without the complexity of managing real subprocesses or network calls. This approach has been invaluable for verifying complex concurrent behaviors, especially when testing features like timeout handling, parallel execution limits, and failure modes in a reliable, repeatable way.

Build Better Abstractions with Service Layers

When working with third-party modules or I/O components, wrapping your interaction with a service layer is invaluable. It keeps business logic decoupled from implementation details and simplifies testing and refactoring. In flow, I use this pattern extensively for components like shell operations, file system operations, and process management.

For example, my run service abstracts away the complexities of running shell operations with the github.com/mvdan/sh library. This means if I need to change how shell commands are executed or add new shell features, I only need to update the service implementation, not the core application logic. You can explore some of my service implementations in the source code.

Good Tools Are Worth the Investment

Investing in custom tooling or incoproating open source, especially for patterns like code generation, can significantly streamline your development workflow and reduce boilerplate. In flow, I define all types in YAML and use go-jsonschema for codegen.

Here’s an example of how my Launch executable type is defined:

LaunchExecutableType:
  type: object
  required: [uri]
  description: Launches an application or opens a URI.
  properties:
    params:
	  $ref: '#/definitions/ParameterList'
    args:
      $ref: '#/definitions/ArgumentList'
    app:
      type: string
      description: The application to launch the URI with.
      default: ""
    uri:
      type: string
      description: The URI to launch. This can be a file path or a web URL.
      default: ""
    wait:
      type: boolean
      description: If set to true, the executable will wait for the launched application to exit before continuing.
      default: false

This generates both the Go type and its documentation:

// Launches an application or opens a URI.
type LaunchExecutableType struct {
	// The application to launch the URI with.
	App string `json:"app,omitempty" yaml:"app,omitempty" mapstructure:"app,omitempty"`

	// Args corresponds to the JSON schema field "args".
	Args ArgumentList `json:"args,omitempty" yaml:"args,omitempty" mapstructure:"args,omitempty"`

	// Params corresponds to the JSON schema field "params".
	Params ParameterList `json:"params,omitempty" yaml:"params,omitempty" mapstructure:"params,omitempty"`

	// The URI to launch. This can be a file path or a web URL.
	URI string `json:"uri" yaml:"uri" mapstructure:"uri"`

	// If set to true, the executable will wait for the launched application to exit
	// before continuing.
	Wait bool `json:"wait,omitempty" yaml:"wait,omitempty" mapstructure:"wait,omitempty"`
}

I’ve also built a docsgen tool that uses this same schema to generate structured documentation. This means my types, code, and documentation all stay in sync automatically. You can see the generated type documentation for Launch here.

This investment in tooling has paid off repeatedly, especially as flow’s type system has grown more complex. It reduces errors, ensures consistency, and lets me focus on implementing features rather than maintaining boilerplate code.

The Road Ahead

Looking forward, I’m excited to explore building extensions around the flow CLI, from allowing users to BYO-vault to providing a local browser-based UI for executing workflows and discovering what’s on your machine.

flow is a reflection of my passion for crafting tools that make developers’ lives easier. What started as a personal project has grown into something I believe can help other developers take control of their development experience. I invite you to contribute, star the repo to show your support, and to open issues to report bugs or suggest features!