Tachikoma Automation Platform

Tachikoma: Distributed Automation & Workflow Orchestration Platform

Tachikoma is a full-featured automation and orchestration platform designed to coordinate complex workflows across filesystems, Docker containers, system commands, and shell scripts. The platform enables users to define, execute, and monitor automation pipelines in a structured, extensible, and observable way.

Originally conceived as a CLI-based automation tool, Tachikoma evolved into a client–server platform with a web-based control plane, supporting asynchronous execution, distributed workers, and real-time job visibility. This evolution reflects a deliberate shift from local task automation to multi-user, multi-runner orchestration at scale.

Architectural Overview

Tachikoma is implemented as a monorepo with clearly defined layers and shared infrastructure: • Core Execution Engine A shared, framework-agnostic engine responsible for plan parsing, step orchestration, runner dispatch, and execution state management. • Backend API (Control Plane) A Node.js/TypeScript service exposing RESTful APIs for plan management, job execution, scheduling, and observability. • Web Frontend (UI) A React 18 application providing plan authoring, execution control, and real-time job monitoring.

This separation ensures strong cohesion within each layer while enabling independent evolution of UI, API, and execution logic.

Workflow Model & Execution Semantics

At the heart of Tachikoma is a declarative workflow model: • Plans are defined as JSON-based workflows • Each plan consists of an ordered sequence of steps • Steps are executed by explicitly defined runners, such as: • Shell / system command runners • Docker container runners • File and filesystem operation runners • Custom runners via plugins

Each step is: • Validated against a schema • Executed deterministically • Captured with structured logs and execution metadata

This design allows workflows to be versioned, audited, and reused across environments.

Asynchronous Job System & Background Processing

Workflow execution is handled through an asynchronous job system, decoupling execution from request lifecycles: • Plans are submitted as jobs • Jobs execute asynchronously and track lifecycle states (queued, running, completed, failed) • Execution output, logs, and errors are persisted and queryable

The job system is powered by: • Redis for scheduling and coordination • BullMQ for queueing, retries, backoff strategies, and worker concurrency • Background workers that can scale horizontally

This architecture enables: • Long-running workflows • Concurrent execution • Fault tolerance and retries • Distributed execution across multiple hosts

Backend API & Observability

The backend exposes a comprehensive REST API, documented via Swagger/OpenAPI, covering: • Plan CRUD operations • Job submission and cancellation • Execution status and history • Log retrieval and inspection • Runner and system health endpoints

Key backend technologies include: • Node.js + TypeScript for type safety and maintainability • Express for HTTP routing • Prisma for database access and schema management • Redis for queueing and scheduling • Docker for execution isolation and reproducibility

Structured logging and job metadata enable traceability and operational insight into every workflow execution.

Web UI & User Experience

The React 18 frontend provides a rich control surface for interacting with the platform: • Plan creation and management • Job submission and execution history • Real-time job status updates • Log streaming and inspection • Clear visualization of workflow steps and outcomes

UI technologies include: • React 18 with modern hooks and concurrent features • Tailwind CSS for utility-driven styling • Material UI (MUI) for composable, accessible components

The UI is designed to support both power users and operational monitoring use cases.

Extensibility & Plugin Architecture

Extensibility is a first-class concern in Tachikoma’s design: • Runners can be added to support new execution environments • Schemas define validation rules for new step types • A plugin interface allows external modules to extend execution logic, inputs, and outputs

This makes Tachikoma adaptable to: • CI/CD automation • Infrastructure orchestration • Local developer tooling • Data processing pipelines • System administration workflows

Testing, Quality & Reliability

The platform includes comprehensive testing and quality controls: • Jest for unit and integration testing • Deterministic execution paths for reproducible workflows • Clear separation of execution logic and infrastructure concerns • Strong typing across API, engine, and UI layers

These practices ensure confidence as the platform evolves.

Platform Vision & Impact

Tachikoma demonstrates how automation tooling can evolve into a platform: • From scripts to structured workflows • From synchronous commands to asynchronous orchestration • From local automation to distributed execution

By combining declarative workflows, extensible runners, and a modern control plane, Tachikoma provides a scalable foundation for automation across development, operations, and infrastructure domains.