What Is the Primary Purpose of the Macro Repository? A Unified Workspace Explained

The Macro repository implements a single, unified workspace that brings together email, messaging, documents, tasks, agents, and a built-in CRM into one fast, searchable interface backed by a bidirectional knowledge graph.

According to the macro-inc/macro source code, this open-source platform eliminates tool-switching by storing every collaboration artifact—emails, messages, docs, tasks, contacts—in a shared backend where all entities are @linked and cross-referenced. The result is what the project calls an "operating system for work," designed to give teams instant context and AI-driven agents complete visibility into their workflows.

The Core Concept: An All-in-One Workspace

Traditional work software fragments information across separate inboxes, chat apps, file drives, and task trackers. Macro attacks this problem directly by unifying these "blocks" into a single interface.

As documented in README.md (lines 28-33):

"Macro is the all-in-one workspace… It unifies email + messages + docs + tasks + agents + CRM into a single fast interface…"

This isn't a superficial integration. Each block—Email, Messages, Docs, Tasks, Agents, CRM, plus calls, files, and PRs—operates as a self-contained module while participating in a shared data layer. The architecture allows any piece of information to reference any other through @ mentions, creating a web of context that follows users across their work.

The Bidirectional Graph: How Everything Connects

The repository's most distinctive feature is its bidirectional linking system. Every entity stores references to every other entity it touches, forming a graph database of relationships.

From README.md (lines 46-48):

"Everything in your workspace is @linked and searchable so your team… never have to switch tools."

Practically, this means:

• An email can @link to a task, a document, and a contact
• A task can surface all related messages and files automatically
• Search across the entire workspace returns connected results with full context

The graph structure is implemented at the data layer, enabling team-level memory—a nightly-updated record of all activity stored in markdown format that agents can query to understand what a team is working on and what they care about (README.md, lines 54-60).

Hexagonal Architecture: Maintainability at Scale

Supporting this unified experience requires clean separation between the core domain and infrastructure concerns. Macro adopts a hexagonal (ports-and-adapters) architecture, documented in CLAUDE.md (lines 5-9):

"Services follow a hexagonal layout: inbound adapters, a domain core with ports, outbound adapters."

This structure provides several advantages:

1. Inbound adapters handle HTTP requests, WebSocket connections, and Kafka event streams
2. Domain core contains pure business logic with no external dependencies
3. Outbound adapters integrate with PostgreSQL, S3, OpenSearch, and DynamoDB

Each "block" can be developed, tested, and deployed independently while still participating in the shared knowledge graph. The modularity is explicit: "Macro is composed of 'blocks' designed to be modular, extensible, and work together like Lego" (README.md, lines 44-50).

Running the Platform Locally

The repository includes comprehensive tooling for local development. The recommended entry point uses just commands, as shown in README.md (lines 102-104):

# From the repository root

just get_environment          # Load .env files for local services

just setup_test_envs          # Prepare DB credentials

just initialize_dbs           # Create all databases

just run                      # Build & start every service + web client

This single command boots the full stack: Postgres, Redis, OpenSearch, Rust services, and the SolidJS front-end. Detailed instructions are available in docs/RUNNING_LOCALLY.md.

Working with Core Services: Code Examples

Creating Tasks Programmatically

The tasks-service demonstrates the clean domain boundaries. From services/task_service/src/service.rs:

use macro_services::task_service::TaskService;
use macro_models::task::TaskCreate;

#[tokio::main]
async fn main() -> Result<(), macro_error::Error> {
    let svc = TaskService::new().await?;
    let new_task = TaskCreate {
        title: "Update onboarding docs".into(),
        assignee_id: Some(42),
        due_date: None,
        ..Default::default()
    };
    let task = svc.create(new_task).await?;
    println!("Created task id={}", task.id);
    Ok(())
}

Querying via GraphQL

Macro exposes a public GraphQL endpoint for client interactions. The resolver implementation lives in apps/web/src/graphql/resolvers.rs:

curl -X POST http://localhost:3000/graphql \
     -H "Content-Type: application/json" \
     -d '{"query":"{ tasks { id title status } }"}'

Interfacing with AI Agents via MCP

The Macro Control Protocol (MCP) enables external AI systems to interact with the workspace. From README.md (lines 70-73):

claude mcp add --transport http macro https://mcp-server.macro.com/mcp
claude mcp call macro "Summarize the latest thread in #engineering"

Agents registered through MCP gain access to the complete knowledge graph, allowing them to act on context that spans every block in the system.

Key Implementation Files

Understanding the Macro repository's purpose requires examining these critical paths:

File	Role
README.md	Product overview, feature list, local development instructions
CLAUDE.md	Architectural deep-dive: hexagonal design, database layout, service boundaries
Cargo.toml (workspace root)	Declares ~167 crates and shared dependencies
services/search_processing_service/src/lib.rs	Document parsing, text extraction, OpenSearch indexing pipeline
apps/web/tauri/src-tauri/src/tauri_protocol.rs	Tauri desktop bridge between web UI and native Rust APIs
crates/worker-rs-otel/src/layer/mod.rs	OpenTelemetry tracing layer used across all services

Summary

• Macro unifies email, messaging, documents, tasks, agents, and CRM into a single searchable interface, eliminating tool fragmentation
• Bidirectional @linking creates a knowledge graph where every entity references every other entity it touches
• Hexagonal architecture enables independent development and deployment of modular blocks while maintaining shared context
• Team-level memory persists nightly snapshots of all activity, giving AI agents complete workflow visibility
• MCP protocol allows external AI systems to query and act on the unified workspace

Frequently Asked Questions

What programming languages does Macro use?

Macro is primarily implemented in Rust for backend services and TypeScript/SolidJS for the web client. The repository contains a Cargo workspace with approximately 167 crates. Native desktop functionality is provided through a Tauri shell, also written in Rust (apps/web/tauri/src-tauri/src/tauri_protocol.rs).

How does Macro's search work across different content types?

Search is handled by services/search_processing_service, which parses documents, extracts text content, and indexes into OpenSearch. Because all blocks store content in a common format with @link metadata, search queries return unified results regardless of whether matches appear in emails, messages, documents, or tasks.

Can I use only specific blocks without adopting the entire platform?

The hexagonal architecture supports selective adoption. Each block is designed as an independent module with its own inbound and outbound adapters. However, the platform's value proposition depends on the bidirectional graph—using blocks in isolation sacrifices the @linking and cross-reference capabilities that distinguish Macro from standalone tools.

What is the Macro Control Protocol (MCP)?

MCP is a protocol interface that allows external AI agents to authenticate against and query the Macro workspace. Agents registered via MCP can access the complete knowledge graph, execute operations across blocks, and leverage team-level memory. The CLI wrapper integrates with systems like Claude for natural language interactions with the workspace.

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