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!

Note

This page covers the architectural decisions and design rationale behind flow. For a deep technical reference, see the architecture docs on DeepWiki.

Last updated: May 2026

Flow is a YAML-driven task runner and workflow automation tool designed around composable executables, built-in secret management, and cross-project automation. This document covers the core architectural decisions and how the pieces fit together.

Design Philosophy

• Developer-Centric: Flow should be designed with developers in mind, providing a powerful yet intuitive interface for managing automation tasks.
• Composable: Flow should allow users to compose complex workflows from simple, reusable executables, enabling cross-project automation and collaboration.
• Discoverable: Flow should make it easy to find and run executables across multiple projects and workspaces, with a focus on discoverability and usability.
• Local-first: Flow should be able to be run entirely on a local machine, with no external dependencies or cloud services required.
• Malleable: Flow should be easily extensible and customizable, allowing users to adapt it to their specific needs and use it in a variety of contexts.

System Overview

Flow’s architecture centers on a CLI-first design where the Go-based CLI engine handles all business logic, with other interfaces acting as presentation or integration layers.

The desktop app and other interfaces communicate with the CLI through process execution, with each user action spawning a discrete CLI command. Because of this, it’s important that CLI operations are fast and efficient, which is achieved through caching and optimized data integrations.

Technical Stack

Core Languages

• Go - CLI engine, business logic, and execution runtime
• TypeScript/React - Desktop frontend with type-safe CLI communication
• Rust - Desktop backend via Tauri framework

User Interface

• Terminal: Bubble Tea with custom tuikit component library
• Desktop: Tauri + Mantine UI for VSCode-like interface
• CLI: Cobra for command structure and auto-completion

Core Libraries

• YAML Processing: yaml.v3 for YAML parsing and serialization
• Process Management: mvdan/sh for shell execution
• Expression Engine: Go’s text/template + Expr for conditional logic and templating
• Markdown Rendering: Glamour and react-markdown for auto-generated documentation UI viewers

Organizational Model

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

Execution Engine

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.

Vault System

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").

Template System

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.

Terminal UI

The terminal UI is built on Bubble Tea and Glamour, with most views defined in the tuikit component library.

Desktop Application

The desktop experience is evolving into Mochi, a local-first DevOps dashboard that wraps Flow’s execution engine. See the Mochi architecture page for more on where the desktop is headed.

Extensions and Integrations

GitHub Actions and CI/CD

Being able to run the same flow executables locally and in CI has always been a goal. A GitHub Action and Docker image are available for use across CI/CD systems. All flowexec organization repositories use this action.

Model Context Protocol

MCP server integration for AI assistant compatibility:

• Workspace browsing and executable discovery
• Natural language workflow generation
• Debug assistance with full context

Framework chosen: mcp-go

While implementing, I wanted to use MCP resources but support across clients is still low. I implemented the server with just Tools and Prompts to get the best experience across the most clients.

There is a get_info tool that provides the AI with context about Flow, the current workspace, and expected schemas. This along with server instructions provided the best experience with AI assistants during my testing.

Known Limitations and Future Work

• WASM Plugin System: Allowing Flow to be extended with WebAssembly plugins for custom executable types and template generators.
  • Note to self: I did a small POC of this but wasn’t very happy with the development experience on the plugin side. WASM may not be the right fit for Flow’s extensibility model, but I want to keep it open as a possibility.
• AI Runner: Integrating AI models to assist with workflow generation, debugging, and context-aware suggestions.
• Containerized Execution: Running executables in isolated containers for security and resource management.
• Current Technical Debt:
  • No dependency graph analysis (circular reference detection)

Resources

• Documentation
• DeepWiki Architecture Reference
• GitHub Repository

For implementation details, see the repository and documentation.

Mochi is a local-first DevOps dashboard built on top of Flow. Point it at a directory and it finds your development workflows and turns them into a unified, AI-enriched interface.

Design Philosophy

• Local-first: No cloud sync, no external accounts required. Your workflows never leave your machine.
• Built on Flow: Mochi inherits Flow’s execution engine, secret management, and composability model rather than building a parallel system from scratch.
• AI-enriched, not AI-dependent: AI augments the experience with workflow analysis and suggestions, but the tool works without it.
• Unified discovery: Meet developers where they are instead of requiring migration to a new workflow format.

System Overview

Mochi wraps Flow’s CLI engine as its execution runtime. The desktop app and CLI share the same binary, with the desktop communicating through process execution in the same pattern as Flow’s architecture. Discovery runs at startup and on sync, after which all discovered executables are available in both the dashboard and CLI identically.

The desktop is not yet released, but the architecture is taking shape. Here’s a preview:

Auto-Discovery Engine

Mochi’s discovery layer imports executables from common developer workflow files without requiring any configuration changes.

Discovered executables are treated identically to native Flow executables once imported: they appear in the browse interface, support the same reference patterns, and can be composed into larger workflows. The sync step surfaces naming conflicts clearly so nothing is silently overwritten.

This discovery system is built on the same import infrastructure in Flow’s core. See the Flow architecture for implementation details.

AI Enrichment Layer

Mochi connects to an AI provider for workflow analysis, troubleshooting suggestions, and workflow context. You can use Anthropic’s cloud API or a local Ollama instance depending on your preference and privacy requirements.

The enrichment layer is optional and additive. The dashboard is fully functional without it, and workflow definitions are processed locally before anything is sent externally.

Desktop and CLI Architecture

Mochi ships as a single binary that includes both the CLI and the Tauri desktop backend. I chose Tauri because it was the most interesting option at the time, given my interest in learning Rust and building a desktop app without the overhead of Electron. The frontend is TypeScript/React with Mantine UI.

Type safety across Go, TypeScript, and Rust is maintained through code generation from a shared JSON schema. Schema changes propagate to all three languages automatically during the build, and the same schema generates documentation as a side effect. This has been one of the best quality-of-life decisions in the project — make a change in one place and have confidence everything stays consistent.

Resources

• mochiexec.io
• Flow Architecture
• GitHub (flowexec org)