What Is Graph Mode for Subagents in Maka?

Graph mode is a one-turn scheduling mechanism that lets a main Agent orchestrate child Sessions as a directed acyclic graph without spawning a second runtime.

Graph mode for subagents in Maka transforms a single conversation into a durable, structured workflow by reusing the existing Session infrastructure. Unlike traditional multi-agent systems that launch independent runtime loops, the Apache Maka implementation adds a lightweight graph control plane to coordinate sub-agents as a directed acyclic graph (DAG). This approach maintains the immutable event log and permissions model of the root Session while enabling dynamic, supervisor-managed task scheduling.

Core Concepts of Graph Mode

Graph mode introduces several architectural primitives that distinguish it from standard turn-based execution. These concepts work together to create a persistent schedule namespace derived from the root Session.

Root Session and Graph Topology

The Root Session serves as the user-facing conversation where the main Agent supervises the entire graph. Rather than creating a separate Agent runtime, Maka derives a durable Graph schedule namespace from this root Session, storing topology and revisions in SQLite. According to the Maka architecture, "Graph is a schedule, not a second runtime"—meaning all execution still flows through the normal Session and AgentRun machinery while the graph merely coordinates the work.

Operators and Child Sessions

An Operator represents a stable binding between a graph node and an actual child Session that executes the work. When the supervisor provisions a new operator, Maka creates a record in agent_graph_operator_provisions that links a graphId and workId to a specific childSessionId. This provisioning happens in packages/storage/src/sqlite-session-metadata-store.ts, where the storage layer ensures each operator maintains the parent Session's snapshot, permissions, and context across activations.

Intents and Work Scheduling

Work or Intent represents a single instruction that the supervisor adds to the schedule. When the main Agent claims an intent, Maka writes to agent_graph_intent_claims with the specific tool calls or sub-agent instructions. This durable record allows the graph to track what should happen, while the Activation (an AgentRun) records what actually happened. The RuntimeEvent then serves as the canonical immutable record, with Graph Records projecting these events as node-to-node edges in the DAG.

How Graph Mode Works

The implementation relies on a SQLite-based control plane that maintains state between turns while ensuring the supervisor can modify the schedule asynchronously.

The SQLite Control Plane

All graph state lives in dedicated SQLite tables managed by packages/storage/src/sqlite-session-metadata-store.ts. The storage layer handles:

• agent_graph_* tables for topology and schedule revisions
• agent_graph_intent_claims for pending work
• agent_graph_supervisor_wakes for checkpoint notifications

This design ensures the graph schedule survives process restarts and allows the supervisor to watch the graph without blocking on record delivery.

Supervisor Wakes and Activation

When a checkpoint becomes ready or new work enters the queue, the storage layer creates a supervisor wake:

await storage.createSupervisorWake({
  graphId,
  wakeId,
  // optional: start turn id, run id, etc.
});

This inserts a row into agent_graph_supervisor_wakes, signaling the main Agent to start a new root turn. The supervisor can then examine the graph state, claim new intents, or provision additional operators before the next activation cycle begins.

Enabling and Using Graph Mode

Maka exposes Graph mode through both the desktop UI and chat commands, making it accessible for both interactive and programmatic use.

UI Toggle

In the desktop application, users enable Graph mode through the interface defined in apps/desktop/src/renderer/app-shell.tsx. The UI labels reside in packages/ui/src/conversation-copy.ts:

// UI strings defined in conversation-copy.ts
copy.graphModeLabel      // → "Graph"
copy.graphModeOnTitle    // → "Graph mode is on — click to turn off"

Clicking the toggle switches the Session between standard conversational mode and graph scheduling mode.

Chat Commands

Users can also control Graph mode directly from the chat input. The command parser in packages/core/src/orchestration.ts routes these to packages/core/src/graph-command.ts:

/graph on          // turn Graph mode on for the current Session
/graph off         // turn it off
/graph <task>      // run a single-turn graph task (e.g., "/graph summarize notes")

When executing a task command, the system builds a one-turn intent claim and schedules it immediately, allowing the supervisor to orchestrate sub-agents without leaving the conversation context.

Implementation Details

Developers extending Maka's Graph mode interact with the storage layer to provision operators and claim work.

Provisioning Operators

To bind a child Session to a graph node, use the storage API:

await storage.provisionOperator({
  graphId: graphId,
  workId: workId,
  operatorId: operatorId,
  childSessionId: childSessionId,
});

This executes an INSERT INTO agent_graph_operator_provisions statement in packages/storage/src/sqlite-session-metadata-store.ts, creating the durable link between the graph topology and the actual execution context.

Claiming Intents

Adding work to the graph requires claiming an intent:

await storage.claimIntent({
  graphId,
  intentId,
  workId,
  operatorId,
  // the intent contains the tool calls / sub-agent instructions
});

This writes to agent_graph_intent_claims and atomically updates the schedule revision, ensuring the supervisor sees the new work during its next wake cycle.

Summary

• Graph mode treats sub-agents as a directed acyclic graph coordinated by a main Agent, not as independent runtimes.
• The SQLite control plane in sqlite-session-metadata-store.ts maintains durable schedule state across turns.
• Operators provision child Sessions that inherit the root Session's context and permissions.
• Supervisor wakes trigger new root turns when the graph reaches checkpoints or receives new work.
• Users enable Graph mode via the desktop UI (app-shell.tsx) or chat commands (graph-command.ts).

Frequently Asked Questions

What is the difference between Graph mode and a regular Agent runtime?

Graph mode does not create a second, independent Agent loop. Instead, it adds a scheduling layer on top of the existing Session/Runtime infrastructure. All sub-agent work executes through normal Session inline activations (AgentRuns), while the graph control plane stored in SQLite merely coordinates which work runs when and tracks dependencies between nodes.

How does Graph mode store workflow state?

Graph mode persists topology, schedule revisions, intent claims, and supervisor wakes in dedicated SQLite tables (agent_graph_*). The sqlite-session-metadata-store.ts implementation handles atomic writes to tables like agent_graph_intent_claims and agent_graph_operator_provisions, ensuring the workflow graph survives process restarts and maintains consistency across concurrent modifications.

Can sub-agents spawn additional sub-agents in Graph mode?

Yes. Child Sessions provisioned as operators can themselves act as supervisors for nested graphs. Because each activation automatically inherits the parent Session's snapshot and permissions, dynamically expanding the graph depth does not require special configuration. The storage layer treats each provisioning call independently, allowing arbitrarily deep DAG structures as long as they remain acyclic.

How do I enable Graph mode in a Maka session?

You can enable Graph mode either by clicking the "Graph" toggle in the desktop UI (defined in conversation-copy.ts and rendered in app-shell.tsx) or by typing /graph on in the chat input. The command parser in orchestration.ts processes these directives, while single-turn tasks like /graph summarize notes immediately schedule work without permanently switching the Session mode.

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