Fork me on GitHub

Machai Project

Machai is a multi-module toolkit for GenAI-enabled developer automation. It provides Java libraries, a command-line application, and Maven integration for provider-neutral GenAI access, Bindex-based library discovery, and guidance-driven repository automation across source code, documentation, project site content, configuration, diagrams, and other governed project files.

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 automation across code, documentation, project site content, configuration, and other repository assets.
  • Maven-native execution for guided and act-based workflows in single-module and multi-module builds.

Modules

Name Description
Project Layout Utility library for describing and resolving conventional project directory layouts such as source roots, test folders, resources, and documentation areas. It helps build tools, scanners, generators, and plugins work with consistent path conventions across Maven, Gradle, JavaScript, Python, and fallback project structures.
GenAI Client Java library that provides a provider-neutral API for working with Generative AI services. It standardizes prompt execution, tool calling, file-aware requests, web search integration, MCP server definitions, embeddings, and usage tracking across supported providers such as OpenAI, Anthropic Claude, and EPAM CodeMie.
Bindex Core Core runtime for Bindex metadata workflows. It manages structured library descriptors, semantic recommendation, metadata registration, repository access, and AI-callable tools that support library discovery, project assembly, and metadata-backed automation.
Ghostwriter Repository-wide AI automation and documentation engine that scans project content for embedded @guidance directives and applies guided updates across source code, documentation, project site content, configuration, diagrams, and other relevant files. It also supports reusable act-based workflows with controlled tool access.
GW Maven Plugin Primary Maven adapter for Ghostwriter. It integrates guided and act-based automation into Maven execution, supports execution-root and per-module workflows, reads optional credentials from Maven settings, and makes repository-scale maintenance easier to run locally and in CI/CD pipelines.

Project structure

The diagram summarizes how the main modules are organized across the Machai platform.

At a high level:

  • Project Layout provides reusable project-structure modeling and path-resolution utilities.
  • GenAI Client supplies the shared abstraction for interacting with supported GenAI providers.
  • Bindex Core builds on GenAI capabilities to support metadata registration, recommendation, and library selection workflows.
  • Ghostwriter uses project-layout and GenAI services to perform guidance-driven repository automation and reusable act execution.
  • GW Maven Plugin integrates Ghostwriter workflows into standard Maven execution for single-module and multi-module projects.

Installation

Prerequisites

  • Git
  • Java 8 or later, with Java 17 recommended for the broader build and site-generation toolchain
  • 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.15-SNAPSHOT:gw -Dgw.scanDir=src\site

Act mode:

mvn org.machanism.machai:gw-maven-plugin:1.1.15-SNAPSHOT: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 repository-wide guidance-driven automation.

Contributing

  • Follow the existing repository structure, naming conventions, and code style.
  • 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