How to Run the Apache Maka TUI or a One-Shot Turn from Source

Clone the Apache Maka repository, run npm install and npm run build to compile packages/cli/dist/cli.js, then execute the binary without arguments to launch the interactive terminal UI or append run "your prompt" for a single non-interactive turn.

When working with the Apache Maka project, developers often need to test changes by running the terminal UI (TUI) directly from a source checkout rather than using a published package. This guide explains how to build the CLI from source and launch both interactive sessions and automated one-shot turns using the repository's TypeScript build pipeline and the runMakaPiTui entry point.

Prerequisites and Repository Setup

Before building, ensure you have Node.js and npm installed. The Maka repository uses npm workspaces to manage the @maka/* sub-packages.

Clone the repository and install dependencies:

git clone https://github.com/apache/maka.git
cd maka
npm install

The root package.json defines the workspace layout, pulling in all sub-packages including the CLI, Runtime Host, and shared libraries into the local node_modules.

Building the CLI from Source

The CLI package requires TypeScript compilation before execution. The build process compiles packages/cli/src/ into the executable packages/cli/dist/cli.js.

Run the build command:

npm run build

Alternatively, for a more granular approach that builds workspace dependencies first:

npm run build:workspace-deps
npm run build

According to the source code in packages/cli/package.json, the build script executes tsc -p tsconfig.json, generating the JavaScript bundle. This dist/cli.js file serves as the bin entry point for both interactive and non-interactive modes.

Launching the Interactive TUI

To start the interactive terminal UI, execute the compiled binary without arguments:

node packages/cli/dist/cli.js

This command invokes runMakaPiTui, defined in packages/cli/src/pi-tui-runner.ts (lines 49-51). The function signature accepts a MakaPiTuiInput object and creates a TuiMainScreen renderer, wiring it to a MakaSessionDriver that communicates with the local Runtime Host to process conversation turns.

Exiting the TUI

Terminate the session by pressing Ctrl-C or typing the !exit command. The source code handles cleanup through handleSigint and handleSigterm functions located in packages/cli/src/pi-tui-runner.ts (lines 86-92), ensuring proper resource disposal and graceful shutdown when the process exits.

Executing a One-Shot Turn

For automated workflows or single queries without launching the full interface, use the run sub-command followed by your prompt string:

node packages/cli/dist/cli.js run "Summarize the project architecture and list risks"

How the Run Command Works

The CLI argument parsing logic resides in packages/cli/src/cli-command-parser.ts. When the parser detects the run sub-command, it constructs a MakaPiTuiInput object (defined in packages/cli/src/pi-tui-contracts.ts) with resumeSessionId set to undefined and passes it to runMakaPiTui.

Unlike the interactive mode, this configuration skips the TuiMainScreen initialization. The driver submits the message via input.driver.submitMessage (as implemented around lines 1264-1272), prints the resulting output to stdout, and terminates the process immediately without rendering the terminal interface.

Using npx for Local Execution

If you prefer not to invoke Node directly with paths, you can use npx with the local package:

npx --yes --package file:packages/cli muka run "Explain the architecture"

This approach references the freshly built package without requiring a global installation or manual path specification.

Summary

• Source checkout: Clone from GitHub and run npm install to populate workspace dependencies defined in the root package.json.
• Build process: Execute npm run build to generate packages/cli/dist/cli.js via the TypeScript compiler (tsc -p tsconfig.json).
• Interactive TUI: Run node packages/cli/dist/cli.js to launch the terminal interface managed by runMakaPiTui in pi-tui-runner.ts.
• One-shot execution: Append run "prompt" to execute a single turn without UI initialization, using the same MakaSessionDriver infrastructure but with immediate termination after the response.
• Process cleanup: Use Ctrl-C or !exit to trigger the signal handlers in pi-tui-runner.ts for graceful shutdown.

Frequently Asked Questions

What is the difference between the TUI and a one-shot turn?

The TUI (Terminal User Interface) launches an interactive TuiMainScreen session where you can conduct multiple turns with real-time visual feedback. A one-shot turn uses the same MakaSessionDriver and Runtime Host infrastructure but submits a single prompt via input.driver.submitMessage and exits immediately without rendering the interface or waiting for further user input.

Where is the CLI entry point defined in the source code?

The executable entry point is declared in packages/cli/package.json under the bin field, pointing to dist/cli.js. The main orchestration logic for booting the TUI lives in packages/cli/src/pi-tui-runner.ts, specifically the runMakaPiTui function exported at lines 49-51, which initializes the session driver and UI components.

How do I exit the Maka TUI cleanly?

Press Ctrl-C or type !exit to trigger the cleanup handlers. The handleSigint and handleSigterm functions in packages/cli/src/pi-tui-runner.ts (lines 86-92) manage process termination and ensure the Runtime Host connections are properly closed.

Can I run the CLI without building the project first?

No. The source is written in TypeScript and must be compiled to JavaScript before Node.js can execute it. The build step, executed via npm run build using tsc -p tsconfig.json as configured in the CLI package, generates the required dist/cli.js file that serves as the runtime entry point.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}