---

GORAK — the Greater OpenROAD Application Kit.

Work with OpenROAD source using readable files, Git, VS Code, command-line tests, and AI coding agents.

Early alpha. gorak is still evolving. Use a disposable development source database and keep backups; do not point it at production source yet.

Demo

The demo shows the normal gorak development loop end to end:

• export an OpenROAD application into readable .w4gl / .wml source;
• edit and synchronize changes with OpenROAD;
• run OpenROAD tests from the command line;
• use an AI coding agent to make a real feature change; and
• review the resulting source and Git diff.

The disposable OpenROAD application used in the video

Follow the project or subscribe for email updates

Setup

We recommend uv for the best development experience.

Clone the repo and install the development environment:

git clone https://github.com/dougwhite/gorak.git
cd gorak
uv sync

Run the test suite:

uv run pytest

Install the tool in editable mode:

uv tool install --editable .

Quickstart

Check the CLI:

gorak --help

Create a local gorak project:

gorak new myproject
cd myproject

This creates a small example project including connection settings, agent instructions, project metadata and a starter application.

Configure your local OpenROAD / Ingres development environment:

gorak config --backend local --vnode myvnode --database sourcedb

Replace myvnode and sourcedb with your vnode and source database. This writes the ignored .env file; .env.example remains a reference for manual configuration.

See the Configuration Guide for local, remote/SSH and ODBC setup.

List the applications available in the configured OpenROAD source database:

gorak app list

To extract an existing application from Workbench into the on-disk gorak project:

gorak app export myapplication

To publish a new application from your gorak project back into Workbench, use gorak app import myapplication or gorak push myapplication.

After editing source on disk, use:

gorak push myapplication         # pushes changes back into Workbench
gorak test                       # run configured OpenROAD tests
git diff                         # review the result

gorak test runs database source.

Use gorak status to see pending pushes, pulls, and conflicts. Use gorak sync to transfer changes in both directions.

See conflict resolution when both sides changed.

New projects include an AGENTS.md describing this workflow for coding agents such as Codex, so an agent can pull source, make a change, synchronize it, run the tests, and prepare a Git change using the same commands as a human developer.

Full Documentation

• Getting Started - Create, export and synchronize your first project
• Command Reference - Normal CLI commands and options
• Configuration Guide - Local, remote and ODBC configuration
• Run and Test - Execute applications and collect test results
• Files and Formats - Project files and source representation
• Remote Helpers - Windows/OpenROAD execution over SSH
• Push and Pull - Transfer scope and conflict resolution
• Development Guide - Contributing to gorak

Actian OpenROAD Extension

In the demo I am using an early-access version of the Actian OpenROAD VS Code extension.

It provides OpenROAD 4GL editing in VS Code and can leverage GitHub Copilot for AI-assisted development.

During the demo it is used as my primary OpenROAD editor. It works amazingly well for normal OpenROAD Workbench workflows, and has greatly improved my OpenROAD productivity. It also works quite well with gorak's native source file formats.

The Actian team has requested that any queries about the OpenROAD VS Code extension should be directed to them.

Project Goals

gorak aims to make OpenROAD projects work more like modern source-code projects.

The goal is to let developers keep using OpenROAD and Workbench where they make sense, while making application source accessible to normal developer tooling: editors, Git, automated tests, code review and AI coding agents.

gorak is focused on:

• A useful CLI for day-to-day OpenROAD development.
• Human-readable, text-based OpenROAD source and metadata.
• Git source control for OpenROAD applications.
• Incremental transfers with conflict checks between files and OpenROAD.
• Command-line build/test workflows that can be used by humans and coding agents.