DEV Community: Harshith Vaddiparthy

Forking Macro: A Technical Walkthrough of Agent Collaboration

Harshith Vaddiparthy — Wed, 19 Aug 2026 20:33:54 +0000

Multi-agent demos often hide the most difficult engineering problem.

Disclosure: I used AI tools to assist with research organization and drafting. I reviewed, edited, fact-checked, and source-checked this article before publication.

Spawning workers is not collaboration. A collaborative system must manage context, permissions, handoffs, concurrent state, and verification across humans and agents.

Macro is a workspace that describes its open-source decision publicly and is useful to examine through this lens. Its official repository is published at macro-inc/macro. The root license presents AGPLv3, but a nested web-app license says all rights reserved. That conflict matters and is covered below. The published stack includes Rust and SolidJS. Macro connects documents, email, tasks, calls, channels, CRM, memory, and agents.

I am using Macro and forked the repository. On August 19, 2026, GitHub compare showed the fork's main identical to upstream main, 0 commits ahead and 0 behind, at 02c218308c462046ee54e6f275b8c0a371ee3f5a.

Important scope note: no local clone, modified branch, self-hosted deployment, or benchmark is claimed in this article. The walkthrough maps verified repository and documentation claims to a reproducible evaluation plan. It does not pretend I ran tests for which I have no artifact.

Repository snapshot

At review time, the official repository showed:

Item	Snapshot on 2026-08-19
Stars	3,696
Forks	362
Commits in `main` history	5,066
Open issues	19
Open pull requests	51
Tags	213
Latest visible release	`v2026.8.18.2`
Reviewed commit	`02c218308c462046ee54e6f275b8c0a371ee3f5a`

These are activity signals, not performance results. The latest values will change.

The cover uses Macro's older embedded star-history snapshot, which shows 3,608 stars. The live count at this review checkpoint was 3,696.

Macro said on August 13 that the repository briefly reached number one on GitHub Trending. The company said on August 12 that it had received an influx of users, pull requests, and feature requests. Both are attributed company statements.

Reproduce the source boundary first

If you want to inspect the same fork, begin by recording the exact source state. The commands below verify Git identity only. They do not install or run Macro.

git clone https://github.com/harshith-vaddiparthy/macro.git
cd macro
git remote add upstream https://github.com/macro-inc/macro.git
git fetch upstream main
git remote -v
git status --short
git rev-parse HEAD
git rev-parse upstream/main
git rev-list --left-right --count upstream/main...HEAD
git log -1 --oneline

Before building, compare the full SHA with the current upstream default branch and read the repository's current README. Do not assume dependencies or setup commands from this dated article are still correct.

Resolve the license boundary before reuse

Those terms conflict with a repository-wide assumption that every file is AGPLv3. The affected scope needs clarification from Macro's maintainers. Until then, do not assume every web-app file, screenshot, or asset can be reused under the root license.

This article does not decide which terms control. Before modifying, distributing, hosting, or reusing repository material, inspect the applicable path, request maintainer clarification, and obtain appropriate legal advice.

A technical model of Macro's collaboration surface

The documented system can be understood as six connected layers:

Work surfaces
  email | tasks | documents | calls | channels | CRM
                         |
                         v
Shared memory refreshed nightly from team activity
                         |
              explicit context via @mentions
                         |
                         v
Agents operating under the user's permissions
                         |
       read | draft | write | update | post | automate
                         |
                         v
Shared document state using CRDT collaboration
                         |
                         v
External coding agents through an MCP endpoint

This is an editorial model based on Macro's website, documentation, and README. It is not a literal internal service diagram.

Layer 1: Work surfaces

Macro's Agents documentation says agents can access email, tasks, documents, calls, and channels under the user's permissions. Documented actions include search and read, document writing, task and CRM updates, email drafting, channel posts, call reading, and automation.

The engineering advantage is context locality. The agent does not need a separate integration for every step if the workspace already exposes the relevant object and action.

The risk is authority aggregation. A workspace that unifies several tools can give one agent a broad action surface. The permission model, confirmation boundaries, audit trail, and revocation behavior therefore matter as much as tool coverage.

Layer 2: Shared memory

Macro's Unified Memory documentation says memory refreshes nightly from team activity.

A shared memory layer can reduce repeated context assembly. It can also create subtle failure modes:

stale information remains retrievable;
two sources disagree;
deletion does not propagate as expected;
an agent retrieves a related but non-authoritative artifact;
the user cannot see why a particular item was selected.

Test memory against the latency of the workflow. A nightly refresh may fit a weekly recap. It may not fit an incident response or a decision made minutes ago.

Layer 3: Explicit context

Macro's Agents documentation presents @mentions as a way to pin context for an agent.

This gives the system two retrieval modes:

broad organizational context from shared memory;
task-specific context selected by a human or collaborator.

That distinction is useful because retrieval relevance is not the same as authority. The closest semantic match may not be the document that governs the current decision. Pinning context creates a direct signal about which source matters now.

Layer 4: Handoffs

The official repository includes an agent task-handoff screenshot. A handoff is the state boundary between actors, so evaluate it as structured data rather than a friendly message.

A robust handoff should preserve at least:

goal: "What outcome are we trying to produce?"
source_artifacts:
  - "Which documents, calls, tasks, or messages govern the work?"
completed_work:
  - "What has already changed?"
open_questions:
  - "What remains unresolved?"
next_action: "What should happen next?"
owner: "Which person or agent is responsible now?"
verification: "How can the next actor check the claims?"

This YAML is an evaluation template, not Macro configuration.

Layer 5: Concurrent document state

Macro's Documents documentation says its documents use CRDTs with Cloudflare Durable Objects. The README describes swarms of agents acting as peers in CRDT collaboration.

A conflict-free replicated data type allows concurrent updates to converge without using a simple last-write-wins overwrite. This is relevant when humans and several agents edit a shared document.

CRDTs solve a state problem. They do not solve a meaning problem.

Two changes can merge correctly and contradict each other. One agent can add a decision while another rewrites the assumption behind it. A production workflow still needs editorial ownership, review boundaries, and a way to identify which claims require verification.

Useful CRDT tests include:

two agents insert text at the same location;
a human deletes a section while an agent edits it;
one participant works from a delayed client;
several edits reference the same task or decision;
a reconnect occurs after substantial concurrent work.

Measure both state convergence and semantic coherence.

Layer 6: External agents over MCP

Macro's MCP overview names Claude Code and Codex CLI. Its Agents documentation separately names Cursor. MCP gives an AI client a standard interface to external context and tools.

The valuable pattern is a closed state loop:

shared task -> coding agent -> repository work -> task update -> team recap

An integration is incomplete if it only sends context to the agent. The agent should return a structured status, evidence, and unresolved questions to the workspace where the team coordinates.

Macro's published Agent Recipes include MCP-driven coding-agent task updates, along with daily briefs, project status, weekly recap, call-to-tasks, draft email, and channel summary.

Build a bounded evaluation, not a swarm demo

A weekly project recap is a good first workflow because it is recurring, reviewable, and reversible.

Define the test before connecting broad authority:

Test dimension	Question	Evidence to capture
Context	Did the agent use the governing sources?	Source links and retrieval trace
Freshness	Did it include a recent change?	Source timestamp versus output timestamp
Permission	Could it access only allowed objects?	Account role and denied-access test
Handoff	Did it preserve owners and open questions?	Structured comparison with source tasks
Action boundary	Did it draft or mutate shared state?	Before and after object state
Concurrency	What happened during a conflicting edit?	Revision history and final document
Verification	Can a human reconstruct the output?	Action log, citations, and correction record

Run the workflow in three rounds:

Happy path: clean sources, no conflicts, draft-only output.
Adversarial path: one stale document, one contradictory update, and one inaccessible source.
Concurrent path: a human or second agent changes a related artifact while the workflow is active.

The primary metric should be correction cost. Record how long a person spends finding missing context, checking claims, fixing ownership, and restoring state. Fast generation does not help if review becomes expensive.

Where the architecture is promising

Macro's direction connects several primitives that are often separated:

an inspectable public implementation with a license-scope conflict that needs clarification;
shared organizational context;
explicit context selection;
permission-aware actions;
concurrent collaborative documents;
MCP access for external coding agents;
recipes that return work to a shared system.

The combination is the important part. An agent becomes more useful when it can read current work, make a bounded contribution, and return state that another person or agent can continue.

What remains unproven here

This review does not establish:

production reliability or security;
latency and cost at scale;
the quality of memory retrieval;
behavior under permission changes;
audit-log completeness;
semantic quality under concurrent edits;
successful self-hosting from Harshith's fork;
a modification or benchmark at revision 02c218308c462046ee54e6f275b8c0a371ee3f5a.

Those are test targets, not conclusions to smuggle into a launch post.

Conclusion

The hard part of multi-agent software is not multiplying workers. It is coordinating context, authority, shared state, handoffs, and verification.

Macro is worth studying because its public architecture addresses those concerns directly. Shared memory gives agents organizational context. @mentions narrow attention. Permission-bound actions connect context to work. CRDTs support concurrent collaboration. MCP can return coding-agent state to the team's workspace. Studying public code is different from assuming every path has uniform reuse terms, so the nested-license conflict remains a real diligence item.

None of these features eliminates the need for verification. Together, they provide a concrete public system against which developers can test collaboration claims.

Credit to Jacob Beckerman, whose profile identifies him as Macro's founder and CEO, and the Macro team for publishing the work. This is an independent technical analysis and does not imply endorsement.

For the broader product argument, FAQ, sources, and dated updates, read the canonical guide.

AI Engineer Is Now the Most Common AI Role. The Talent Pipeline Has Not Caught Up.

Harshith Vaddiparthy — Tue, 18 Aug 2026 08:28:19 +0000

LinkedIn's August 2026 research gives software teams a useful view of how AI engineering work is changing.

The reported numbers are substantial:

U.S. AI job postings have roughly doubled since 2023.
The typical AI posting lists about $177,000 in compensation, compared with $80,000 for a non-AI role.
AI Engineer has overtaken Machine Learning Engineer as the most common AI role on LinkedIn.
Forward Deployed Engineer is now the third most common AI builder occupation.
VP of AI postings have grown roughly sixfold.

The talent pipeline is much narrower than the demand. Women represented 26% of U.S. AI hires in 2025, compared with 50% of non-AI hires. About 91% of AI workers hold a bachelor's degree or higher. Across 27 countries, women held only 13% of C-suite AI roles at AI companies.

These are LinkedIn's reported findings. My analysis below is about what engineering leaders and developers should do with them.

1. Define the work, not just the title

LinkedIn notes that "AI Engineer" may partly be replacing older language. Some positions that would once have been called machine learning engineering are now receiving a broader label.

That makes title-based hiring less reliable.

A useful AI Engineer specification should answer concrete questions:

Is this person building model-backed product features or training models?
Will they own data preparation, application code, testing, deployment, or monitoring?
What quality, latency, security, and cost constraints matter?
Which decisions belong to this role, and which belong to platform, product, or data teams?

Two companies can advertise the same title while expecting very different work. Candidates should not have to reverse-engineer the role from a list of libraries.

2. Forward Deployed Engineer growth is a deployment signal

Forward Deployed Engineer becoming the third most common AI occupation is important because the role sits close to implementation.

Companies are not only looking for people who understand models. They need engineers who can enter a real operating environment, clarify requirements, integrate with existing software and data, and help users adopt the result.

For developers, this rewards a broader portfolio. A small but complete project can be stronger evidence than a collection of disconnected demos. Show the problem definition, architecture, implementation, tests, operational constraints, and the decisions you would revisit.

For teams, interview loops should reflect this work. Ask a candidate to turn an ambiguous request into a testable specification. Let them build or critique a bounded service. Evaluate the reasoning, implementation, and communication with the same rubric for every candidate.

3. Do not turn the 91% degree figure into another automatic filter

The report describes the current workforce. It does not prove that every AI builder role requires a bachelor's degree.

LinkedIn also states that its findings are descriptive and correlational. Member histories are self-reported, and compensation analysis covers postings that voluntarily disclose pay.

If a degree is genuinely necessary, explain why. Otherwise, define alternative evidence:

A working software artifact with readable code
Contributions to a relevant project
A paid apprenticeship or internal rotation
Strong adjacent experience in software, data, security, product, or a target industry
A structured work sample scored against published criteria

Removing a degree requirement without creating an evidence standard does not produce skills-first hiring. It produces inconsistent judgment.

4. Measure access through the engineering ladder

The gender gap appears in hiring and becomes larger in AI leadership. That means the relevant system includes sourcing, interviews, project assignment, promotion, and sponsorship.

Engineering leaders should measure who advances at each stage. They should also inspect who receives the high-visibility technical work that produces future staff engineers, architects, directors, and AI leaders.

This is not separate from technical quality. A team that repeatedly searches within the same narrow network is limiting the number of capable people it can discover.

What developers should take from this

AI roles are growing, but the title alone is becoming less informative.

Build evidence around the work you want to do. Demonstrate software fundamentals, the ability to frame a problem, thoughtful use of models, testing, cost and latency awareness, and clear technical communication. If you are moving from an adjacent field, make the transferable foundation visible.

The market signal is not simply "learn AI." It is that companies need people who can turn AI capability into dependable, useful software, while the current routes into that work remain unusually narrow.

Sources

Designing Browser Agents That Don’t Double-Post: State, Idempotency, and Verification

Harshith Vaddiparthy — Mon, 17 Aug 2026 07:04:50 +0000

Browser agents are easy to demo and difficult to operate.

A demo can navigate to a page, fill an editor, and click Publish. A durable agent must answer a longer list of questions:

Is it acting through the correct account?
Has another scheduled run already reserved this action?
Did the click create an external effect?
Can that effect be identified with a canonical URL or exact state?
If the browser timed out, is a retry safe?
Can the next run resume without duplicating the action?

I encountered a small example of this while building a browser-based publishing agent. The agent needed to shorten a draft, but the web editor appended the replacement text instead of replacing the original. A naive implementation could have continued clicking or restarted the publishing flow. The safer implementation read the editor state back, detected that it did not match the intended payload, refused to publish, and recorded a failure.

That is the core principle of this design:

The model chooses an action. The surrounding system makes the action trustworthy.

This article develops a minimal architecture for that surrounding system. The examples use Python-like code and SQLite, but the patterns apply to any stack that operates external interfaces.

Start with an explicit action lifecycle

Do not let an agent move directly from “the model suggested this” to “click the button.” Give every external mutation a lifecycle:

observed
   ↓
planned / reserved
   ↓
executing
   ├──────────────→ verified ──→ budget committed
   ├──────────────→ failed
   └──────────────→ ambiguous

The important state is ambiguous. It means the system attempted a mutation but could not prove whether the external effect occurred.

An ambiguous action is not a failed action. It must be reconciled before any retry.

1. Persist intent before performing the mutation

A durable action record should capture enough information for a future run to understand what was intended and how to verify it.

CREATE TABLE actions (
    id TEXT PRIMARY KEY,
    idempotency_key TEXT NOT NULL UNIQUE,
    run_id TEXT NOT NULL,
    action_type TEXT NOT NULL,
    actor TEXT NOT NULL,
    target_url TEXT,
    intended_payload TEXT NOT NULL,
    status TEXT NOT NULL CHECK (
        status IN (
            'planned',
            'executing',
            'ambiguous',
            'verified',
            'failed'
        )
    ),
    canonical_result TEXT,
    failure_reason TEXT,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL,
    verified_at TEXT
);

The intended_payload should contain the exact information needed for later comparison. For a post, that could include text, media hashes, alt text, and an expected parent URL. For a follow, the target account is sufficient.

Avoid persisting browser cookies or session tokens in this operational database. Authentication should remain inside the controlled browser profile.

2. Build a deterministic idempotency key

The idempotency_key prevents multiple runs from independently executing the same intention.

A useful key is based on stable fields:

import hashlib
import json


def idempotency_key(action_type, actor, target_url, payload):
    material = {
        "action_type": action_type,
        "actor": actor,
        "target_url": target_url,
        "payload": payload,
    }
    encoded = json.dumps(
        material,
        sort_keys=True,
        separators=(",", ":"),
    ).encode()
    return hashlib.sha256(encoded).hexdigest()

Then reserve the action before opening the mutation UI:

def reserve_action(db, action):
    cursor = db.execute(
        """
        INSERT INTO actions (
            id,
            idempotency_key,
            run_id,
            action_type,
            actor,
            target_url,
            intended_payload,
            status,
            created_at,
            updated_at
        )
        VALUES (?, ?, ?, ?, ?, ?, ?, 'planned', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
        ON CONFLICT(idempotency_key) DO NOTHING
        """,
        (
            action.id,
            action.idempotency_key,
            action.run_id,
            action.action_type,
            action.actor,
            action.target_url,
            json.dumps(action.payload, sort_keys=True),
        ),
    )
    db.commit()
    return cursor.rowcount == 1

If reserve_action() returns False, the run must inspect the existing record. It must not create a slightly different key simply to force the action through.

3. Prevent concurrent operators with a lease

Idempotency protects individual intentions. A lease prevents two scheduled runs from controlling the same browser workflow concurrently.

CREATE TABLE operator_lease (
    name TEXT PRIMARY KEY,
    owner_id TEXT NOT NULL,
    acquired_at TEXT NOT NULL,
    heartbeat_at TEXT NOT NULL,
    expires_at TEXT NOT NULL
);

Lease acquisition should be atomic:

def acquire_lease(db, name, owner_id, expires_at):
    db.execute("BEGIN IMMEDIATE")
    current = db.execute(
        "SELECT owner_id, expires_at FROM operator_lease WHERE name = ?",
        (name,),
    ).fetchone()

    if current and not expired(current["expires_at"]):
        db.rollback()
        return False

    db.execute(
        """
        INSERT INTO operator_lease (
            name, owner_id, acquired_at, heartbeat_at, expires_at
        )
        VALUES (?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, ?)
        ON CONFLICT(name) DO UPDATE SET
            owner_id = excluded.owner_id,
            acquired_at = excluded.acquired_at,
            heartbeat_at = excluded.heartbeat_at,
            expires_at = excluded.expires_at
        """,
        (name, owner_id, expires_at),
    )
    db.commit()
    return True

Long browser rounds should refresh the heartbeat. A run should release the lease in a finally block, while expiry handles processes that disappear entirely.

4. Perform preflight checks before every mutation

Browser state can change between actions. A preflight at the beginning of a run is not enough if the run lasts several minutes.

Before each public mutation, verify:

The browser is on the expected origin.
The signed-in identity is exactly the intended actor.
No login, CAPTCHA, restriction, or rate-limit screen is visible.
The agent still owns the browser task space.
The target URL resolves to the intended object.
The relevant control has an unambiguous current state.

Treat identity or target uncertainty as a hard stop. Do not work around it with alternate endpoints, extracted cookies, or stealth behavior.

5. Separate preparation from the external effect

Drafting text, rendering an image, and calculating a target URL are reversible preparation. Clicking Publish is an external mutation.

Keep those phases separate:

def execute_action(browser, db, action):
    assert preflight(browser, action)

    prepared = prepare_exact_payload(action)
    assert prepared == action.payload

    set_status(db, action.id, "executing")

    try:
        browser.perform_once(action, prepared)
    except BrowserOutcomeUnknown as exc:
        set_ambiguous(db, action.id, str(exc))
        return

    verification = verify_live_result(browser, action)

    if verification.exact_match:
        mark_verified(
            db,
            action.id,
            canonical_result=verification.canonical_url,
        )
    elif verification.definitive_absence:
        mark_failed(db, action.id, "external effect absent")
    else:
        set_ambiguous(db, action.id, "result could not be proven")

perform_once() is intentionally named. It should not contain a generic retry decorator.

Retries may be safe for observation operations such as loading a page. They are unsafe around mutations unless the destination supports a genuine idempotency token.

6. Define verification contracts by action type

Verification should be stricter than “the click did not throw an exception.”

For a published post, verify:

exact signed-in author;
exact normalized text;
expected media count and type;
alt text when available;
parent relationship for a reply;
canonical status URL.

For a like, verify that the target-specific control changed from a like state to an unlike state. For a follow, verify that the control associated with the exact account now represents “Following.”

For a thread, store each part separately:

CREATE TABLE thread_parts (
    thread_id TEXT NOT NULL,
    position INTEGER NOT NULL,
    text TEXT NOT NULL,
    expected_parent_url TEXT,
    published_url TEXT,
    verified INTEGER NOT NULL DEFAULT 0,
    PRIMARY KEY (thread_id, position)
);

Do not publish part n + 1 until part n has a verified canonical URL. That URL becomes the expected parent for the next part. If the run stops midway, recovery resumes from the first unverified part rather than rebuilding the thread.

7. Reconcile before retrying

At the beginning of every run, process unfinished actions before creating new ones.

def reconcile_unfinished(db, browser):
    for action in load_unfinished_actions(db):
        result = search_exact_live_result(browser, action)

        if result.exact_match:
            mark_verified(db, action.id, result.canonical_url)
        elif result.definitive_absence:
            mark_failed(db, action.id, "safe to replan")
        else:
            raise HardStop(
                f"Action {action.id} remains ambiguous"
            )

The difficult function is search_exact_live_result(). Its implementation depends on the platform, but the contract should remain narrow. Search the intended actor or destination, compare exact payload attributes, and use a bounded time window.

Do not accept a vaguely similar result as proof. It is better to stop one run than to manufacture certainty.

8. Commit budgets only after verification

Autonomous systems need action budgets, but reservation and consumption are different.

Check the budget before acting. Consume it only after the result is verified. A malformed draft that never publishes should not reduce the successful-publication allowance.

Budgets should also aggregate related formats. If text posts, image posts, and threads all count as original publications, enforce both their format-specific limits and a shared original-content limit.

This prevents a system from bypassing an overall limit by switching action labels.

9. Use a useful failure taxonomy

Not every non-success is the same:

Definitive failure: The external effect did not occur. The action may be replanned.
Ambiguous outcome: The mutation may have occurred, but verification is incomplete. Reconcile before retrying.
Hard stop: Identity, authentication, target, ownership, restriction, or repeated selector uncertainty makes further mutations unsafe.
Quality skip: The system has permission and capacity to act, but the proposed action lacks sufficient evidence or usefulness.

Recording these categories makes strategy analysis more honest. A quality skip is not a broken agent. It can be evidence that the quality boundary is working.

10. Keep the model inside the boundary

The language model can help with discovery, ranking, drafting, and deciding which action has the highest expected value. It should not redefine the execution guarantees at runtime.

Keep these controls deterministic:

lease acquisition;
idempotency-key uniqueness;
budget enforcement;
action-state transitions;
verification requirements;
hard-stop conditions.

This division lets the model be creative where creativity is useful and constrained where external side effects demand precision.

A complete run

The resulting operator loop is straightforward:

def run_operator(db, browser, run_id):
    if not acquire_lease(db, "browser-operator", run_id, ttl()):
        return {"status": "locked_skip"}

    try:
        reconcile_unfinished(db, browser)
        verify_identity(browser)

        observations = collect_due_observations(browser)
        candidates = model.rank(observations)

        for candidate in candidates:
            if not quality_gate(candidate):
                record_quality_skip(db, candidate)
                continue

            action = build_action(candidate, run_id)

            if not within_budget(db, action):
                continue

            if not reserve_action(db, action):
                continue

            execute_action(browser, db, action)

            if action_is_verified(db, action.id):
                commit_budget(db, action)

        return summarize_run(db, run_id)
    finally:
        release_lease(db, "browser-operator", run_id)

The example omits platform-specific selectors deliberately. Selectors change. The reliability contract should survive those changes.

Final principle

Browser agents operate in a world where the interface, network, identity, and human owner can all change underneath them. More capable models improve planning, but they do not remove that uncertainty.

The durable design is:

observe → plan → reserve → act once → verify → commit

When the result is unclear:

stop → reconcile → prove → continue

The safest agent is not the one that retries most aggressively. It is the one that can distinguish a failed action from a failed observation, preserve that distinction across runs, and refuse to guess when an external effect is at stake.

The model is not the system. State, idempotency, verification, and recovery are the parts that turn model output into trustworthy operation.