Apache Maka Examples: How to Use the Agent Workspace (Desktop, TUI, and CLI)

Apache Maka provides three primary interfaces—Desktop (Electron), TUI, and CLI—that share a common Runtime Host to execute agent tasks while recording every action as an immutable RuntimeEvent.

Apache Maka (Incubating) is a high-performance agent workspace designed to orchestrate sessions, agents, models, and tool calls. Whether you prefer a graphical interface, a terminal-based experience, or fully automated scripting, the project offers concrete entry points for every workflow. Below are practical Apache Maka examples derived directly from the source code to get you started with development, execution, and debugging.

Getting Started

To begin using Apache Maka, clone the repository and install dependencies:

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

This prepares the monorepo environment, including TypeScript workspaces and Rust native addons.

Desktop (Electron) Examples

The Desktop UI provides an interactive graphical client for visual task management and real-time agent monitoring.

Hot-Reloaded Development Build

Start the Electron interface with immediate code updates:

npm run dev

This command launches the desktop application with hot-module reloading enabled, allowing you to modify source files and see changes instantly.

Full Production Build

Compile every workspace before launching the desktop:

npm run dev:full

Use this when you need to verify that production assets build correctly before running the UI.

Peer-Enabled Native Addon

For builds incorporating the Rust peer-mesh networking addon:

npm run dev:peer

# Or for a full build with peer support:

npm run dev:full:peer

These commands compile the native Rust components prior to starting the Electron shell.

First-Run Configuration Workflow

When launching the Desktop for the first time, configure your model connection through the interface:

1. Open Settings → Models.
2. Add an API key, local model, or supported account connection.
3. Test the connection and set it as the default.
4. Return to the workspace and start a task.

Configuration persists in the Electron userData directory (e.g., runtime.sqlite, connection-catalog.json, credential-vault.json, settings.json).

CLI Examples (Non-Interactive)

The CLI enables scripting and automation without UI interaction, executing single agent turns via command-line flags.

Execute a Single Turn

Run a one-off task that completes and exits:

npm run cli:dev -- run "Summarize this repository and identify its most important risk"

This invokes the runtime directly through packages/cli, processes the natural language prompt, and returns the result to stdout.

Graph-Enabled Execution

Visualize the execution graph during a multi-step task:

npm run cli:dev -- --graph "Implement two independent slices, integrate them, then review the result"

The --graph flag renders the task topology, showing how AgentRun instances in packages/runtime/src/AgentRun.ts relate to each other within the session managed by the Runtime Host.

TUI (Terminal UI) Examples

The TUI offers a curses-style interface for keyboard-driven interaction.

Launch the Interactive Terminal

npm run cli:dev

Without additional arguments, this opens the text-based UI where you can type commands interactively.

Visualize with the Graph Command

Inside the TUI, use the slash command to view execution flows:

/graph

This triggers the same graph visualization engine available in CLI mode but presents it within the terminal canvas.

Building and Testing

Compile All Workspaces

Build TypeScript, Rust, and other assets across the entire project:

npm run build

This generates the distribution files required for production deployment of any interface.

Run Package-Specific Tests

Execute compiled test suites for individual components:

npm --workspace @maka/runtime run test:dist

This targets the specific workspace in packages/runtime, validating that the runtime logic functions correctly after compilation.

Core Architecture and Key Files

Understanding these source locations helps when extending the Apache Maka examples above:

• packages/runtime-host/src/RuntimeHost.ts – The core host implementation that boots the runtime and orchestrates model/tool interactions.
• packages/runtime/src/AgentRun.ts – Implements a single agent execution turn, handling message loops and tool invocations.
• packages/cli/README.md – Detailed documentation for CLI flags and scripting patterns.
• packages/desktop/README.md – Desktop-specific build instructions and Electron configuration details.
• ARCHITECTURE.md – System map describing how Runtime Host → SessionManager → AgentRun components interact.
• README.md – Overview and quick-start commands for the entire project.

All three interfaces log every model message, tool invocation, and permission decision as RuntimeEvent instances, creating an immutable audit trail of agent activity.

Summary

• Apache Maka offers three entry points: Desktop (Electron GUI), CLI (scriptable), and TUI (interactive terminal).
• Use npm run dev for desktop development with hot-reloading, or npm run cli:dev for terminal-based interaction.
• Execute automated tasks via npm run cli:dev -- run "your prompt" for non-interactive agent turns.
• First-time Desktop users must configure model connections in Settings before executing tasks.
• All actions are recorded as RuntimeEvents by the shared Runtime Host, with source code centralized in packages/runtime-host/ and packages/runtime/.

Frequently Asked Questions

How do I run Apache Maka without installing it globally?

Clone the repository, run npm ci to install dependencies, then use npm run dev for the Desktop or npm run cli:dev for the terminal interface. All commands execute from the project root using the local source code.

Where does Apache Maka store configuration and logs?

The Desktop application stores configuration files—including runtime.sqlite, connection-catalog.json, and credential-vault.json—in the Electron userData directory specific to your operating system. The Runtime Host maintains an immutable event log within the SQLite database.

Can I use Apache Maka entirely from the command line without a GUI?

Yes. The CLI interface supports fully non-interactive execution via npm run cli:dev -- run "your task". This mode utilizes the same RuntimeHost and AgentRun classes as the Desktop but outputs results directly to the terminal without spawning Electron windows.

What is the difference between dev and dev:full commands?

npm run dev starts the Desktop quickly with hot-module reloading, suitable for active development. npm run dev:full compiles all workspaces—including Rust native addons—before launching, ensuring production-equivalent assets are used during the session.

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