Headless Mode

Run Makima non-interactively with --print, and pass the prompt with -p / --prompt. Useful for scripts, CI, and automation.

makima --print -p "explain this codebase"

Pipe via stdin:

echo "list all TODO comments" | makima --print

With both -p and piped stdin, the prompt is the -p text, a blank line, then everything read from stdin. Makima reads stdin until it closes, so a run whose stdin stays open waits for it. Inside a while read loop, Makima would also read the rest of the loop's input. Give such runs </dev/null (see the migration example).

Output Formats

Format	Description
text	Raw response only (default)
json	Single JSON object with metadata
stream-json	JSONL stream, one event per line

makima --print -p "fix the tests" --output-format json

JSON output includes type, subtype, is_error, duration_ms, num_turns, result, stop_reason, session_id, total_cost_usd, and usage.

Add --verbose to include full turn-by-turn messages in the output.

Slash commands

A prompt whose first token is an available slash command runs that command before Maki creates model input. Custom Markdown commands, MCP prompts, and Lua commands can produce a normal agent turn. A side-effect-only command succeeds with empty output. A known available command with invalid arguments exits with an error. Unknown and unavailable slash-prefixed text is rejected with an error; prefix a literal message that starts with / with another slash to send it as text (//lmao sends /lmao).

SDK stream mode and ACP project the built-ins supported by their target capabilities. /model accepts an explicit model spec. One-shot print mode supports /exit. Commands that require TUI capabilities are rejected in headless frontends. The // escape also works there, so /help becomes text via //help. Local commands reject image attachments, while agent-turn commands preserve them.

See Commands for matching, collision priority, and the generated command list.

Claude Code Compatibility

Makima's --print output matches Claude Code. One flag differs: in Makima, -p is the prompt, so print mode is always the long --print.

# Before
claude -p "fix the bug" --output-format json

# After
makima --print -p "fix the bug" --output-format json

Same JSON fields, same --output-format options, same --verbose behavior. Scripts that parse Claude Code output work unchanged.

SDK / Stream Mode

For tools like Conductor, Windsurf, or custom orchestrators that speak the Claude Code SDK wire protocol, use --input-format stream-json:

makima --print --input-format stream-json

This enters a bidirectional NDJSON loop over stdio instead of the one-shot print path:

your orchestrator                     makima --print --input-format stream-json
        │                                             │
        │  {"type":"user",...}            (stdin)     │
        ├─────────────────────────────────────────────►
        │                                             │
        ◄─────────────────────────────────────────────┤
        │  system / assistant / stream_event / result │
        │  one JSON object per line       (stdout)    │

Inbound messages (user, control_request, control_response, control_cancel_request) drive the agent; outbound messages match the Claude Code SDK shape. The initialization and control projections list the active slash commands. A system/commands_update event reports registry changes after plugin reloads or MCP updates. Under the hood it reuses the same driver as the TUI and ACP server, so sessions, tools, and permissions all work the same way.

SDK-only flags (--max-turns, --session-id, --fork-session, --permission-mode, --include-partial-messages, ...) are listed in the CLI flag matrix. --system-prompt / --append-system-prompt apply in every run path.

Two caveats:

• One-shot --print always starts a new session in build mode. Plan mode and session resume need the SDK path (or the TUI).
• The plan file for SDK --permission-mode plan is ./plan.md under cwd, not the state-dir plans/<slug>.md files the TUI uses.

Quick example

echo '{"type":"user","message":{"content":"explain this repo"}}' \
  | makima --print --input-format stream-json --max-turns 3

Examples

Pipe compiler errors back for a fix:

cargo build 2>&1 | makima --print -p "Fix these compiler errors." --yolo

Generate a changelog from recent commits:

git log --oneline v1.2.0..HEAD | makima --print -p "Write a user-facing \
  changelog grouped by: Added, Changed, Fixed. Skip chores."

Automated PR summaries in CI:

SUMMARY=$(git diff main..HEAD | makima --print -p "Write a 2-3 sentence \
  summary of this change for a PR description.")
gh pr edit --body "$SUMMARY"

Migrate an API across many files. The </dev/null keeps each run from reading the rest of the file list:

grep -rl 'old_api_call' src/ | while read file; do
  makima --print -p "In $file, migrate old_api_call() to new_api_call(). \
    Keep behavior identical." --yolo --allowed-tools Read,Edit </dev/null
done

Cost tracking:

makima --print -p "refactor the database layer" --output-format json | jq '.total_cost_usd'