# vFlow builds Android automation workflows out of drag-and-drop modules

> vFlow is an Android app written in Kotlin that lets you assemble screen automation into workflows from reusable modules, with a dynamic editor, a coroutine based executor, event triggers and a separate privileged backend. It targets Android API 29 and newer, and the last push was on 2026-08-21.

**ChaoMixian/vFlow** — vFlow 是一款为 Android 平台设计的、强大且高度可扩展的自动化工具。它允许你通过图形化界面，将一系列“动作模块”自由组合成强大的“工作流”，从而自动完成各种日常的、重复性的屏幕操作任务。

- Repository: https://github.com/ChaoMixian/vFlow
- Website: https://chaomixian.github.io/vFlow-Docs/
- Stars: 1,297 · Forks: 106
- Language: Kotlin
- License: GPL-2.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/chaomixian-vflow

## An Android automation app that shows its own building blocks

vFlow is a visual automation tool for Android, and its premise is that automation logic should be decomposed into independent, reusable modules that a person can arrange rather than code. The README describes it as a tool for turning clicking, recognition, judgement and system operations into workflows that read like a script and edit like a diagram.

The project is written entirely in Kotlin and follows modern Android practice, with a Material 3 interface and dynamic colour theming. The README badges put the requirements on the record: Android API 29 and newer, and Kotlin 2.3.20. The repository layout confirms a conventional multi-module Android project, with app/ and core/ directories, Gradle Kotlin build files at the top level, settings.gradle.kts, gradle.properties, a debug.keystore and a signing/ directory.

The feature list is specific about what the editor does. You build a flow by dragging and clicking. Every function, whether a click, a text lookup or a judgement, is a separate module. The output of one module can feed the next through what the README calls magic variables. There is if and else branching and looping, and the editor UI changes shape depending on the parameters you pick, for instance showing only the variable types that apply inside an if module. Permissions are requested clearly before a workflow runs, with a single management entry point, and workflows can be imported and exported for backup, restore and sharing.

The stated audience is wide, from people who want their daily check-in done for them to developers looking for a way to sketch an automated test flow, and the architecture section is written to be read by the second group.

## Modules declare their own inputs, outputs and permissions

The module system is the core of the project, and the README describes it in enough detail to understand the design.

Everything, whether it is an action, a trigger or a control flow node, is built on the ActionModule interface. Most modules extend BaseModule, while paired or block shaped control flow modules, such as if, else and loop constructs, extend BaseBlockModule. A module carries more than its behaviour: it declares ActionMetadata, an InputDefinition, an OutputDefinition, the permissions it needs, a summary string, and optionally a ModuleUIProvider that supplies a custom editing screen. The named examples are ClickModule, IfModule and TimeTriggerModule.

A central ModuleRegistry does the registration, at app/src/main/java/com/chaomixian/vflow/core/workflow/module/ModuleRegistry.kt. It injects the ApplicationContext into each BaseModule and exposes the registered modules by category to the action picker, the editor and the executor. The built-in categories listed in the README cover triggers, interaction, logic, data, file, network, system, Core, Shizuku, snippet and UI components.

Two constraints on module authors are worth noting because they show where the sharp edges are. The README asks that enum parameters save stable constant values rather than localised display text, so that a workflow saved in one language still runs in another. And if you replace a parameter value that shipped in a previous release, you are asked to add a compatibility mapping such as legacyValueMap at the definition layer, while new modules should not carry speculative compatibility logic.

## The editor generates its forms from the module definitions

WorkflowEditorActivity is the core user interface, and it works on a list of ActionStep objects. ActionStepAdapter renders those steps as the visible cards, and ActionEditorSheet builds the editing form for a step by combining the module's InputDefinition, its dynamic input definitions and its optional ModuleUIProvider.

The README is explicit that this is not a static form. Beyond assembling fields, the editor handles magic variables, parameter visibility, error handling policy, block structure editing and dedicated configuration entry points for some modules. Dynamic input definitions are what make the visible form change when you pick a different parameter, so the same if module shows a different set of options depending on whether the variable you compare is a state, a number or a string.

The consequence for a user is that the module authors, not the app, decide what configuration looks like. A module with a plain set of parameters gets a generated form, and a module with an unusual parameter screen supplies its own provider. That keeps the app from growing a special case for every module, at the cost of a workflow being only as configurable as its modules are.

The development guide is part of the repository rather than the README, at docs/CONTRIBUTION.md, and the module development instructions in the README end by asking for tests, with unit tests under app/src/test/java when parsing, execution, typing or compatibility behaviour changes.

## The executor runs on coroutines and carries one shared context

WorkflowExecutor is where a workflow actually runs, and it is built on coroutines. It maintains running instances, a re-entry policy, logging, timeouts and stop control, and it constructs an ExecutionContext that carries variables, magic variables, trigger data, service instances, step outputs and a temporary working directory in one place.

That context is the mechanism that makes module chaining work. A step writes its output into the context, and the next step reads it from there, which is why the editor's magic variables and the runtime agree on names. The executor handles more than a straight sequence: conditional branches, loops, sub-workflows, failure policy and notification status synchronisation are all its responsibility.

Triggers and background services sit beside it. TriggerService, VoiceTriggerService and TimeTriggerReceiver listen for system events and start workflow execution. The README says this is what lets a workflow run either manually or driven by time, notification, clipboard, location or voice events. A voice trigger in particular is a differentiator from a purely visual tool, since it means the flow can be started without touching the screen at all.

The failure policy is the part the README does not expand on. A workflow can fail partway through, and the executor tracks that, but the README does not describe what a failure does to a step that already wrote output, and it does not say whether a failure inside a loop aborts the loop or the whole run. If you are building anything long running, that is a question worth answering in the source before you rely on it.

## vFlowCore.dex is the privileged half, reached over a local socket

vFlow is split in two. A workflow engine runs inside the Android application process, and a separate backend called vFlowCore.dex starts on demand. The engine handles module registration, editing, execution and trigger scheduling, while Core takes care of the system capabilities that need higher privileges or their own process isolation.

The core/ module builds the file app/src/main/assets/vFlowCore.dex, and the app side launches and connects to it through CoreLauncher and VFlowCoreBridge. The current Core follows a master and worker design: the master receives requests and routes them to a Shell worker or a Root worker. Communication between the app and Core goes over a local socket, and the README says both TCP and Unix domain socket transports are supported, with some high privilege system capabilities exposed to workflows through Core.

The Shizuku category in the module registry and the Shell and Root workers in the architecture diagram point at the same thing. Some operations on a modern Android device cannot be done by an ordinary app, and the project answers that with a second process that can hold higher privileges, with root as an option. That is also why the module categories include a dedicated Core category rather than folding those capabilities into the ordinary system ones.

The architecture image in the repository, docs/vFlow_Core_Architecture.png, is the fastest way to see the split, and the README links it right after the description.

## Building it takes a clone, Android Studio and a Gradle sync

The project ships releases, with the latest linked through a GitHub releases badge, but the README's build instructions are for working on the code rather than installing a binary.

```bash
git clone https://github.com/ChaoMixian/vflow.git
```

After the clone, you open the project in Android Studio, wait for the Gradle sync to complete, and run it onto a device or an emulator. There is no separate build command given, and no command line packaging step in the README, so the Gradle wrapper in the repository, gradlew and gradlew.bat, is the path a contributor uses through the IDE rather than a documented shell recipe.

The contribution flow is the standard fork, branch, commit, push, pull request sequence, with the branch naming example feature/AmazingFeature. Beyond code, the project keeps a Discord server and a QQ group linked from the README, and a developer guide at docs/CONTRIBUTION.md.

The repository also has a DISCLAIMER.md at the top level, and the README points to it from a warning block that says the software involves automation operations and root permission execution, which may lead to device damage, data loss and account bans, with all risk borne by the user and none of the responsibility by the developer. That is a more candid statement than most projects of this kind make, and it belongs in the first five minutes of evaluating an automation tool that can touch a root shell.

## A young project, a permissive licence and a candid gap statement

vFlow is licensed GPL-2.0-or-later, with the licence file at the top of the repository. GPL-2.0 is a different choice from the MIT or Apache licences common in the Android tooling world, and it matters for anyone who wants to bundle vFlow modules into a closed source app, since derived work has to stay under the same terms.

The project's own assessment of its maturity is worth quoting rather than paraphrasing. The sponsorship section says vFlow is still growing, that there is a fairly large feature gap compared with mature software, and that it is currently kept running through a free platform and does not accept sponsorships. The list of past donors is included in a collapsed block for the record.

The release history is consistent with that. Version 1.5.2 shipped on 2026-05-23, v1.5.2-pr1 on 2026-05-13 and v1.5.3-pr1 on 2026-05-27, so the project uses a pr suffix for pre-releases and is not shy about publishing them alongside stable tags. The last push was on 2026-08-21 and the repository is not archived, so work is ongoing, though the README does not state a release cadence.

There is also a docs/ directory with the documentation site, the screenshots used in the README and the architecture image, and a scripts/ directory at the top level, whose contents the README does not describe. A developer guide, a contributing guide, a code of conduct and an AI policy file round out the repository, which is a fuller governance setup than the age of the project would suggest.

## Conclusion

vFlow fits someone who wants to automate repetitive Android screen work without writing a script, and it does not fit someone who needs a stable long-lived tool, since the project describes its own feature gap compared with mature software and ships release candidates with a pr suffix. Before using it, read DISCLAIMER.md, because the README states that the app involves automation, root execution and the risk of device damage, data loss and account bans, with all risk on the user. Verify first that your device runs Android API 29 or newer, and decide deliberately whether the privileged vFlowCore.dex path is needed at all before granting it root access.

## FAQ

### What is vFlow and what does it do on Android?

vFlow is a Kotlin Android app for visual automation, where actions, triggers and control flow blocks are assembled into workflows. The editor generates forms from module definitions, and workflows can be run manually or driven by time, notification, clipboard, location or voice events.

### What Android version does vFlow require?

The README badges state Android API 29 or newer, and the project is built with Kotlin 2.3.20. It is built as a standard Android Studio project with Gradle.

### What is vFlowCore.dex and why is it separate?

The core/ module builds app/src/main/assets/vFlowCore.dex, a backend started on demand for system capabilities that need higher privileges or process isolation. It uses a master and worker design, routing requests to a Shell or Root worker, and the app connects to it over a local socket with TCP and Unix domain socket transports.

### How do I add a new module to vFlow?

Create the module class under the module directory in the appropriate category, extend BaseModule or BaseBlockModule, define a stable id, metadata, input and output definitions and the execute logic, then register it in the initialize() function of ModuleRegistry.kt. Parameters that need a custom screen supply a uiProvider, and enum values should store stable constants rather than localised text.

### What licence is vFlow released under?

The project uses the GNU General Public License v2.0 or later, GPL-2.0-or-later, with the licence file at the top of the repository. The README also points to a DISCLAIMER.md covering the risks of automation and root execution.

## Sources

- [ChaoMixian/vFlow on GitHub](https://github.com/ChaoMixian/vFlow)
- [License: GPL-2.0](https://github.com/ChaoMixian/vFlow/blob/master/LICENSE)
- [Project website](https://chaomixian.github.io/vFlow-Docs/)
- [README](https://github.com/ChaoMixian/vFlow/blob/master/README.md)
- [Releases](https://github.com/ChaoMixian/vFlow/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/chaomixian-vflow