# What Is Graph Mode for Subagents in Maka?

> Discover Maka's Graph mode for subagents. Learn how this one-turn scheduling mechanism orchestrates child Sessions as a DAG without a second runtime. Optimize your Agent orchestration.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-09-10

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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:

```typescript
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`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/app-shell.tsx). The UI labels reside in [`packages/ui/src/conversation-copy.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/conversation-copy.ts):

```typescript
// 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`](https://github.com/apache/maka/blob/main/packages/core/src/orchestration.ts) routes these to [`packages/core/src/graph-command.ts`](https://github.com/apache/maka/blob/main/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:

```typescript
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`](https://github.com/apache/maka/blob/main/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:

```typescript
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/app-shell.tsx)) or chat commands ([`graph-command.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/conversation-copy.ts) and rendered in [`app-shell.tsx`](https://github.com/apache/maka/blob/main/app-shell.tsx)) or by typing `/graph on` in the chat input. The command parser in [`orchestration.ts`](https://github.com/apache/maka/blob/main/orchestration.ts) processes these directives, while single-turn tasks like `/graph summarize notes` immediately schedule work without permanently switching the Session mode.