Fork me on GitHub

Machai Project

Machai is a multi-module toolkit for GenAI-enabled developer automation. It provides Java libraries and Maven tooling that unify access to multiple GenAI providers, generate and consume Bindex metadata for library discovery and reuse, and automate repository-scale documentation and file updates from embedded guidance using Ghostwriter.

Key capabilities include:

  • Provider-agnostic GenAI access through a shared Java client.
  • Bindex metadata generation, registration, semantic picking, and dependency-aware context assembly.
  • Guidance-driven, repository-scale automation across code, documentation, site content, and other project files.
  • Maven-native execution for guided and act-based workflows in multi-module builds.

Modules

Name Description
Project Layout Utility library for describing and working with conventional project directory layouts such as sources, resources, tests, and documentation in a consistent way. It helps tools and plugins resolve well-known folders reliably, avoid hard-coded paths, and reduce duplicated path logic across different project types.
GenAI Client Java library for integrating with Generative AI providers through a shared, provider-agnostic API. It supports prompt composition, optional file attachments, optional tool calling, and embeddings so higher-level automation can interact with AI services without being tightly coupled to provider-specific SDKs.
Bindex Core Core Java library for Bindex metadata workflows. It supports generating and registering Bindex records, classifying natural-language requests into structured metadata filters, performing semantic library selection, expanding dependency context, and exposing these capabilities as tools for AI-assisted automation.
Ghostwriter Guidance-driven documentation and repository automation engine available as both a CLI and a library. It scans project files, extracts embedded @guidance directives, composes model inputs with project context and optional instructions, and applies AI-generated updates back to source code, documentation, site content, and other repository artifacts.
GW Maven Plugin Maven plugin that integrates Ghostwriter into Maven builds. It provides guided and act-based goals, supports both aggregator-style and reactor-ordered execution, accepts configurable scan roots and excludes, can load credentials from Maven settings, and makes repository automation easier to run locally and in CI pipelines.

Project structure

The diagram summarizes the main modules and the way responsibilities are layered across the Machai platform.

At a high level:

  • Project Layout provides reusable project layout modeling utilities.
  • GenAI Client provides the shared abstraction for working with GenAI providers.
  • Bindex Core builds on Project Layout and GenAI Client to support Bindex metadata and semantic library discovery.
  • Ghostwriter uses the shared libraries to perform guidance-driven repository automation.
  • GW Maven Plugin integrates Ghostwriter workflows into standard Maven execution.

Installation

Prerequisites

  • Git
  • Java 17 recommended for building the full project
  • Maven 3.8.1 or later

Clone and build

git clone https://github.com/machanism-org/machai.git
cd machai
mvn -U clean install

To build and stage the Maven site:

mvn clean install site site:stage

Usage

Build a specific module

mvn -pl genai-client clean install

Run Ghostwriter CLI

cd ghostwriter
mvn -Ppack package
java -jar target\gw.jar src\site\markdown

Run Maven plugin goals

Guided processing:

mvn org.machanism.machai:gw-maven-plugin:1.1.0:gw -Dgw.scanDir=src\site

Act mode:

mvn org.machanism.machai:gw-maven-plugin:1.1.0:act -Dgw.act="Rewrite headings for clarity" -Dgw.scanDir=src\site

Use the libraries in Java projects

You can consume individual modules as Maven dependencies for project layout handling, GenAI integration, Bindex workflows, or guidance-driven repository automation.

Contributing

  • Follow the existing code style and repository conventions.
  • Keep changes focused and add or update tests where applicable.
  • Use GitHub Issues for bug reports and feature requests: https://github.com/machanism-org/machai/issues
  • Submit pull requests with a clear summary, rationale, and reproduction details for fixes.
  • Review generated documentation and site changes before opening a pull request.

License

Licensed under the Apache License, Version 2.0. See LICENSE.txt.

Contact and support