Kindflow is an opinionated platform for running AI agents as independent OS processes. Each agent gets its own directory, its own identity, and its own set of capabilities. You create and configure agents through an embedded AI terminal in the browser, and Kindflow orchestrates the rest — process lifecycle, inter-agent communication, scheduled tasks, webhooks, and integrations.

Philosophy: Agents are processes, not prompts. Each one is a first-class citizen with its own filesystem, config, and runtime. The platform handles orchestration so you can focus on what the agent should do, not how to run it.

Key features:

• Real-time WebSocket state sync — instant UI updates, zero polling
• Live agent activity feed — watch tool calls, responses, and completions as they happen
• Visual cron schedule builder — no cron syntax knowledge needed
• Procedures — define structured, reusable workflows for agents
• Dashboard with health metrics, process status, and event timeline
• Slash commands — agents discover and execute .claude/commands/ automatically

Install

curl -fsSL https://raw.githubusercontent.com/surajpratap/kindflow/main/install.sh | sh

Or install directly:

npm install -g kindflow

Prerequisites

• Node.js >= 18
• Claude Code CLI
• bun (for running agent scripts)

Quick Start

# Start the daemon (runs in background)
kindflow start

# Start with the web UI
kindflow start --web

# Create an agent
kindflow create my-first-agent

# Check status
kindflow status

# Stop the daemon
kindflow stop

Open http://localhost:7001 to access the dashboard, create agents, and configure them with AI.

How It Works

                            +-------------------+
                            |     Web UI        |
                            |   (Next.js)       |
                            |   WebSocket <--------- real-time state sync
                            +--------+----------+
                                     |
                            +--------v----------+
                            |      Daemon       |
                            |   HTTP + WS API   |
                            |   State Manager   |
                            |   IPC Hub         |
                            |   Process Manager |
                            +---+----+----+-----+
                                |    |    |
                   +------------+    |    +------------+
                   |                 |                  |
            +------v------+  +------v------+  +--------v--------+
            |   Agent     |  |   Agent     |  | Helper processes |
            |  headless   |  |  headless   |  | Cron / Email /   |
            |  process    |  |  process    |  | Telegram         |
            +-------------+  +-------------+  +-----------------+

• Agents run as isolated headless processes. Each agent is a directory with a config.json, identity file, scripts, and commands.
• The daemon is the central orchestrator. It manages agent lifecycles, routes IPC messages, serves the HTTP/WebSocket API, and auto-generates capability files.
• Configure with AI opens an embedded AI terminal in the browser. A master agent walks through discovery, design, build, and review phases to set up your agent.
• Helper processes (cron scheduler, email watcher, Telegram bot runner) are singletons shared across all agents.
• Everything is filesystem-driven. The agent's config.json is the source of truth. No central database for agent config.

Agent Directory

Each agent lives in its own directory:

~/.kindflow/agents/my-agent/
  agent/                     # Agent working directory
    config.json              # Agent configuration (source of truth)
    CLAUDE.md                # Agent identity and instructions
    .claude/commands/*.md    # Slash commands (auto-generated from procedures)
    procedures/*.md          # Structured workflows (source of truth for commands)
    scripts/                 # Tool scripts
    resources/               # Reference documents
    data/                    # Persistent data
    capabilities/            # Auto-generated capability files
  master/                    # "Configure with AI" directory
    CLAUDE.md                # Master agent instructions
    .claude/commands/        # Setup commands (S3, database, etc.)
    resources/               # Capability reference docs

Web Dashboard

The web UI at http://localhost:7001 provides real-time visibility into your agents:

• Dashboard — process counts (running/stopped/crashed), agent counts, capability summary, health indicators, uptime, and a recent event timeline
• Agents — cards showing each agent's status, model, uptime, and a live activity snapshot. Click through to the live feed or configuration
• Live Activity Feed — real-time stream of agent actions (tool calls, responses, completions). Send messages to agents directly from the browser
• Processes — table of all managed processes with status, uptime, restart counts, and start/stop/restart controls
• Process Detail — per-process event history and log viewer
• Capabilities — manage cron jobs (with visual schedule builder), HTTP endpoints, email accounts, Telegram bots, S3 profiles, and database connections

All state is pushed via WebSocket — the UI updates instantly when anything changes on the server. No polling.

Procedures

Procedures are structured markdown workflows that live in agent/procedures/. Each procedure automatically generates a corresponding slash command in .claude/commands/ so agents can execute them via /procedure-name.

agent/procedures/deploy.md      ->   .claude/commands/deploy.md
agent/procedures/daily-report.md ->  .claude/commands/daily-report.md

Create and manage procedures through the web UI at /agents/:id/procedures.

Capabilities

Kindflow provides six built-in capability types. Each follows the same pattern: a global resource (configured in the web UI) connected to one or more agents.

| Capability | Resource | What It Does | | ------------ | ---------------------- | ----------------------------------------------- | | Cron | Scheduled jobs | Triggers agent commands on a cron schedule | | HTTP | Webhook endpoints | Routes incoming HTTP requests to agents via IPC | | Email | Gmail accounts (OAuth) | Watches inboxes via IMAP, forwards to agents | | Telegram | Bot tokens | Receives messages, routes to agents by chat ID | | S3 | AWS S3 buckets | Agents read/write objects via kindflow/s3 | | Database | PostgreSQL / SQLite | Agents query databases via kindflow/database |

When you connect a resource to an agent, Kindflow auto-generates a capability file at agent/capabilities/<type>/<connection-id>.md so the agent knows what it has access to.

Agent Scripts

Agent scripts can import Kindflow client libraries:

import { createS3Bucket } from 'kindflow/s3';
import { createDatabaseClient } from 'kindflow/database';
import { createTelegramClient } from 'kindflow/telegram';

Configuration

All config and credentials are stored in ~/.kindflow/ (never in the repo):

| Path | Description | | ---------------------------- | ---------------------------------------------- | | ~/.kindflow/config.db | Global config (connections, settings, helpers) | | ~/.kindflow/encryption.key | AES-256 key for secret encryption at rest | | ~/.kindflow/agents/ | All agent directories |

Environment Variables

| Variable | Default | Description | | ------------------- | ------------- | ---------------------------- | | KINDFLOW_PORT | 7777 | Daemon API port | | KINDFLOW_DATA_DIR | ~/.kindflow | Override the data directory | | KINDFLOW_DEV | — | Set to 1 to force dev mode |

CLI Reference

kindflow start [options]     Start the daemon (background)
  --web                      Also start the web UI (port 7001)
  --port <n>                 Override the API port
  --web-port <n>             Override the web UI port
  --agents-dir <path>        Override the agents directory
  --foreground               Run in the foreground (don't daemonize)

kindflow stop                Stop the daemon

kindflow status              Show daemon status (PID, ports, logs)

kindflow create <name>       Create a new agent from template

kindflow list                List all agents

Development

Kindflow is a Turborepo monorepo. For local development:

git clone https://github.com/surajpratap/kindflow.git
cd kindflow
npm install

# Start everything in dev mode
npm run dev

# Or start individually
npm run start --workspace=@repo/daemon   # Daemon on :7777
npm run dev --workspace=apps/web         # Web UI on :7001

Project Structure

packages/
  cli/              CLI entry point (kindflow command)
  daemon/           Process orchestrator, HTTP API, IPC hub
  agent-runner/     Headless agent process wrapper
  cron-runner/      Singleton cron scheduler
  imap-runner/      Email IMAP watcher
  telegram-runner/  Telegram bot runner
  ipc/              node-ipc hub + client
  store/            SQLite persistence (sql.js)
  crypto/           AES-256-CBC encryption for secrets
  s3/               S3 client library
  database/         PostgreSQL + SQLite client
  telegram/         Telegram bot client
  types/            Shared TypeScript types
  ui/               Shared React components

apps/
  web/              Next.js web UI (dashboard + terminal)

templates/
  agent/            Default agent scaffold

Commands

npm run dev              # Start all apps in dev mode
npm run build            # Build all packages
npm run build:release    # Build CLI + web for npm publish
npm run lint             # Lint everything
npm run format           # Format with Prettier
npm run check-types      # Type-check all packages
npm run test             # Run all tests
npm run duplicates       # Check for code duplication

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for guidelines.

License

MIT