Project Structure Overview

The project is organized as a command-line application with a shared processing core. Startup resolves configuration and selects either guidance processing or Act execution. Both modes reuse project and module traversal, filtering, prompt composition, and provider dispatch. Guidance processing delegates instruction extraction to format-aware reviewers; Act processing loads reusable definitions, merges inherited settings, and coordinates ordered episodes. Provider management and tool registration connect the processing core to the configured model and to controlled capabilities for files, commands, web resources, Acts, guidance, and shared context. The project layout library supplies module discovery and project-relative paths. External project content, remote resources, and the GenAI provider remain outside the application boundary, allowing the same processing flow to be used locally or in automation.

The related processing diagrams show the same architecture from complementary perspectives. The guidance flow scans eligible content, extracts an embedded directive with the appropriate reviewer, sends the composed request to the provider, and records a guidance report; files without applicable instructions are skipped unless a default prompt is configured. The Act flow parses and configures a workflow, selects its episodes, traverses project modules and files, and records results while allowing an episode to repeat, move, or stop processing. Together, these views clarify that guidance processing and Act processing are separate entry paths that share traversal, provider, tool, and project-context services.

See the guidance processing flow, guidance overview, Act episode flow, and module and file traversal flow for the detailed diagrams.

Machai Ghostwriter vs. Other Tools

The closest widely known tool to Machai Ghostwriter is Claude Code. Both can work across a project's files, use tools, and assist with multi-file changes rather than only inline code completion. Claude Code is the nearest comparison because it combines an agentic CLI with headless automation, GitHub Actions integration, persistent project instructions, and extensibility through skills, hooks, and MCP tools. Ghostwriter emphasizes repository-embedded guidance, explicit scan scopes, reusable Acts, and Java CLI deployment in build pipelines.

Prerequisites

• Java runtime compatible with the delivery pack and selected provider libraries. The Maven build sets maven.compiler.release to 8, targeting Java 8 bytecode for Ghostwriter itself; bundled dependencies or provider plugins may require a newer runtime.
• A configured, supported Machai GenAI provider and model, including any required credentials, endpoint, and network access.
• Read/write access to the target project; use network access when the provider, remote Acts, or referenced HTTP(S) resources need it.
• Maven 3.x and a compatible JDK to build from source, plus access to the project's dependency repositories. Building the delivery pack additionally requires the pack profile and the MACHANISM_PACK_DIR environment variable.
• Configure provider credentials without committing secrets: the supplied pack documents GENAI_USERNAME/GENAI_PASSWORD for CodeMie, or OPENAI_API_KEY and optional OPENAI_BASE_URL for an OpenAI-compatible service. Requirements vary with the selected provider.
• Any tools requested by a workflow (such as Git, Maven, or test runners) must be installed and accessible to the process, and command execution must satisfy the configured security rules. Use version control to review and revert generated changes.

Basic Usage

Run the executable JAR with a path or pattern to scan:

java -jar gw.jar "glob:**/*.md"

The positional <path> can be a relative path inside the project, a directory name, a glob: pattern such as glob:**/*.java, or a regex: pattern such as regex:^.*/[^/]+\.java$. Multiple positional targets are accepted and scanned in order. Absolute paths must remain inside the configured project directory. If no positional path is provided, Ghostwriter uses gw.path or .. Path matching uses the operating system's Java path matcher, so regular expressions involving separators may need adjustment on Windows.

Typical Workflow

1. Unpack the CLI delivery artifacts and configure the AI provider, model, credentials, and project directory.
2. Add precise @guidance directives to the files that should govern their own processing, or create/select an Act workflow.
3. Start with a narrow file path or pattern and supply exclusions where needed.
4. Run the CLI, review the resulting changes and command logs, and refine the guidance or Act.
5. Reuse the same configuration and scoped command in CI/CD after validating it locally. Supply explicit instruction/Act values, choose non-interactive workflows, provision credentials through the CI secret store, and validate the resulting diff and tests before publishing.

Java Version and Functional Requirements

The project declares Java 8 through maven.compiler.release. This is Ghostwriter's compilation target, not a guarantee that every bundled dependency or provider plugin runs on Java 8; use a runtime compatible with the complete delivery pack. Building requires a JDK supported by the selected Maven plugins. Functional processing also requires an available GenAI provider/model configuration; project writes require suitable file permissions, and remote providers or resources require the relevant credentials and network connectivity.

Command-Line Options

These are all nine CLI options; there are no separate CLI flags for request logging, non-recursive traversal, or interactive settings. A missing default configuration file is tolerated; an explicitly selected file that cannot be loaded fails startup. Because configuration loading precedes applying --projectDir, use an explicit configuration path when the file is in a different project directory.

Example

The following command uses a scoped scan, custom project directory, provider/model, concurrency, exclusions, and instructions:

java -jar gw.jar "glob:**/*.md" --projectDir . --model "OpenAI:gpt-5.1" --threads 4 --excludes "target,.git" --instructions "Keep headings consistent and preserve public links."

To select a different properties file, use --config automation.properties or place the JVM option before the JAR: java -Dgw.config=automation.properties -jar gw.jar src. Keep provider secrets in the environment or a protected configuration source, not in checked-in commands.

For Act mode, run a bundled workflow or an ad-hoc task:

java -jar gw.jar . --act "code-doc"
java -jar gw.jar . --act "> Summarize the project and update its documentation."

Use --acts "acts,shared-acts" --act documentation-update only after creating those directories and the requested custom Act. The built-in help also illustrates directory and relative-path scans, "glob:**/*.java", and "regex:^.*/[^/]+\.java$". In automation, always supply values for --instructions and --act if those flags are used, since omitting their values prompts on standard input.