Minarflow OS: A Local-First Task Control Center for AI Programming Agents

Minarflow OS provides a transparent, auditable, and repeatable workflow management solution for AI programming agents, addressing the black-box issue in the execution process of agents like Claude Code and Codex, enabling developers to truly take control of every execution. Its core features include local-first (data stored locally with no cloud dependency), self-hosting, step visibility with fully auditable prompts, reusable workflows, and an agent-agnostic architecture.

With the rise of AI programming agents like Claude Code and Codex, developers have gained the ability to automatically execute complex code tasks. However, the working process of these agents is often a black box—unable to see step prompts, difficult to locate links where quality declines, and each run feels like a gamble. Minarflow OS emerged as a complete local-first task control center, providing structured and transparent management for AI agent work.

Core Concepts

1. Visibility: Break down work into visible and auditable steps, with each step's prompt fully visible, allowing for locating quality issues and reusing fixed workflows.
2. Repeatability: Successful explorations can be converted into repeatable workflows, supporting one-click elevation of chat conversations to structured workflows, and allowing replacement of different agent backends (Claude Code, Codex, etc.).
3. Local-First: All data is stored locally (default ~/.minarflow-os), no cloud dependency or telemetry collection, ensuring privacy and offline availability.

Functional Architecture

Provide two launch modes:

• Run Agent Workflow (Default): For operators, use ready-made pipelines, run via npx, suitable for quick use of preset templates.
• Builder Mode: For developers, supports deep customization, includes the "Vibe-code this app" loop (describe changes → agent edits in an isolated git tree → preview → choose to promote/discard), disabled by default to ensure safety.

Tech Stack

• Vite 7: UI construction and development server
• Hono 4: Lightweight API server
• React 19 + Tailwind CSS v4: Frontend framework
• Drizzle ORM + better-sqlite3: Type-safe database access
• tsx: Production runtime

Security Model

• Single-operator system, assuming a trusted operator runs it on a trusted machine, with detailed security documentation (docs/SECURITY.md).
• Binds to loopback address (127.0.0.1) by default, authentication off; cross-device access requires changing the binding host and setting an authentication token.

Data Persistence

All state, databases, logs, and backups are stored in the local data directory (default ~/.minarflow-os). Automatic backups are performed at startup and daily to the /backups/ directory.

Feature Highlights

• Workflow Templates: Built-in templates for content generation, MVP scaffolding, SEO audits, code audits, etc.
• Gallery System: Files generated by agents enter the gallery, which can be browsed, previewed, and edited without rummaging through chat logs.

Quick Start

• Method 1 (Quick Experience): npx minarflow-os (automatically creates data directory, starts server, and opens browser).
• Method 2 (Deep Customization): Clone the repository → nvm use → pnpm install → pnpm dev (development) / pnpm build + pnpm start (production).

Comparative Advantages

Feature	Traditional Chat UI	Workflow Builder	Minarflow OS
Step Visibility	Limited	Moderate	Fully Transparent
Prompt Auditing	No	Partial	Fully Visible
Workflow Reusability	Difficult	Moderate	One-Click Copy
Agent Switching	Not Supported	Limited	Fully Supported
Self-Hosting	Product-Dependent	Product-Dependent	Natively Supported
Data Privacy	Cloud-Dependent	Product-Dependent	Local-First

Target Users and Scenarios

• Target Users: Independent developers, agency owners, advanced users.
• Typical Scenarios: Exploratory development (chat to workflow), automated code reviews, content pipelines, rapid MVP validation.

Minarflow OS represents a paradigm shift in the use of AI programming agents—from blind trust in black boxes to full transparency and control. It transforms AI agents from mysterious magic boxes into auditable, reusable, and improvable engineering components, balancing efficiency and controllability, making it an essential tool for professional development. As AI agent technology evolves, transparent, local-first management solutions will become the mainstream.