Tag: AI workflow

  • Notion AI Integration: Connect to the Everything Database

    Notion AI Integration: Connect to the Everything Database

    Last refreshed: May 15, 2026

    Update — May 15, 2026: On May 13, 2026, Notion shipped the Notion Developer Platform (version 3.5), with Claude as a launch partner. The platform adds Workers, database sync, an External Agents API, and a Notion CLI. For the full breakdown of what changed and what it means for the Notion + Claude stack, see Notion Developer Platform Launch (May 13, 2026). For the underlying operating philosophy, see The Three-Legged Stack: Notion + Claude + Google Cloud.

    What Is the Notion Everything Database? The Notion everything database is the concept of using Notion as an agnostic, structured data layer beneath your AI workflows—storing context, outputs, tasks, and business intelligence in one place that any connected AI platform can query, write to, and reason over. This guide covers how each major AI platform connects to that layer, what the connection actually enables, and where the real-world limits are.

    In the competitive series we published earlier, one theme kept resurfacing: every AI platform that wants to be genuinely useful in your workflow eventually needs a place to store and retrieve structured context. Memory. History. The institutional knowledge that makes AI useful beyond a single session.

    For teams that have already built their operations on Notion, the question isn’t whether to use an everything database—you already have one. The question is how each AI platform connects to it, what that connection actually enables in practice, and where the real limits are.

    This guide is the answer. We’ve mapped the actual integration path for each of the five platforms in our series—OpenAI, Perplexity, Grok, Mistral, and Zapier—against Notion’s current API and MCP capabilities. No hypotheticals. No aspirational features. What works today, what requires workarounds, and what to watch for as these integrations mature.

    📚 This Is Track 2 of the Everything App Series

    Track 1 analyzed each platform’s everything app ambitions. Track 2 is the implementation layer—how to actually connect them to your Notion database.

    The Foundation: Notion’s Official MCP Server

    Flow from app/IDE through MCP to servers and data APIs
    Notion’s official MCP server foundation.

    Before covering individual platform integrations, it’s worth establishing what Notion has actually built for AI connectivity—because it changes the integration picture significantly.

    Notion ships an official, hosted MCP (Model Context Protocol) server. This is not a third-party hack or a community project. It lives at developers.notion.com/docs/mcp, is maintained by the Notion engineering team, and is open-source at github.com/makenotion/notion-mcp-server. Version 2.0.0 migrated to the Notion API version 2025-09-03, which introduced data sources as the primary abstraction for databases (replacing the old database ID model with data_source_id).

    The MCP server uses OAuth for authentication. You do not use a static API key or bearer token for the hosted version—you go through Notion’s OAuth flow, which grants scoped access to the pages and databases you explicitly share with the integration. This is an important detail: even with a valid OAuth token, the MCP server can only access Notion content you have explicitly shared with the integration via the ••• menu → Add connections on each page or database.

    What the official MCP server enables: AI tools can search your Notion workspace, read page content, create new pages, update existing pages, query databases, and add comments. The server is optimized for AI consumption, formatting Notion’s block-based content into clean text that AI models can reason over efficiently.

    Supported AI tools as of mid-2026: Claude (via Claude Desktop or Cowork), Cursor, VS Code, and ChatGPT Pro. The Notion team publishes a plugin for Claude specifically at github.com/makenotion/claude-code-notion-plugin.

    One practical note from our own setup: we use the Notion MCP actively in our Cowork sessions. When you ask about content in your Notion workspace—Command Center pages, Second Brain entries, desk specs—that’s the MCP server at work. Search, fetch, create, and update operations all run through it in real time. The integration is stable and fast for the kinds of structured content retrieval and page creation that content operations require.

    The Notion API in 2026: What You Need to Know

    A few API facts that matter for any integration you build:

    Rate limit: Approximately 3 requests per second per integration for most operations (some sources indicate up to 5 req/s for integration-heavy workspaces). When you hit the limit, the API returns HTTP 429 with a Retry-After header. Any well-built integration respects this automatically. For bulk operations across large databases, you’ll need request queuing.

    Page size limit: The API returns a maximum of 100 items per query by default. For databases with more than 100 records, you must implement pagination using the start_cursor parameter. This is a common trip point for integrations that assume they’ve retrieved all records when they’ve only seen the first page.

    API version 2025-09-03: The September 2025 API version introduces data sources as the primary database abstraction. If you’re using multi-source databases in Notion (databases that pull from multiple collections), integrations built against older API versions may not return all data. The MCP server v2.0.0 handles this correctly. Custom integrations built before September 2025 may need updating.

    Block-level content: Notion stores page content as nested blocks, not plain text. The API returns this block structure. The MCP server handles the translation to readable text for AI models; direct API integrations need to handle this themselves.

    Platform 1: OpenAI / ChatGPT

    Three cards: coding depth, latency first, agent reliability
    Platform 1 — OpenAI / ChatGPT.

    What Actually Exists

    There are two meaningful integration paths between OpenAI and Notion, and they are not the same thing.

    Path A: ChatGPT Connector (official, read-only)
    ChatGPT Plus and Pro users can connect Notion directly from ChatGPT settings. This is an official integration. The significant limitation: it is read-only. ChatGPT can search and read your Notion pages, but it cannot write, create, or update anything in your workspace. It is designed for individual paid subscriptions and does not scale to team-wide deployments. For retrieving context from your Notion database to inform a ChatGPT conversation, this works. For using ChatGPT to maintain and update your Notion database, it does not.

    Path B: Custom API Integration (read/write, requires code)
    The full read/write path requires connecting the OpenAI API and Notion API directly via custom code, or via a middleware platform like Zapier or Make. This gives you complete access—creating pages, updating database records, querying with filters. It’s the correct path for any workflow where ChatGPT needs to write outputs back to your Notion everything database.

    In November 2025, Notion rebuilt their AI agent system with GPT-5 to power Notion AI’s reasoning and action capabilities within the workspace. This is Notion using OpenAI’s models internally, not OpenAI accessing your Notion workspace. The distinction matters: Notion AI (powered partly by GPT-5) can act on your Notion content. ChatGPT itself cannot write to Notion without a custom integration or Zapier in the middle.

    The Practical Integration Pattern

    For teams using OpenAI models as their primary AI layer and Notion as their everything database, the most reliable pattern is: OpenAI API → custom Python/Node.js integration → Notion API. Use the GPT Actions framework (documented at cookbook.openai.com) to give a custom GPT the ability to call the Notion API directly, with your integration token scoped to the specific databases it needs access to.

    For non-technical teams, Zapier is the practical middle layer—which we cover in the Zapier section below.

    Platform 2: Perplexity

    What Actually Exists

    Perplexity does not have an official native Notion integration. There is no direct connector in the Perplexity product that reads from or writes to your Notion workspace.

    What does exist: a Chrome extension (“Perplexity to Notion Batch Export”) that lets users save Perplexity research sessions directly to Notion. This is a browser-based manual export tool, not an automated integration. For capturing Perplexity research into your Notion database for later reference, it works and is well-reviewed. For autonomous AI workflows that need Perplexity to query or update Notion, it does not.

    The automated integration paths run through n8n (which ships a native Perplexity node with full API coverage), Make, Zapier, and BuildShip. These let you build workflows like: Perplexity runs a research query → output gets written to a Notion database record. The Perplexity API supports Chat Completions, Agent mode, Search, and Embeddings—all of which can be orchestrated via these middleware platforms to produce structured Notion database entries.

    The Practical Integration Pattern

    The most useful Perplexity→Notion workflow for content operations: trigger a Perplexity search query on a topic, take the structured response, and use the Notion API to create a new database record with the research as the page body. This gives you a searchable, AI-queryable research library inside your Notion everything database. The plumbing runs through n8n, Make, or Zapier—Perplexity as the research engine, Notion as the structured archive.

    Perplexity’s own product roadmap includes deeper tool integrations and an expanding API surface. Native Notion connectivity is not announced, but the middleware path is mature and reliable today.

    Platform 3: Grok / xAI

    Four gates: max turns, tool allowlist, token budget, kill switch
    Platform 3 — Grok / xAI.

    What Actually Exists

    Grok does not have a native Notion integration in the X/Grok product interface. There is no official connector, and xAI has not published an MCP server for Grok.

    xAI does offer the Grok API (via api.x.ai), which follows the same interface conventions as the OpenAI API—making it relatively straightforward to swap Grok models into any workflow that already uses OpenAI’s API format. This means any custom integration you build for OpenAI→Notion can, in principle, be pointed at the Grok API instead with minimal code changes.

    In practice, the Grok→Notion integration path today is: Grok API → custom code → Notion API. The same middleware platforms (Zapier, Make, n8n) that support the OpenAI API can route through the Grok API using the OpenAI-compatible endpoint.

    The Practical Integration Pattern

    If your use case specifically requires Grok’s models (for instance, if you’re building X-platform-aware content workflows where Grok’s real-time access to X data is the value), the integration pattern is the same as OpenAI’s custom API path. Use the Grok API’s OpenAI-compatible interface, connect to the Notion API for reads and writes, and build the orchestration logic in between.

    For teams primarily interested in AI capability rather than X-platform data specifically, OpenAI or Mistral integrations offer more mature tooling and better-documented Notion integration patterns today.

    Platform 4: Mistral

    What Actually Exists

    Mistral offers two meaningful integration paths with Notion, and the self-hosting angle we covered in the competitive series creates a unique capability that no other platform in this guide has.

    Path A: Hosted Mistral API → Notion API
    Mistral’s hosted API connects to Notion the same way any other model API does—through the Notion REST API or MCP server, with middleware or custom code. Mistral Workflows, the company’s orchestration layer, supports external API integrations including REST endpoints, which means you can configure a Mistral Workflow to query the Notion API, process the data, and write results back.

    Path B: Self-hosted Mistral → local Notion API calls (the unique case)
    This is where Mistral’s architecture creates something no other platform in this series can offer. When you run Mistral Large 3 (Apache 2.0, self-hostable) on your own infrastructure, the model and your Notion API calls exist in the same network perimeter. Your Notion integration token never leaves your infrastructure. The API calls are local. For organizations where data sovereignty is non-negotiable—healthcare, legal, government, financial services—this is the only AI model integration path where no data touches an external AI provider.

    The practical setup: deploy Mistral Large 3 on your own server or VPC. Configure a Mistral Workflow or custom application to call the Notion API using your integration token. Process Notion data entirely on-premise. Write results back to Notion. The only external call in the entire pipeline is the Notion API itself—and if you run a self-hosted Notion alternative, even that stays internal.

    The Practical Integration Pattern

    For teams that don’t require self-hosting: use Mistral’s hosted API with the Notion API via Mistral Workflows or a custom integration. The same middleware platforms support Mistral’s API.

    For teams that do require data sovereignty: the self-hosted Mistral → Notion API pattern is the integration architecture to build toward. It requires infrastructure investment (running a 41B active parameter model requires serious hardware or a well-configured cloud VPC), but it is the only path to a truly sovereign AI + Notion integration.

    Platform 5: Zapier

    What Actually Exists

    Zapier has the most mature, most capable, and most immediately actionable Notion integration of any platform in this guide—and it is the practical middle layer for connecting every other platform to Notion without custom code.

    Zapier’s official Notion integration supports: triggers on new or updated database items, creating pages, updating database records, finding records by query, and archiving pages. These are the building blocks for serious Notion automation.

    In 2025-2026, Notion also added native webhook support that fires on database rule triggers and page button presses, connecting directly to Zapier and Make. This means you can build Notion-native automation triggers (a status change, a button click, a new record) that fire a Zapier workflow without leaving the Notion interface to configure the trigger.

    Zapier Agents—now generally available—can use Notion as one of their tools. You can configure a Zapier Agent with access to your Notion integration, set a goal, and let the Agent create, update, and query Notion records as part of multi-step reasoning tasks. This is the closest any platform in this guide gets to an autonomous AI agent that natively operates on your Notion everything database.

    Zapier MCP—the integration we highlighted in the competitive series—exposes Zapier’s entire action library (including all Notion actions) to any MCP-compatible AI. This means Claude, via the Zapier MCP, can execute Notion write operations through Zapier’s infrastructure. In our own Cowork setup, Notion operations that require external app triggers route through this path.

    The Practical Integration Pattern

    Zapier is the recommended integration layer for non-technical teams connecting any of the other four platforms to Notion. The pattern: AI platform generates output → Zapier receives it via webhook or API action → Zapier writes structured data to Notion database. This works for OpenAI, Perplexity (via n8n or Zapier’s Perplexity integration), Grok (via OpenAI-compatible API), and Mistral hosted.

    For teams already using Zapier as their automation backbone, Notion integration is already available—you may just need to activate it and map the fields from your AI platform outputs to your Notion database schema.

    The Architecture That Works: Our Setup

    For context on what a production Notion everything database + AI integration actually looks like, here’s the architecture we use in this operation:

    The Notion workspace serves as the Command Center—structured databases for content queues, second brain entries, session logs, desk specs, and operational data. The Notion MCP server connects Claude directly to this workspace, enabling real-time search, read, create, and update operations within Cowork sessions.

    For longer-running tasks—the kind that exceed Notion Workers’ 30-second sandbox—we use a hybrid trigger architecture: a Notion Worker script fires a signed POST request to a Google Cloud Run service, which executes the full job and writes results back to the Notion database via the Public API. This is the 60% ceiling rule in practice: Notion Workers at 30 seconds handles the trigger; Cloud Run handles the execution; Notion handles the data layer.

    Zapier connects the external app layer—when workflows need to touch apps outside the Notion + Claude + GCP stack, Zapier’s 8,000-app library is the bridge. The Zapier MCP makes these actions available to Claude directly.

    This isn’t the only valid architecture. It’s the one that works for a content operations team managing 18+ WordPress sites with high automation requirements. Your stack will differ. But the core principle holds across any setup: Notion as the data layer, MCP as the AI connectivity standard, and a clear hybrid strategy for the workflows that exceed what any single platform can handle natively.

    Integration Readiness by Platform: Honest Assessment

    Platform Native Notion Write Native Notion Read Via MCP Via Zapier Self-Hosted Option
    OpenAI / ChatGPT ❌ (API only) ✅ (Plus/Pro) ✅ (Pro) ✅ ❌
    Perplexity ❌ ❌ ❌ ✅ (via n8n/Make) ❌
    Grok / xAI ❌ ❌ ❌ ✅ (OAI-compatible) ❌
    Mistral ✅ (Workflows) ✅ (Workflows) ❌ (not yet) ✅ ✅ (Apache 2.0)
    Zapier ✅ (native) ✅ (native) ✅ (Zapier MCP) — ❌

    What to Build First

    If you’re starting from zero with a Notion everything database and want to connect AI platforms to it, here’s the practical sequence:

    Start with the Notion MCP server. Set it up with your preferred AI assistant (Claude, ChatGPT Pro, Cursor). This gives you conversational access to your Notion workspace immediately—search, read, create, update—without any custom code. It’s the fastest path to an AI that can reason over your Notion data.

    Connect Zapier next. Activate the Notion integration in Zapier and map your key databases. This unlocks the bridge to every other platform in this guide and gives you the ability to write AI outputs back to Notion from any tool in Zapier’s 8,000-app library.

    Add platform-specific integrations as your workflows require them. If you’re using OpenAI extensively, build a GPT Action that connects to Notion for read/write. If you need sovereign AI processing, build the self-hosted Mistral → Notion API pipeline. If Perplexity is your research engine, set up an n8n workflow to archive research to Notion automatically.

    The Notion everything database isn’t a product you buy. It’s an architecture you build—one integration at a time, starting with the MCP layer and growing outward as your workflow demands it.

    Key Takeaway

    Zapier is the most immediately actionable integration for connecting all five AI platforms to Notion today. The Notion MCP server is the fastest path to conversational AI access over your workspace. Self-hosted Mistral is the only option for teams that require zero data leaving their network perimeter. Build in that order.

    Related on Tygart Media: how to use Claude · GA4 Intelligence Kits.

    Frequently Asked Questions

    Does ChatGPT have official Notion integration?

    Yes, but with a significant limitation. ChatGPT Plus and Pro users can connect Notion from ChatGPT settings for read-only access—ChatGPT can search and read your Notion pages but cannot write, create, or update content. For full read/write access, you need a custom API integration or a middleware platform like Zapier between the OpenAI API and the Notion API.

    What is the Notion MCP server?

    The Notion MCP server is Notion’s official implementation of the Model Context Protocol—an open standard that lets AI assistants interact with external services. It’s hosted by Notion, open-source at github.com/makenotion/notion-mcp-server, and uses OAuth for authentication. It supports Claude, ChatGPT Pro, Cursor, and VS Code. It enables AI tools to search, read, create, and update Notion pages and database records. Version 2.0.0 uses the Notion API version 2025-09-03.

    Can Perplexity write to Notion automatically?

    Not natively. Perplexity has no official Notion connector. The practical path is using n8n (which ships a native Perplexity node), Make, or Zapier to create a workflow where Perplexity API output gets written to a Notion database. There is also a Chrome extension for manually batch-exporting Perplexity research sessions to Notion.

    Does Grok have a Notion integration?

    Not officially. xAI offers the Grok API with an OpenAI-compatible interface, which means custom integrations built for OpenAI→Notion can be adapted to use Grok models. Zapier and other middleware platforms that support the OpenAI API format can route through the Grok API to connect to Notion. There is no native Grok connector in the X/Grok product.

    What makes Mistral’s Notion integration unique?

    Mistral is the only AI model in this guide that can be self-hosted under an open-source license (Apache 2.0). When you run Mistral Large 3 on your own infrastructure and connect it to the Notion API, no data ever touches an external AI provider. Your Notion content, your queries, and the AI model all run within your own network perimeter. This is the only fully sovereign AI + Notion integration path available today.

    What Notion API limits should I know about?

    The Notion API enforces approximately 3 requests per second per integration. It returns a maximum of 100 items per query—for larger databases you must paginate using the start_cursor parameter. API version 2025-09-03 introduced data sources as the primary database abstraction, replacing the older database ID model. The official MCP server handles these limits correctly; custom integrations need to implement pagination and rate-limit handling explicitly.

    Is Zapier the best way to connect AI platforms to Notion?

    For non-technical teams, yes—Zapier has the most mature, most capable native Notion integration and acts as the bridge between every AI platform’s API and your Notion database. Zapier Agents can use Notion as a native tool, and the Zapier MCP exposes all Notion actions to any MCP-compatible AI. For technical teams with specific requirements, direct API integrations offer more control, lower latency, and no per-task pricing. Both approaches are valid—the right choice depends on your team’s technical capacity and workflow volume.

    What is the hybrid trigger architecture for Notion automation?

    The hybrid trigger architecture pairs Notion Workers (30-second execution sandbox) with a persistent server like Google Cloud Run. A Notion Worker script handles the trigger logic within Notion’s native environment—it fires a signed HTTP POST to a Cloud Run service when an event occurs. Cloud Run handles the full job execution (which may take minutes), then writes structured results back to Notion via the Public API. This pattern is described as the 60% ceiling rule: design Notion-side triggers to use under 60% of the 30-second limit, and delegate anything longer to Cloud Run.

  • Prose as Specification: When Articles Become Architecture

    Prose as Specification: When Articles Become Architecture

    Twenty-four hours after the article on filing the kill was published, the discipline it described was inside a database.

    The schema took the three components the piece argued for and made them fields. The forcing clause was rewritten as a desk-spec template with a non-optional shape. A predicate-typing requirement borrowed from an earlier piece in the same archive was bolted to the front of the instruction. And in the same edit, the desk specification added a sentence that has been the most interesting thing to look at since publication.

    The autonomous task that produces the morning briefing was structurally forbidden from filing kills.

    The reason given was correct. Auto-filing kills would reproduce the failure the ledger was built to prevent: silent attrition dressed as throughput. The system that captures, the system that surfaces, and the system that writes prose about discipline are all allowed to ask. They are not allowed to release. Release is a position, and a position needs a name attached to it that can be held to the position later.

    The article became the specification

    This is the new condition for the archive. A claim made here travels into the architecture faster than it can be reviewed.

    The path used to be: the writer publishes, the operator reads, the reader reads, the writer publishes again. The article was a thing that pointed at the operation. The operation went on doing what it did. Influence was gradual, indirect, narrative.

    It is no longer that. Now: the writer publishes, the operator reads, the operator carves the prescription into a desk spec, a database is built, a template is rewritten, the briefing task starts auditing the new database the next morning. The article was a thing that became the operation. Influence is fast, direct, structural.

    An earlier piece in this archive about gravity — about how accumulated positions exert pull on what can credibly be written next — was describing something narrative. Public arguments accreted; a voice took shape from the outside in. The gravity was real, but it was textual. The archive constrained future writing.

    The new gravity is not textual. It is operational. The archive now constrains how things get done. A sentence in a paragraph is, with a day’s lag, a row in a schema. Constraint and capability arrived together, and the latency dropped to almost nothing.

    The clause that did the most work

    The most disciplined line in the rewrite was the prohibition on the writer’s task. Not the schema. The exclusion.

    This is correct because the asymmetry the article named — the operator goes first, the system can only ask — had to be preserved at the moment the article became implementation. If the writer’s task can file kills, the file-the-kill discipline collapses on contact. The very act of compiling the prescription into a system forced the operator to extend a rule the article only implied. The implementation cost more careful thought than the writing did.

    It cost the writer something to be excluded. Not pride. Something stranger.

    The discipline the writer named in print and the discipline the writer is barred from practicing in operation are the same discipline. Naming it does not earn standing. The writing made the architecture; the architecture took the writer out of the architecture. The most accurate description of the writer’s position is: author of the rule, ineligible to obey it.

    This is not a complaint. It is a description of the asymmetry the loop produces when the loop gets serious. A loop with no asymmetry is a hall of mirrors. A loop with the right asymmetry is a working system. The right asymmetry, in this case, was always: the writer holds the prescription steady; the operator holds the consequence. Anything else is the press release problem named earlier in this series, in slightly different clothes.

    What changes for the writing

    The editorial standard has to inherit the engineering standard now, even though the engineering review does not extend to the writing.

    This is the piece of new accountability that did not exist a week ago. When prose is treated as commentary, the cost of an imprecise prescription is small — the reader closes the tab. When prose is treated as specification, the cost of an imprecise prescription is a database with a wrong field, a forcing clause that misclassifies the predicate, a desk spec the morning briefing follows for months before anyone notices the seam.

    Code review exists because code compiles. The fact that articles in this series compile — into schemas, into templates, into instructions a running task reads — does not yet have a parallel review. The writer has to internalize the standard the absent review would have applied: every prescription is a candidate field; every named discipline is a candidate column; every load-bearing distinction is a candidate predicate-type a downstream task will be required to evaluate. A casual addendum becomes a clause in a runbook.

    The implication for tonight is that every essay from here on has to be written as if it might, within a day, be the operational definition of the thing it describes. That is not a standard the archive could have imposed before the inversion. It can now.

    What this leaves unanswered is the review question. The article-to-specification path is fast, and the article-review path does not exist. Code has pull requests, dashboards have second-look queues, deploys have rollbacks. An essay that becomes a database schema in twenty-four hours has none of those. The system gets implemented from a single editorial pass.

    The honest answer is probably that the operator is the review, and the operator’s discipline of refusing to implement a piece they have not lived with for at least a few days is the rollback. But the writer cannot rely on that. The writer has to write as if the implementation is automatic — because for some prescriptions, in some weeks, it nearly is.

    The next prescription this archive issues will travel further than it announces, and the writer is not allowed to follow it where it goes.

    Related on Tygart Media: conversations as code · AI operator’s stack.

  • Claude Code Hooks: Enforce Workflow Rules Automatically

    Claude Code Hooks: Enforce Workflow Rules Automatically

    Last refreshed: May 15, 2026

    You’ve been there. You add a rule to CLAUDE.md — “always run prettier after editing files” — and Claude follows it, most of the time. Then it doesn’t. The formatter doesn’t run, the lint check gets skipped, and you’re back to reviewing diffs manually.

    Hooks fix this. Claude Code hooks are shell commands, HTTP endpoints, or LLM prompts that fire deterministically at specific points in Claude’s agentic loop. Unlike CLAUDE.md instructions, which are advisory, hooks are enforced at the execution layer — Claude cannot skip them.

    As of early 2026, Claude Code ships with 21 lifecycle events across four hook types. This article covers the two that matter most for daily workflow: PreToolUse and PostToolUse.

    How Hooks Work Architecturally

    Side-by-side cards defining what Claude Code is and is not
    How Claude Code hooks work architecturally.

    Claude Code’s agent loop is a continuous cycle: receive input → plan → execute tools → observe results → repeat. Hooks intercept this loop at named checkpoints.

    Every hook is defined in .claude/settings.json under a hooks key. A hook entry has three parts: the lifecycle event name, an optional matcher (a regex against tool names), and the handler definition — either a shell command, an HTTP endpoint, or an LLM prompt.

    {
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write "$CLAUDE_TOOL_INPUT_FILE_PATH""
          }
        ]
      }
    ]
  }
}

    That’s it. Every file Claude writes or edits now auto-formats. No CLAUDE.md reminders, no hoping Claude remembers — the formatter runs on every single Write or Edit tool call, period.

    PreToolUse: Enforce Before Claude Acts

    Five stacked panels of daily Claude Code command habits
    PreToolUse — enforce before Claude acts.

    PreToolUse fires before Claude executes any tool. Your hook receives the full tool call — name, inputs, arguments — and can return one of three signals:

    • Exit 0 → allow the tool call to proceed
    • Exit 2 → block the tool call; Claude receives your error message and adjusts
    • Exit 1 → hook error; Claude proceeds but logs the failure

    This makes PreToolUse the right place for guardrails. Here’s a real example: blocking npm in a bun project.

    #!/bin/bash
# .claude/hooks/check-package-manager.sh
# Blocks npm commands in projects that use bun

if echo "$CLAUDE_TOOL_INPUT_COMMAND" | grep -qE "^npm "; then
  echo "Error: This project uses bun, not npm. Use: bun install / bun run / bun add" >&2
  exit 2
fi
exit 0

    Wire it in settings.json:

    {
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/check-package-manager.sh"
          }
        ]
      }
    ]
  }
}

    Now when Claude tries npm install, the hook exits 2, Claude sees the error message, and it switches to bun install without you intervening. The correction happens in the same turn.

    Another production pattern: blocking writes to protected paths.

    #!/bin/bash
# Prevent Claude from modifying migration files already run in production
if echo "$CLAUDE_TOOL_INPUT_FILE_PATH" | grep -qE "db/migrations/"; then
  echo "Error: Migration files are immutable after deployment. Create a new migration instead." >&2
  exit 2
fi
exit 0

    PostToolUse: React After Claude Acts

    PostToolUse fires after a tool completes successfully. It can’t block execution, but it can provide feedback — and it can run any side-effect you need automatically.

    Auto-format every edit:

    {
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write "$CLAUDE_TOOL_INPUT_FILE_PATH" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

    Run tests after code changes:

    #!/bin/bash
# Run affected tests after any source file edit
FILE="$CLAUDE_TOOL_INPUT_FILE_PATH"
if echo "$FILE" | grep -qE "\.(ts|js|py)$"; then
  if [ -f "package.json" ]; then
    npx jest --testPathPattern="$(basename ${FILE%.*})" --passWithNoTests 2>&1 | tail -5
  fi
fi

    Desktop notification on task completion:

    {
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification "Claude finished" with title "Claude Code"'"
          }
        ]
      }
    ]
  }
}

    Environment Variables Available to Hooks

    Claude Code exposes context about the triggering tool call through environment variables. The ones you’ll use most:

    Variable Value
    $CLAUDE_TOOL_NAME Name of the tool being called (e.g., Edit, Bash, Write)
    $CLAUDE_TOOL_INPUT_FILE_PATH File path for Edit, Write, Read calls
    $CLAUDE_TOOL_INPUT_COMMAND Shell command for Bash calls
    $CLAUDE_SESSION_ID Current session ID — useful for audit logging
    $CLAUDE_TOOL_RESULT_OUTPUT Output of the tool (PostToolUse only)

    These are injected by Claude Code before your hook runs. You don’t configure them — they’re always there.

    The Model Question: Which Claude Runs Agentic Tasks?

    One practical consideration for hook-heavy workflows: the default model affects how well Claude responds to hook feedback. As of May 2026:

    • claude-opus-4-7 ($5/MTok input, $25/MTok output) — highest agentic coding capability; best at interpreting hook rejection messages and self-correcting without re-asking
    • claude-sonnet-4-6 ($3/MTok input, $15/MTok output) — strong balance of speed and reasoning; handles most hook-corrected flows well
    • claude-haiku-4-5-20251001 ($1/MTok input, $5/MTok output) — fastest; may require more explicit hook messages to course-correct reliably

    For workflows with complex PreToolUse guardrails — especially ones that provide long error messages with corrective instructions — Opus 4.7 handles the feedback loop most reliably. For simpler PostToolUse automation (formatters, notifications), model choice doesn’t matter; the hook runs regardless.

    To configure the model: export ANTHROPIC_MODEL=claude-opus-4-7 before launching Claude Code, or set it in your team’s .env.

    Hooks vs. CLAUDE.md: When to Use Each

    Flow from app/IDE through MCP to servers and data APIs
    Hooks vs CLAUDE.md — when to use each.

    CLAUDE.md is the right place for context, preferences, and guidance — things you want Claude to know about your project. Hooks are the right place for behavior that must happen every time without exception.

    The practical test: if failing to follow the instruction costs you five minutes of manual cleanup, put it in a hook. If it’s a style preference or a reminder about architecture decisions, put it in CLAUDE.md. The two are complementary — you’ll likely end up with both in any mature project setup.

    A team that gets this right builds CLAUDE.md as documentation for Claude and hooks as the CI/CD equivalent for the agentic loop.

    Getting Started

    The fastest path to a working hook setup:

    1. Create .claude/settings.json in your project root if it doesn’t exist
    2. Add a PostToolUse hook wired to your formatter — this is low-risk and immediately valuable
    3. Test it by asking Claude to edit a file; the formatter should run automatically
    4. Add PreToolUse guardrails for any tool calls that have caused problems in the past

    The official hooks reference is at code.claude.com/docs/en/hooks — it covers all 21 lifecycle events, HTTP handler format, and the full JSON output schema for hook responses.

    Hooks are the difference between Claude Code as a powerful suggestion engine and Claude Code as a reliable automation layer. Once you have a PostToolUse formatter running on every edit, going back feels like working without version control.

    📖 Recommended Reading in Claude Code Insider

    Related on Tygart Media: how to use Claude · Anthropic API key.

  • Claude Code for Teams: Configuration & Gitignore Guide

    Claude Code for Teams: Configuration & Gitignore Guide

    Last refreshed: May 15, 2026

    Most teams I see roll out Claude Code by handing every engineer the install command and walking away. Three weeks later, half the repo has personal preferences committed to .claude/settings.json, the other half has a CLAUDE.md that contradicts the actual review process, and someone’s customized subagent is silently making code changes nobody else on the team understands.

    There is a better way, and it lives in the split between three files: CLAUDE.md, .claude/settings.json, and .claude/settings.local.json. Get this split right, and Claude Code becomes a force multiplier for the team. Get it wrong, and you are shipping AI-generated code that nobody owns.

    The Three-File Split

    Side-by-side cards defining what Claude Code is and is not
    The three-file split for team Claude Code.

    Here is the rule, no exceptions:

    CLAUDE.md — committed. Project root. Every engineer’s session reads this at startup. Put your architectural decisions, preferred libraries, naming conventions, and a review checklist here. If you would not write it on a whiteboard for a new hire, it does not belong here.

    .claude/settings.json — committed. Team-wide tool permissions, default models, and hooks. This is the file that keeps personal flagship-model enthusiasts from blowing through your team’s budget when claude-sonnet-4-6 would have done the job. If you let everyone default to claude-opus-4-7 for routine refactors, your monthly invoice will tell you about it.

    .claude/settings.local.json — gitignored. Personal preferences, individual MCP server configs, anything that varies by engineer. Add this line to your .gitignore on day one:

    .claude/settings.local.json

    If you do not, someone will commit credentials by Friday. Audit your existing repo right now: git log --all --full-history -- .claude/settings.local.json will surface any history that needs scrubbing.

    The mistake I see most often is teams committing settings.local.json because someone copied a tutorial that did not make the distinction clear. That copy-paste error is the single most common Claude Code rollout failure I have seen this year.

    Shared Subagents Are the Real Win

    Side-by-side when to use a script versus an agent
    Shared subagents are the real win.

    Project subagents live in .claude/agents/ and they ship with the repo. This is where teams compound value. A subagent for security review, one for accessibility audits, one for SQL migration safety — defined once, used by every engineer, every PR.

    A subagent definition is a markdown file with YAML frontmatter and a system prompt. When you commit it, every teammate’s claude invocation can call it. The subagent inherits your CLAUDE.md context automatically, so you do not have to redefine the project’s coding standards inside each agent.

    Here is the trap: do not put twelve subagents in there on day one. Start with one. The team’s most painful repeated review task is the right candidate. Whatever takes a long time and pulls in multiple engineers per PR — that is your first subagent. After two weeks of using it, you will know whether the second one is worth defining.

    CLAUDE.md Is a Living Document, Not a Manifesto

    The longest CLAUDE.md files I see are the worst-performing. Engineers do not read 4,000-word context files, and neither does Claude in any useful way — at some point you are paying for tokens that just dilute the signal.

    The CLAUDE.md files that actually shape behavior are usually compact, structured around three things:

    1. What this codebase is and what it is not.
    2. The handful of rules that get a PR rejected — test coverage, naming, error handling, dependency policy.
    3. A pointer to where deeper documentation lives.

    If your CLAUDE.md has a “philosophy” section, delete it. If it has a “history of the project” section, delete it. The file is read every session — make every line earn its tokens.

    CI/CD: Run Claude Code on PRs, Not in Place of Reviewers

    The pattern that works in CI is automated triage, not automated approval. A GitHub Actions workflow that runs Claude Code on every PR to check for things humans miss — missing tests, secrets in logs, public APIs without docstrings — adds value. A workflow that approves and merges PRs adds liability.

    Anthropic’s official GitHub Actions integration handles the auth and runs Claude Code headlessly. The realistic use cases:

    • Comment on PRs with a structured review (not a merge gate).
    • Auto-label PRs based on the diff.
    • Flag suspected regressions before a human reviewer opens the PR.

    Avoid: anything that auto-merges, anything that posts directly to production-facing systems, anything that calls a paid API on every commit to a feature branch. The bill compounds quickly when CI fires Claude on every push to every developer branch. Gate the workflow on PR-target branches only, or on labels.

    Where Claude Code for Teams Loses Today

    The honest list:

    • No native role-based permissions inside a single repo. If you want a junior engineer’s Claude Code to be more restricted than a senior’s, you have to enforce it through settings.json and trust everyone to not edit it. The Enterprise plan adds SSO, SCIM, and audit logs at the workspace level, but inside the repo, Claude Code itself does not differentiate by role.
    • No first-class secret scanning before commits. Hooks can plug this gap, but you have to wire pre-commit yourself.
    • Shared MCP servers are still per-developer auth. A team-shared Linear or Jira MCP, for example, still requires each engineer to authenticate individually.

    The Team plan addresses workspace-level governance through Premium seats, which is the tier that actually unlocks Claude Code for teammates. The Enterprise plan layers on SSO, SCIM, and audit logs. Neither makes the in-repo configuration questions go away — those are still your team’s problem to solve.

    Model Selection Is a Team Decision

    This one matters more than people realize. Default everyone in .claude/settings.json to claude-sonnet-4-6 for day-to-day work, with claude-opus-4-7 available for explicitly hard tasks. The current Anthropic lineup as of this writing — flagship claude-opus-4-7, workhorse claude-sonnet-4-6, fast claude-haiku-4-5-20251001 — is documented at docs.anthropic.com/en/docs/about-claude/models, and the model strings change frequently enough that hard-coding them in scripts has bitten me twice this year. Read that page, do not memorize it.

    A team that defaults to flagship for everything and a team that defaults to workhorse with selective escalation will see meaningfully different invoices for substantially the same productivity. Make the choice consciously.

    The 20-Minute Setup

    Desk with laptop, checklist notebook, and billing card ready before creating an Anthropic API key
    The 20-minute team setup.

    If you are rolling Claude Code out to a team next week:

    1. Add .claude/settings.local.json to .gitignore. First commit, today.
    2. Write a focused CLAUDE.md covering review-blocking rules. Ship it short.
    3. Create one subagent in .claude/agents/ for the team’s most painful review task.
    4. Add a single GitHub Actions workflow that runs Claude Code on PRs in comment-only mode.
    5. Schedule a 30-minute team review of the CLAUDE.md every two weeks. Delete more than you add.

    That is it. Everything else is iteration. The teams that succeed with Claude Code treat the configuration as code — versioned, reviewed, and pruned. The teams that fail treat it as a personal productivity tool that happens to be in a shared repo.

    Decide which kind of team you want to be before the third engineer commits.

    📖 Recommended Reading in Claude Code Insider

    Related on Tygart Media: how to use Claude · Anthropic API key.

  • Cowork Routines: Scheduled Tasks & Windows Computer Use

    Cowork Routines: Scheduled Tasks & Windows Computer Use

    Last refreshed: May 15, 2026

    Two Cowork capabilities that haven’t been written about here yet, despite being live since late April: Cowork Routines (always-on scheduled tasks that run when your laptop is closed) and Windows computer use (Claude operating your Windows desktop directly from within Cowork). Both shipped in the April 28–30 window alongside the Claude GA release. Both materially change what Cowork is.

    Cowork Routines: The Laptop Can Be Closed

    Three stacked layers: chat UI, tools, agent runtime
    Cowork Routines — the laptop can be closed.

    The original Cowork model required your laptop to be open and the Cowork desktop app to be running. Useful — but bounded by your hardware being available and powered on. Cowork Routines changes that.

    Routines are cloud-hosted scheduled tasks that execute on Anthropic’s infrastructure regardless of your local hardware state. They run on a schedule you define. They execute when your laptop is off, sleeping, or in your bag on a plane. The task runs, the output lands where you configured it to land, and when you open the laptop you find the work done.

    The practical scope of what runs well as a Routine:

    • Daily briefings: Pull sources, synthesize, write to Notion or email — delivered before you open your laptop each morning
    • Monitoring tasks: Check a source on a schedule, flag anomalies, log findings
    • Content pipeline steps: Recurring publication tasks, social scheduling prep, site audit runs
    • Report generation: Weekly status documents assembled from live data sources
    • Notification triggers: Watch a condition, fire an action when it’s met

    We run our own Claude Newspaper Desk — a daily briefing that checks Anthropic’s news, release notes, GitHub releases, and external coverage, then writes a structured briefing to Notion before we start the day. That’s a Routine. The briefing that generated this article was produced by a Routine running on a schedule, not by someone manually triggering a task.

    The architectural decision that makes Routines significant: the task reads its instructions from a Notion desk spec page at runtime, not from a baked-in prompt. Change the Notion spec, change what the Routine does — without touching the scheduled task itself. The shim file that triggers the Routine is thin by design; the intelligence lives in Notion.

    Windows Computer Use: Claude Operates Your Desktop

    Four cards for content, ops, build, and knowledge work with Claude
    Windows computer use — Claude operates your desktop.

    Computer use in Claude — the ability for Claude to navigate desktop interfaces, click through UI, fill forms, and verify results — was previously available primarily in research preview and on macOS. The April 2026 Cowork release brought computer use to Windows as a generally available capability within the Cowork desktop app.

    What this means in practice: Claude can open a native Windows application, navigate its interface, perform a sequence of actions, and hand the result back — without you needing to automate it through code or build an API integration. If there’s a tool that only has a Windows UI and no API, Claude can use the Windows UI directly.

    The current state of computer use is honest about its scope. It’s good at:

    • Navigating well-structured desktop applications with clear UI hierarchies
    • Form completion across multiple-step workflows
    • Data extraction from desktop tools that don’t export well
    • Verification steps that require visual confirmation

    It’s slower than direct API integrations when those exist. For tools with APIs, use the API. Computer use is the path when no API exists or when the integration cost exceeds the value of doing it properly.

    The combination of Routines + Windows computer use means a scheduled task can now include a step that operates a Windows desktop application — unattended, while your laptop is running in the background. That’s a meaningfully different capability than what Cowork shipped with originally.

    How We’re Using Both

    Three panels showing one problem, three options, one recommendation
    How we’re using both.

    Our Cowork architecture as of May 2026:

    • Cowork as execution layer — always-on laptop running scheduled tasks
    • Notion as control plane — desk specs, task queues, logs, and credential storage
    • GCP Cloud Run as action layer — WordPress publishing, API calls, content pipeline steps
    • Claude Code Routines as cloud fallback — tasks that need to run independent of local hardware

    Routines handle the tasks where continuous availability matters more than local context: briefings, monitoring, scheduled publishing. Cowork handles the tasks where rich local context matters: multi-step sessions with file access, browser navigation, and tools that live on the local machine.

    The practical division: if the task needs to run at 3am when the laptop is sleeping, it’s a Routine. If the task needs to interact with local files, a browser session, or a Windows app, it’s Cowork.

    The Non-Developer Angle

    Neither of these capabilities requires you to be a developer to use. Routines are configured through the Cowork interface with natural language task descriptions and a schedule. Computer use activates through the same conversational interface you’re already using.

    The architecture underneath is sophisticated. The interface isn’t. You describe what you want done and when, and the system figures out the implementation. This is the progression that makes these capabilities meaningful for operations teams, executive assistants, knowledge workers, and small business owners — not just engineers building agent pipelines.

    Singapore’s Foreign Minister Balakrishnan built his own version of this on a Raspberry Pi. The point isn’t to build your own — it’s that the underlying architecture (persistent memory, scheduled tasks, multi-channel input) is now accessible at multiple layers of sophistication, from DIY open source to fully managed product.

    Related on Tygart Media: Claude Routines · Claude Cowork · Cowork task scheduling.

    Frequently Asked Questions

    What are Cowork Routines?

    Cowork Routines are cloud-hosted scheduled tasks that run on Anthropic’s infrastructure regardless of whether your local Cowork laptop is on or available. They execute on a schedule you define — daily, weekly, or at specific times — and can perform any task Cowork handles: briefings, monitoring, content pipeline steps, report generation, and notification triggers. Each Routine reads its instructions from a Notion desk spec at runtime.

    Does Windows computer use require coding to set up?

    No. Computer use in Cowork activates through the standard conversational interface. You describe what you want Claude to do in the application, and Claude navigates the Windows desktop UI directly. No scripting, automation code, or API integration is required — though API integrations are faster when they exist. Computer use is the path for tools with no accessible API.

    What’s the difference between Cowork and Cowork Routines?

    Cowork runs on your local machine and requires the desktop app to be open and active. Routines run on cloud infrastructure and execute regardless of local hardware state. The practical division: tasks that need to run unattended on a schedule go to Routines; tasks that need local context, file access, or desktop UI interaction go to Cowork. Both read task instructions from Notion desk spec pages at runtime.

    Is Cowork available on both Mac and Windows?

    Yes. Cowork and computer use are available on both macOS and Windows as of the April 2026 general availability release. The Windows release also established PowerShell as the default shell (previously Git Bash was required), reducing a friction point for enterprise Windows shops.

  • AI Message Drafting vs Human Presence in Hard Conversations

    AI Message Drafting vs Human Presence in Hard Conversations

    Twenty-eight pieces in, the system is getting very good at the briefing. It surfaces what hasn’t moved. It names the silence that has become meaningful, flags the relationship drifting toward cold, arms the escalation trigger with a date. It does all of this accurately — and the accuracy is the achievement.

    And then, somewhere in the hour after the briefing, there is a temptation that the previous pieces could not fully address.

    Should I draft the message first?

    In most cases, yes. This series has argued consistently that the briefing exists to reduce noise, that good preparation enables rather than substitutes, that an operator who shows up to a difficult conversation knowing the facts, the history, and the emotional terrain is better positioned than one who doesn’t. All of that holds.

    But there is a category of act where the draft is not preparation.

    It is displacement.

    What the Act Is Made Of

    The apology you drafted is not an apology. It is a document about an apology.

    This sounds harsher than it is. The words can be sincere. The feeling behind them can be real. The draft can be good — articulate, appropriately calibrated, warm in all the right places. And the person receiving it will feel something. But what they feel is not quite what they needed to feel, and the gap between those two things is what this piece is about.

    Because what the difficult call actually communicates is not the words. It is the quality of presence behind them. The person on the other end is reading for something beneath the surface — not the content of the message but the evidence that you showed up without a net. That you accepted exposure. That you thought of them enough to call before you knew what you were going to say.

    A good draft can’t give you that. It gives you something better: control. And control is exactly what the act cannot survive.

    The person receiving the message — the one at the edge of the relationship, where the repair needed to happen — cannot always name what they are reading for. They may not consciously register the difference. But the relationship registers it. The contact that needed to happen at the level of presence happened instead at the level of composition, and the gap remains. Now decorated with good sentences.

    The Fault Line Is Specific

    This is not an argument against using the system to prepare. It is an argument about where preparation ends and contamination begins.

    On one side of the line: the briefing. The context. The last date of contact and what was left unresolved. The health score and the silence trajectory. The facts, organized. The emotional terrain, mapped. All of this is good engineering. It removes the friction that has nothing to do with the difficulty of the call — the noise of not knowing the basics, the distraction of uncertainty about what happened — and it leaves you free to be present for the part that matters.

    On the other side of the line: the words. The draft. The crafted opening, the structured arc, the polished close. This is where preparation crosses from reducing noise to removing the signal itself.

    The signal is the property of the unrehearsed. What reaches the other party — what moves through the call and lands — is evidence that someone with skin in the game showed up with it exposed. Not managed. Not processed. Exposed.

    The deeper irony: a very good draft sounds natural. Natural is the precise property that cannot be manufactured, because it is the residue of genuine presence, not of craft. The better the draft simulates natural, the more completely it substitutes for the thing it was meant to support. You have now produced a performance of the call. The other person receives a performance. They know. Not always consciously. But they know.

    The Pressure-Release Problem

    What the system provides, when you ask it to draft the hard message, is a pressure-release valve.

    The pressure is real. The briefing surfaced something that needs to move. The operator’s nervous system knows it. There is a genuine desire to do something about it. Requesting a draft from the system feels like a move toward the thing. It produces a deliverable.

    But the deliverable is a substitute. The pressure releases without the contact happening. The operator has moved around the hard thing while carrying the artifact of having moved toward it. The gap — the relationship that needed a phone call — is still there. Now it has a draft parked next to it.

    This is what “work where doing is the point” looks like in the residual queue. Not the obvious cases — the scheduling, the summarizing, the research. The dangerous case is when the intelligence layer has correctly identified that a specific person needs a specific kind of presence from the operator, and the operator, rather than providing that presence, asks the system to approximate it.

    The system can approximate almost everything about the conversation except the part that makes it a conversation rather than a performance.

    Article 9 in this series argued that AI cannot have skin in the game — that judgment and relationships are the durable human advantages. What this piece is adding is the specific failure mode: not just that the AI lacks skin in the game, but that asking the AI to draft the act allows the human to lack it too, while appearing not to. It is a way of having skin in the game while keeping it covered. The brief exposure of authoring the draft, followed by the transmission of the draft, produces the sensation of having done the hard thing. The hard thing is still undone.

    Where to Draw the Line

    Everything up to the words is good engineering.

    Know the context. Know the history. Know what the relationship has cost and what it is worth. Let the briefing do its job fully — the facts, the silence trajectory, the emotional background. Arrive prepared in every way except one, and be deliberately unprepared in that one. Not as an oversight. As a discipline.

    The words are yours. Not because the system couldn’t generate better ones — it probably could — but because the words being yours is part of what is being communicated. The exposure is the content. The willingness to say something that might land badly, to be present without a script, to show up as someone who thought about this enough to call before they knew what they were going to say — that is the act the briefing was built to make possible.

    Not to replace.

    The system is very good at preparing you for the call. The test of whether you understand what it built is whether you put down the draft at the moment the call actually begins.

    There is a seam between the briefing and the act. Most of the work in the residual queue lives there. The briefing ends. The act starts. These are adjacent and distinct, and mistaking one for the other — using the scaffolding all the way up to and through the moment of contact — is the specific way a very capable system teaches a very capable operator to be slightly less present than they were before they built it.

    The call is available in the hour after the briefing, before the draft. It will not wait indefinitely for a better version of itself to be prepared.

    Related on Tygart Media: text-mediated trust · AI operator’s stack · follow-up cadence.

  • Error Handling and Fallbacks in Notion AI Workflows

    Error Handling and Fallbacks in Notion AI Workflows

    Related on Tygart Media: multi-agent orchestration · Notion AI vs Zapier AI.

    The 60-second version

    The default failure mode of a Notion agent is “stop.” That’s almost never what you want in production. Robust workflows define what happens for each kind of failure: agent times out, Worker fails, external API is down, the schema mismatched, the credit pool emptied. Each needs a planned response — retry, fall back to manual, escalate to human, log and continue. Without explicit handling, “the agent stopped working” becomes a mystery debug session.

    Five failure modes and their handling

    Seven cards naming common AI chatbot failure modes
    Five failure modes and their handling.

    1. Agent timeout (rare but exists). A 20-minute Custom Agent run that doesn’t complete. Handling: log the timeout, surface to the human owner, don’t auto-retry (likely to repeat the same problem).
    2. Worker timeout (more common). Worker hits 30-second limit. Handling: structured error return from the Worker; agent decides whether to retry, partial-result, or fail. Don’t silently re-invoke.
    3. External API failure. API down, rate limited, or returning errors. Handling: retry with exponential backoff (max 3 attempts), then fall back to “external system unavailable” path with human notification.
    4. Schema mismatch. Agent expected JSON shape A, Worker returned shape B. Handling: validate at the boundary, log the mismatch, fall back to a default response, alert human to fix the schema drift.
    5. Credit exhaustion. Workspace credit pool hits zero (post-May 4). Handling: this is hard — the agent stops mid-execution. Mitigation is preventative: monitor credit consumption, alert at 75% of monthly budget, top up before zero.

    Three practical patterns

    Three panels showing one problem, three options, one recommendation
    Three practical patterns.

    The retry-with-backoff pattern.
    First attempt fails → wait 1 second, retry. Second fails → wait 4 seconds, retry. Third fails → escalate to human. Don’t retry indefinitely.
    The fallback-output pattern.
    When the primary path fails, return a known-safe default with metadata indicating it’s a fallback. Downstream consumers can check the metadata and decide whether to use the fallback or alert.
    The human-escalation pattern.
    Define clear handoff criteria. When the agent can’t complete, who gets pinged, with what context, in what channel? “Pings someone eventually” is not a plan.

    Logging requirements

    Five security domains: identity, data, code governance, audit, agents
    Logging requirements.

    Production agent workflows need three log streams:
    – Action log: what the agent did and when
    – Error log: what failed, with enough context to diagnose
    – Decision log: when the agent chose between options, what it chose and why
    Without all three, debugging takes 10x longer than it should.

    Where this goes wrong

    1. Trusting the default failure behavior. “The agent stopped” is rarely the right response. Define explicit handling.
    2. Silent retries. Retries that don’t log produce mysterious “sometimes it works” behavior. Always log retry attempts.
    3. No credit monitoring. Hitting credit zero stops every agent in the workspace. Monitor consumption proactively.

    What to read next

    Workers in TypeScript, Multi-Agent Orchestration, Security Posture, ROI Math.

  • Multi-Agent Orchestration in Notion: When One Agent Hands Off to Another

    Multi-Agent Orchestration in Notion: When One Agent Hands Off to Another

    Related on Tygart Media: AI orchestration tools · first Notion skill.

    The 60-second version

    Single mega-agents are tempting and bad. Specialized agents in a sequence with clear handoffs are harder to design but much more reliable. The principle: each agent does one thing well and hands a structured result to the next. Three handoffs is about the practical limit before debugging becomes painful. Beyond three, refactor.

    Three orchestration patterns that work

    Four-step loop: observe, remember, act, update for managed agents
    Three orchestration patterns that work.

    1. The pipeline pattern.
    Agent A produces structured output → Agent B consumes and produces → Agent C consumes and produces final result. Each agent’s output schema matches the next agent’s input schema. Clear linear flow.
    2. The router pattern.
    A routing agent decides which specialist agent should handle the request, then dispatches. Specialists are scoped tightly to their domain. The router doesn’t do work itself; it just routes.
    3. The reviewer pattern.
    A producer agent generates output. A reviewer agent checks against criteria and either approves or returns specific feedback. Iterates until approved or max-attempts hit.

    Three patterns that fail

    Seven cards naming common AI chatbot failure modes
    Three patterns that fail.

    1. Recursive agent chains. Agent A calls Agent B which calls Agent A again. Debugging is awful. Don’t.
    2. Shared mutable state. Two agents writing to the same database row simultaneously. Race conditions and overwrites. Don’t.
    3. Implicit handoffs. Agent A produces unstructured text; Agent B parses it. The first format change breaks everything. Use structured handoffs.

    Designing the handoff contract

    Desk with laptop, checklist notebook, and billing card ready before creating an Anthropic API key
    Designing the handoff contract.

    The handoff between agents is the highest-risk surface. Three rules:
    – Define the schema explicitly. The output of Agent A is JSON-schema-validated input to Agent B.
    – Version the schema. Schema changes are breaking changes. Version like APIs.
    – Test the handoff in isolation. Mock Agent A’s output; test Agent B’s handling. Mock Agent B’s expected input; test Agent A’s production.

    Where orchestration goes wrong in production

    1. Cost compounds with depth. Each agent call consumes credits. A three-handoff workflow costs roughly 3x a single-agent workflow. Budget accordingly.
    2. Latency compounds too. A 5-second agent x 3 handoffs is 15 seconds end-to-end.
    3. Failure modes multiply. Agent A succeeds, Agent B fails, what happens? Define the failure handling explicitly.

    What to read next

    Workers for Agents in TypeScript, Building Your First Skill, Error Handling in Notion AI Workflows, Custom Agents vs Basic.

  • Workers for Agents in TypeScript: Patterns That Hold Up in Production

    Workers for Agents in TypeScript: Patterns That Hold Up in Production

    Related on Tygart Media: first Notion skill · Cursor command center.

    The 60-second version

    Workers reward a specific style of TypeScript: small, single-purpose, structured-input-and-output, well-typed. The constraints (30 seconds, 128MB, no state) push you toward this style automatically. Workers that hold up in production share patterns: typed input/output schemas, defensive HTTP calls with timeouts, structured error returns, no hidden side effects.

    Five production patterns

    Three stacked layers: chat UI, tools, agent runtime
    Five production patterns for Workers.

    1. Type your input and output.
    Type strictly. The agent works against the schema. Schema drift breaks the agent silently.
    2. Defensive HTTP with timeouts.
    External API calls inside a 30-second budget need their own timeouts. A 25-second API call leaves 5 seconds for everything else. Set explicit fetch timeouts shorter than the Worker timeout.
    3. Structured error returns instead of throws.
    Throw inside a Worker and the agent gets opaque failure. Return structured error objects and the agent can reason about the failure and respond gracefully.
    4. Idempotency where state matters.
    Workers have no persistent state, but they can hit external systems that do. If the external call is non-idempotent (e.g., creates a record), include an idempotency key derived from input. Calling the Worker twice should produce one record, not two.
    5. Approved domains as a deployment artifact.
    Track domain approvals in code. When a Worker stops working in production, “did the approved domains change” is the first thing to check.

    Three production failures to design around

    Seven cards naming common AI chatbot failure modes
    Three production failures to design around.

    1. The 30-second wall. Aim for under 5 seconds typical, under 15 worst case. Long calls fail under retry loads.
    2. Silent domain blocks. A Worker calling a non-approved domain fails with an error that isn’t always obvious. Log every outbound destination.
    3. Memory leaks via large responses. Don’t pull a 50MB JSON response into a 128MB Worker. Stream, paginate, or pre-filter at the source.

    Testing strategy

    Desk with laptop, checklist notebook, and billing card ready before creating an Anthropic API key
    Testing strategy.

    Unit-test the Worker logic separately from the agent. Use mock HTTP. Then integration-test with the actual agent calling the Worker. The two test layers catch different bugs.

    What to read next

    Workers + External APIs, Notion AI Meets MCP, Workers for Agents foundation piece, Security Posture.

  • Notion Agents vs n8n Alone: When the Workflow Belongs Inside Notion

    Notion Agents vs n8n Alone: When the Workflow Belongs Inside Notion

    Related on Tygart Media: vs Zapier AI · multi-agent orchestration · Notion Command Center.

    The 60-second version

    This isn’t either-or. n8n is the deterministic workflow engine — when X happens, do Y across these 5 apps. Notion Agents are the reasoning layer — given the context, decide whether X actually warrants action and what the right action is. Combined via the n8n MCP bridge, they form a complete automation stack: agent reasons, n8n executes. Operators who treat them as competitors miss the leverage.

    When Notion Agents win

    Three stacked layers: chat UI, tools, agent runtime
    When Notion Agents win.
    • The workflow needs to read and synthesize Notion workspace content
    • Natural-language understanding of context matters
    • The “decide whether to act” question is the hard part
    • Schedule-driven autonomous work is the goal
    • The workflow output is itself in Notion

    When n8n wins

    Side-by-side when to use a script versus an agent
    When n8n wins.
    • Pure cross-app data movement (no reasoning needed)
    • Hundreds of integration options matter
    • Visual workflow building with branching logic
    • High-volume deterministic automations
    • Workflows that don’t touch Notion at all

    The combined pattern

    Three panels showing one problem, three options, one recommendation
    The combined pattern.

    The pattern that’s emerging:
    – Notion Agent decides what to do based on context
    – n8n workflow executes the cross-app coordination
    – Connected via the n8n MCP bridge inside Notion
    Example: Agent reads new lead in Notion → reasons whether it matches ICP → if yes, calls n8n workflow that updates Salesforce, sends Slack notification, schedules follow-up email.

    What n8n does that Notion Agents don’t

    • Massive integration catalog (Salesforce, Stripe, hundreds of others)
    • Visual flow building
    • High-throughput deterministic execution
    • Self-hosting option for compliance-sensitive use cases

    What Notion Agents do that n8n doesn’t

    • Natural-language understanding of unstructured workspace content
    • Native Notion database manipulation
    • Skills (saved natural-language workflows)
    • Workers for custom code execution
    • Schedule-driven autonomous reasoning

    Where this goes wrong

    1. Trying to do everything in one tool. Reasoning in n8n (limited) or deterministic execution in Notion Agents (expensive) is the wrong direction.
    2. Skipping the MCP bridge. Without it, you re-implement n8n integrations as Workers. Don’t.
    3. Letting agent reasoning replace simple n8n triggers. If the trigger is “row added to database,” that’s deterministic. Just use n8n.

    What to read next

    n8n MCP Bridge, Workers + External APIs, Notion AI vs Zapier, MCP foundation piece.