Skip to content
BranchesTags

Repository files navigation

😼 devOS

Development Operating System

devOS is a development acceleration toolkit that combines visual design tools, code generation, Ralph-first automation, and version-controlled snippets to eliminate the gap between prototype and production code.

drawUML

TL;DR — devOS in 5 Minutes

Assumptions

  • You are inside an active git repository
  • You have Node.js installed
  • The dev command is installed with pipx

Configure a Project

Point devOS at your project's directories and language once, then everything else (code gen, snippets, and automation utilities) reads from that config.

dev config

This writes specs/project_config.json with paths for DAOs, DTOs, routes, tests, and contract synchronization outputs.

Build Project Artefacts

Generate DAOs, DTOs, CRUD routes, and tests from your JSON specification:

dev build project_name               # full build — all artefacts for the named project
dev build dao project_name           # DAOs only
dev build dto project_name           # DTOs only
dev build api project_name           # API routes only
dev build tests api project_name     # API test scaffolding only
dev build tests services project_name # service test scaffolding only
dev build context .py,.md .          # aggregate project context file
dev sync                              # sync classes marked with @contract across Python/TypeScript

Launch the ORM Builder UI

Open the visual entity designer (drawORM) in your browser:

dev ui path,to,devOS

If this doesn't work, make sure you have Node.js installed and run npm install in the devOS/frontend directory.

Design entities, set field types and relationships, then export directly to specs/dao_spec.json.

Managing Credentials

Store credentials as JSON documents in Redis. Project runtimes load only the credential bundle for the current Git project. General credentials remain available only through the explicit secrets commands.

Configure Redis with either a single URL:

devos_redis_url=rediss://username:password@host:6379/0

Or separate devos_redis_host, devos_redis_port, devos_redis_username, devos_redis_password, devos_redis_db, and devos_redis_ssl variables. The URL takes precedence when both forms are present.

Install a project-owned loader and configuration template:

dev setup credentials

Push the current .env, set one value, or materialize the project credentials:

dev set credentials             # refuses to overwrite existing keys
dev set credentials true        # force an overwrite
dev set credential API_TOKEN token-value
dev get credentials

General values use the existing secrets command:

dev set secrets secret_key secret_value
dev get secrets secret_key

The get command copies the value to the clipboard without printing it. Without a project name, listing shows global key names, the current project's key names, and the registered projects. With a project name, it shows only that project's key names:

dev list credentials
dev list credentials project-name

Export the complete credential estate as one .env file per bundle. The destination is relative to your home directory and should remain outside OneDrive and Git:

dev export credentials vault-export

Copy the whole store into a second Redis database with a lossless JSON mirror. Export writes one file per stored key, dropping the devos: prefix and turning the remaining colons into folders, so devos:projects:devOS becomes projects/devOS.json:

dev export store "Protocol/00 PKM/3 Resources/vault"

Both commands talk to whichever database the current .env describes, so the devos_redis_* variables are what select the destination. Point them at the second database, then import. Import writes only to Redis, never to .env, and never replaces a value that is already there: an existing credential is kept and reported, everything else lands, and the project registry is unioned.

dev import store "Protocol/00 PKM/3 Resources/vault"

The exported tree holds every credential in plaintext, so delete it once the import is done.

The one-time legacy migration is intentionally a script rather than a permanent command:

python scripts/migrate_credentials_vault.py

Managing Snippets

Snippets are reusable code stored in a git-backed snippets repository. Pull/push snippets with explicit from/to paths:

dev get snippet from python
dev get snippet from python,sqlalchemy_adapter.py
dev get snippet from python,sqlalchemy_adapter.py to path,to,local,sqlalchemy_adapter.py
dev set snippet from path,to,local,adapters.py to python,database-adapters,adapters.py

Categories include Python adapters, TypeScript components, GitHub Actions workflows, Dockerfiles, prompts, and Copilot instruction files.

Ralph-First Workflow

devOS now prioritizes a Ralph-first local workflow. Keep your AGENTS.md and ralph.sh files synchronized with prompt snippets using dev-sync.

Keeping devOS Up to Date

Add devOS_profile.ps1 to your PowerShell profile. It exposes a dev-update alias that pulls the latest changes, reinstalls the package into the currently activated environment, and returns you to your project directory:

# From your project directory (devOS lives one level up by default)
dev-update

# Specify a different devOS location or return directory
dev-update -DevOSPath "C:/path/to/devOS" -TargetDir "my-project"

Activate your environment before running dev-update — the script installs directly into whatever pip is on your PATH.

Fast Local Sync for AGENTS.md and ralph.sh

To keep local instruction files aligned with snippets in prompts/, add this function to your PowerShell profile (or to devOS_profile.ps1):

# A function that will run devOS to update specific files locally.
function Sync-devOS {
  param(
    [string]$Target = ""
  )

  switch ($Target.ToLower()) {
    "read_agents" {
      dev get snippet from prompts,AGENTS.md to AGENTS.md
    }
    "read_ralph" {
      dev get snippet from prompts,ralph.sh to ralph.sh
    }
    "write_agents" {
      dev set snippet from AGENTS.md to prompts,AGENTS.md
    }
    "write_ralph" {
      dev set snippet from ralph.sh to prompts,ralph.sh
    }
    default {
      Write-Host "Unknown target: $Target. Supported targets: read_agents, read_ralph, write_agents, write_ralph."
    }
  }
}
Set-Alias dev-sync Sync-devOS

Example usage:

# Pull down snippet updates
dev-sync read_agents
dev-sync read_ralph

# Push local edits back into snippets
dev-sync write_agents
dev-sync write_ralph

This gives you a quick read/write partition so you can edit locally, then sync back to devOS snippet storage immediately.

Table of Contents

Philosophy

The advent of LLMs means there's no excuse for not having tests, documentation, and high-quality clean code. devOS is built on these principles:

  1. Prototype first, refactor with design — Write messy code to understand the problem, then use devOS to rewrite it properly
  2. First version is always throwaway — Accept that prototypes are learning tools, not production artifacts
  3. Specifications over implementations — JSON specifications export to any language and avoid AST parsing errors
  4. Version-controlled development assets — Snippets, prompts, and configs live in git branches, not scattered files
  5. Ralph-first local workflows — Keep prompt and instruction files synced and runnable locally

devOS is not distributed via PyPI. It is cloned locally and installed as an editable pipx tool so the dev command is available across projects. The cloned repository lets you:

  • Customize default configs and settings for your team
  • Maintain your own snippets as git branches
  • Use it as a Redis-backed credential database client
  • Run local Ralph workflows without cloud dependencies

Core Components

drawORM — Visual ORM Designer

A UI ORM builder powered by React Flow, inspired by drawSQL.

Purpose: Refactoring tool for data models

  • Design your domain entities visually
  • Generate DAOs, DTOs, CRUD routes, and tests automatically
  • Syncs specifications bidirectionally (like xstate, but for Clean Architecture)

drawUML — Specification Builder

A domain-specific visual language on top of JSON for defining:

  • Endpoints and schemas
  • Advanced behaviors (on-delete rules, data transformations, pre/post-instantiation hooks)
  • Business logic constraints

Why JSON specifications?

  • Easier to export to different programming languages
  • Less error-prone than building abstract syntax trees
  • Machine-readable for LLM code generation
  • Type-safe and version-controllable

Ralph Workflow Utilities

devOS provides utilities for keeping prompt and automation assets synced locally:

  • Sync AGENTS.md and ralph.sh with snippet storage
  • Reuse version-controlled prompts across projects
  • Keep workflows local-first for proprietary codebases

Installation

Prerequisites

  • Node.js v18 or above
  • Python 3.12 or above
  • An active git repository (devOS extracts repo name, tags, etc.)
  • (Optional) Tooling required by your local ralph.sh workflow

Install globally on macOS

Install devOS as an isolated command-line tool with pipx. The editable installation exposes dev everywhere while continuing to execute the source in the cloned repository. Python 3.14 can be shared with cliOS and satisfies devOS's Python requirement.

Confirm that Homebrew and pipx are available.

brew --version
pipx --version

Install Python 3.14 through Homebrew.

brew install python@3.14
"$(brew --prefix python@3.14)/bin/python3.14" --version

Clone devOS into ~/protocol if it is not already present.

mkdir -p "$HOME/protocol"
git clone https://github.com/kesler20/devOS.git "$HOME/protocol/devOS"

Install the repository with pipx.

pipx install \
  --python "$(brew --prefix python@3.14)/bin/python3.14" \
  --editable "$HOME/protocol/devOS"

If pipx reports that devos is already installed, replace that installation.

pipx uninstall devos
pipx install \
  --python "$(brew --prefix python@3.14)/bin/python3.14" \
  --editable "$HOME/protocol/devOS"

Make sure the directory where pipx exposes commands is on PATH, then restart the login shell.

pipx ensurepath
exec zsh -l

Verify that the executable is available.

command -v dev
pipx list

command -v dev should resolve to ~/.local/bin/dev. Run devOS commands inside an active Git repository because devOS uses the current repository for project configuration.

Install globally on Windows

Install devOS as an editable global tool with uv. Python 3.14 can be shared with cliOS and satisfies devOS's Python requirement.

uv python install 3.14
uv python find 3.14

Clone devOS into the protocol folder if it is not already present.

New-Item -ItemType Directory -Force -Path "$HOME\protocol" | Out-Null
git clone https://github.com/kesler20/devOS.git "$HOME\protocol\devOS"
Set-Location "$HOME\protocol\devOS"

Install the repository. The editable installation keeps dev connected to the source checkout.

uv tool install --python 3.14 --editable .
uv tool update-shell

Open a new PowerShell window after uv tool update-shell, then verify the command from an active Git repository.

Set-Location "$HOME\protocol\devOS"
Get-Command dev
dev version

If devOS is already installed through uv, replace or refresh the installation.

uv tool install --force --python 3.14 --editable "$HOME\protocol\devOS"

Configure devOS

  1. Run the setup command:
dev setup

This will:

  • Install the ORM builder UI (React frontend)
  • Configure environment variables
  • Set up code snippets as git branches
  1. Configure credential storage:

Set the Redis bootstrap variables, then run dev setup credentials. Redis becomes the credential authority. A local .env remains an explicit materialization and offline fallback.

  1. Verify installation:
dev version

Update or remove devOS

Because the installation is editable, source changes take effect immediately. Pull repository updates normally. Reinstall only when dependencies, entry points, or package metadata change.

git -C "$HOME/protocol/devOS" pull
pipx reinstall devos

Remove the global command without deleting the repository.

pipx uninstall devos

On Windows, pull changes and refresh the uv installation with the following commands.

git -C "$HOME\protocol\devOS" pull
uv tool install --force --python 3.14 --editable "$HOME\protocol\devOS"

Remove the Windows installation without deleting the repository.

uv tool uninstall devos

Key Concepts

Specification-Driven Development

devOS assumes you update DAOs and endpoints via specifications, freeing you to focus on:

  • Writing use cases
  • Implementing adapters (services)
  • Creating comprehensive tests

The Credential Database

Redis stores one JSON document for general credentials and one per Git project. Applications load only their own project document at import time through their copied configs.py bundle. General credentials are available only through the explicit secrets commands. Redis is authoritative when available. If it cannot be reached, values already loaded from a local .env remain in place.

Explicit exports preserve arbitrary JSON values under:

vault-export/
  general/credentials.json
  projects/<project-name>/credentials.json

Snippets as Version-Controlled Assets

Snippets are reusable code stored as git branches that can be pulled into any project:

  • Adapters, utils, and helpers
  • Prompts and AGENTS.md files
  • GitHub Actions workflows
  • Copilot instruction files
  • Dockerfiles and mocks

Philosophy: Clone devOS, update snippets in your own repo, and use it to speed up development across all your projects.

Configuration Paths

Paths are entered as comma-separated lists to remain platform-agnostic.

home_root configs:

  • Global configs using the user home directory as root
  • Paths start from ~ or $HOME

project_root configs:

  • Project-specific paths starting from the repository root
  • Define directories, filenames, and programming languages for generated code

ORM Builder UI Guidelines

  • Use array types to indicate one-to-many relationships
  • AI autocomplete is available in the editor for endpoint definitions
  • Visual design syncs bidirectionally with JSON specifications

Architecture

System Overview

graph TB
    subgraph "Visual Design Layer"
        A[drawORM UI]
        B[drawUML UI]
    end

    subgraph "Specification Layer"
        C[JSON Specifications]
        D[Domain-Specific Rules]
    end

    subgraph "Code Generation Layer"
        E[DAO Generator]
        F[DTO Generator]
        G[Route Generator]
        H[Test Generator]
        I[LLM Codegen]
    end

    subgraph "Local Workflow"
      J[Ralph Scripts]
      K[Prompt Snippets]
      L[Local Task Execution]
    end

    subgraph "Developer Assets"
        M[Snippets<br/>Git Branches]
        N[Redis Credential Database]
        O[Templates]
    end

    A --> C
    B --> C
    C --> D
    D --> E
    D --> F
    D --> G
    D --> H
    D --> I
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
    J --> K
    K --> L
    M --> J
    N --> J
    O --> E
    O --> F
    O --> G
    O --> H
Loading

Data Flow

sequenceDiagram
    participant Dev as Developer
    participant UI as drawORM/drawUML
    participant Spec as JSON Specification
    participant Gen as Code Generator
    participant Ralph as Ralph Workflow
    participant Local as Local Task Runtime

    Dev->>UI: Design entities & endpoints
    UI->>Spec: Generate JSON specification
    Spec->>Gen: Parse and validate
    Gen->>Ralph: Create local generation task
    Ralph->>Local: Execute code generation
    Local->>Ralph: Apply templates & snippets
    Gen->>Dev: Produce DAOs, DTOs, routes, tests
    Dev->>Local: Review generated changes
Loading

Clean Architecture Layers

devOS enforces Clean Architecture principles through code generation:

┌─────────────────────────────────────────┐
│          Domain Layer                    │
│  • entities.py (DAOs)                   │
│  • Business rules & constraints         │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│        Use Cases Layer                   │
│  • crud_dto.py, custom_dto.py           │
│  • use_cases.py                         │
│  • ports.py (interfaces)                │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│      Infrastructure Layer                │
│  • crud_routes.py, custom_routes.py     │
│  • adapters.py                          │
│  • schema.py (external contracts)       │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│          Tests Layer                     │
│  • unit_tests.py                        │
│  • integration_tests.py                 │
└─────────────────────────────────────────┘

Dependency Rule: Inner layers never depend on outer layers.

Code Generation

Supported Languages

  • Python (FastAPI, SQLAlchemy, Pydantic)
  • TypeScript (React, Express, type definitions)
  • More languages via LLM codegen when not explicitly supported

Generation Workflow

  1. Design in drawORM/drawUML — Visually define entities, relationships, and endpoints
  2. Export JSON specification — Domain-specific rules encoded as JSON
  3. Run code generator:
dev build project_name               # Generate all artifacts
dev build dao project_name           # Generate DAOs only
dev build dto project_name           # Generate DTOs only
dev build api project_name           # Generate API routes only
dev build tests api project_name     # Generate API test scaffolding only
dev build tests services project_name # Generate service test scaffolding only
dev sync                              # Translate all classes in @contract files
  1. LLM Integration — When programming language is not specified, devOS invokes an LLM codegen workflow using AGENTS.md for architectural guidance

Test Generation

  • Service tests: Code generator searches for files with @service marker
  • API tests: Generates tests only for endpoints created by devOS code generator

Extending Generated Code

Generated code is importable and extensible:

# Import generated routes
from generated_endpoints import app

# Extend with custom routes
@app.route("/custom_endpoint", methods=["POST"])
def custom_endpoint():
    return {"message": "Custom logic here"}

Suggested Project Structure

project/
├── domain/
│   └── dao.py                    # Generated entities
├── use_cases/
│   ├── crud_dto.py               # Generated CRUD DTOs
│   ├── custom_dto.py             # Your custom DTOs
│   ├── use_cases.py              # Your business logic
│   ├── ports.py                  # Interfaces for adapters
│   └── utils/                    # Shared utilities
├── infrastructure/
│   ├── crud_routes.py            # Generated CRUD routes
│   ├── custom_routes.py          # Your custom routes
│   ├── adapters.py               # External service adapters
│   └── schema.py                 # Third-party contracts
└── tests/
    ├── unit_tests.py             # Generated unit tests
    └── integration_tests.py      # Generated integration tests

Software Design

React Component Architecture

The frontend is built with React + TypeScript following event-driven patterns outlined in AGENTS.md.

classDiagram
   App <|-- Console
   Console <|-- UmlDiagram
   Console <|-- NavbarComponent
   Console : - edges
   Console : - nodes
   Console : + handleCopy()
   Console : + createTable()
   Console : + onEventNodesChange()
   Console : + onEventEdgesChange()

   UmlDiagram : - gridTable
   UmlDiagram : + viewComment
   UmlDiagram : + objectComment
   UmlDiagram : + insertMode
   UmlDiagram : + findIndex()
   UmlDiagram : + addRow()
   UmlDiagram : + deleteRow()
   UmlDiagram : + handleNavigation()
   UmlDiagram : + handleObjectClick()

   NavbarComponent : - sideBarView
   NavbarComponent : + onEventExportJSON()
   NavbarComponent : + onEventImportJSON()
   NavbarComponent : + onEventCreateTable()
Loading

Console Design (Container Component)

View: The Console component is divided into two sections:

  1. NavbarComponent — Uses createTable and handleCopy to modify parent state
  2. React Flow Grid — Uses UmlDiagram as custom nodes:
const nodeTypes = { umlDiagram: UmlDiagram };

State: The node data structure:

{
  id: `node-${nodes.length + 1}`,
  type: "umlDiagram",
  position: { x: 10, y: 10 },
  data: {
    objectName: "Object Name",
    comment: "Object Description",
    color: getRandomColor(),
    gridTable: [
      {
        visibility: "+",
        signature: "",
        type: "",
        comment: "signature description",
      },
    ],
  },
}

This data is passed to UmlDiagram via the data prop and modified through:

  • addRow() / deleteRow() — Manage entity fields
  • handleObjectClick() — Select/focus entities
  • handleNavigation() — Keyboard navigation within the grid

Backend Architecture

Follows Clean Architecture principles (see AGENTS.md):

domain/ → use_cases/ → infrastructure/
  • domain/entities.py — Business entities and DAOs
  • use_cases/ — Business logic, DTOs, and ports
  • infrastructure/ — Adapters, routes, clients, and external contracts

Usage

Quick Start

  1. Launch the ORM builder:
dev ui path,to,devOS

  1. Design your entities:

    • Drag nodes onto the canvas
    • Define fields with types and relationships
    • Add constraints and validation rules

  2. Export specification:

Use the drawORM save/export action in the UI. It writes to specs/dao_spec.json.

  1. Generate code:
dev build project_name
  1. Implement use cases:

Write your business logic in use_cases/use_cases.py using the generated DTOs and DAOs.

  1. Run tests:
pytest tests/

Working with Ralph Locally

  1. Pull prompt and instruction updates:
dev-sync read_agents
dev-sync read_ralph
  1. Run your local Ralph workflow:
  • Execute ralph.sh with your preferred local runtime setup
  • Keep generated or updated instructions aligned with project conventions
  1. Push local prompt edits back to snippets:
dev-sync write_agents
dev-sync write_ralph

Managing Snippets

  1. List available snippets:
dev get snippet from python
  1. Pull snippet into project:
dev get snippet from python,sqlalchemy_adapter.py to path,to,local,sqlalchemy_adapter.py

To preview a snippet in the terminal instead of copying it:

dev get snippet from python,sqlalchemy_adapter.py
  1. Update snippet from project:
dev set snippet from path,to,local,adapters.py to python,database-adapters,adapters.py
  1. Create custom snippet:
dev delete snippet python,database-adapters,adapters.py
  1. Use the local sync alias for prompts docs/scripts:
dev-sync read_agents
dev-sync write_agents

Configuration

Edit specs/project_config.json to customize:

{
  "project_name": "my-project",
  "home_root": {
    "snippets": ["protocol", "devOS", "snippets"]
  },
  "project_root": {
    "dao_output_config": [
      { "directory": ["src", "my_app", "domain", "dao.py"], "language": "python" }
    ],
    "dto_output_config": [
      { "directory": ["src", "my_app", "use_cases", "dto.py"], "language": "python" }
    ],
    "api_output_config": [
      {
        "directory": ["src", "my_app", "infrastructure", "routes.py"],
        "language": "python"
      }
    ],
    "test_api_output_config": [
      { "directory": ["tests", "test_routes.py"], "language": "python" }
    ],
    "test_services_output_directory": ["tests"],
    "contract_sync_output_config": [
      {
        "source_language": "python",
        "output_directory": ["src", "typescript_code", "schema"]
      },
      {
        "source_language": "typescript",
        "output_directory": ["src", "python_code", "schema"]
      }
    ]
  }
}

Any class inside files containing @contract is translated to the opposite language using the same filename stem. Example: types.ts -> types.py in the configured destination.

Why devOS?

The Problem

With LLMs, we can generate high-quality code faster than ever. But we still:

  • Write throwaway prototypes that never get refactored
  • Lack tests and documentation
  • Rebuild the same patterns across projects
  • Struggle to maintain consistency in large teams

The Solution

devOS bridges the gap between prototype and production:

  1. Visual design tools eliminate manual boilerplate
  2. JSON specifications ensure portability and type safety
  3. Ralph-first local workflows keep automation under your control
  4. Version-controlled snippets standardize patterns across projects
  5. LLM integration handles unsupported languages and edge cases

When to Use devOS

✅ Use devOS when:

  • Starting a new project that needs Clean Architecture
  • Refactoring a prototype into production code
  • Standardizing patterns across multiple projects
  • Working on proprietary code that can't use cloud AI services
  • You want generated tests, docs, and scaffolding automatically

❌ Don't use devOS when:

  • Building a quick throwaway script
  • Project structure is too unique for code generation
  • Team prefers full manual control over every file

Contributing

devOS is designed to be forked and customized. To contribute:

  1. Fork the repository
  2. Update snippets, templates, or generators
  3. Submit a PR with your improvements
  4. Or keep your fork private and sync upstream changes periodically

License

MIT License — See LICENSE for details.

Roadmap

  • Support for more programming languages (Go, Rust, Java)
  • GraphQL schema generation
  • Integration with more task management tools (Jira, Linear, etc.)
  • Real-time collaboration on drawORM canvas
  • Export to OpenAPI/Swagger specifications
  • Plugin system for custom code generators

Built with ❤️ by developers who are tired of rewriting the same code.

About

boiler plate code generator (DTO, DAO, CRUD Routes etc..) for clean architecture from JSON spec

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages