Claude Code continues to amaze me with its fast and furious updates. At the same time, though, its lacks certain basic capabilities we've come to expect from contemporary software. Case in point: a proper /restart command.

As long as I've been a fanboy, I've had to use the /exit command. In Terminal, I'd then type /claude to install updates and effect changes to my config.json file.

Not anymore.

A Simple Restart Command

As of today, I restart Claude Code by via a Raycast hotkey. As you can see below, I use ⇪ + R, but you can easily roll your own.

Technically, you don't need Raycast to run the script.

Since everyone should be able to restart Claude Code with a single command, I'm making the code available via GitHub.

Geek on.

In a recent post, I discussed the ever-expanding array of tools available to proper developers and their citizen counterparts. Today, I'll cover why it's imperative to understand the pros and cons of each tool.

Automating Notion Product Updates

A while back, I had built a Notion custom agent that sent the company's product releases to a simple database. (I refuse to check Twitter/X for its latest capabilities and changes.) As usual, I gave my new automated friend a playful and phonetic name.

Norm the Notion Product Update Tracker ran daily, but its token cost was considerable. (See the message in blue in the visual above.)

Rethinking My Custom Agent

I knew that there had to be better (read: cheaper) way to accomplish the same goal. In maybe 15 minutes, Claude Code helped me create a simple launchd job that replaced the Notion custom agent.

At the beginning of this year, I began my Claude Code journey in earnest. Since that time, I've used Anthropic's powerful new AI tool in more ways than I can count.

Sessions with my bestie have run the gamut. A few recent examples include:

1. Automating formerly manual processes for myself and clients.
2. Noodling with Notion Workers and MCPs.
3. Developing a new lead-gen tool based on my last four books.
4. Migrating a friend's website from Wix to easier for her to use, not to mention cheaper.
5. Creating more than 50 GitHub repos, including this cool Apple Health visualizer.

Note that I'm currently on the Pro plan.

Looking at the Data

I suspected that I initiated at least a thousand sessions and used millions of tokens during that time. I wasn't wrong.

Here's a breakdown:

Initial Thoughts

First up, I find it fascinating that I used ten times as many tokens per month from April to June as I did early on. I would have suspected a more gradual incline. As for consistency, I do monitor my token usage to avoid incurring outrageous bills.

Developers' toolboxes have never been more robust

Second, Phoenix in July is hot AF. Third, although I regularly use tokens, in some cases I'll opt for creating an API key. As I wrote recently, developers' toolboxes have never been more robust.

The Weekly Rhythm

I knew that I interacted with Claude Code far less during the weekend. Great, but how significant was the dropoff?

Not surprisingly, my Claude Code usage strongly correlates with my increased GitHub activity.

Feedback

How are you using today's AI tools? Does the actual data match your suspicions?

How many organizations and teams use both Slack and Notion?

Given the popularity of each tool, I'd bet that the number is in the hundreds of thousands. Yes, the two apps overlap to a degree, but they fundamentally do different things. Unleashing the full power of both requires two separate and recurring software licenses. Such is life in the SaaS world.

The Limitations of Slack's Free Plan

The no-cost tier packs some powerful functionality, but it also constrains users in considerable ways. Most germane here, workspace members can only access the most recent 90 days of message and file history. (For more information on Slack's message retention policy, click here.)

This restriction is anything but a minor inconvenience that annoys a few power users. On the contrary, the vast majority of the roughly 10 million Slack users pay bupkus. (It's not even close, and I suspect that Marc Benioff would love a Mulligan on Salesforce's $27.7B acquisition of the company in 2020.)

If you're currently stuck on Slack's Free plan, your options around old messages and files have traditionally included:

1. Lobbying your management to upgrade.
2. Footing the bill yourself under the radar—aka shadow IT.
3. Getting your IT department to create a fancy export routine.
4. Accepting that limitation.
5. Eschewing Slack altogether and using a minimalist Notion message board. (Here's my affordable template that does exactly that.)

In a word, eh.

Today I'm adding a new option to that list.

A New Alternative

My latest creation is the Public Channel Summarizer. It's a custom Slack app for budget-conscious organizations and teams that want to do all the following:

1. Remain on Slack's Free plan.
2. Preserve their valuable institutional knowledge in Slack in public channels.
3. Easily and permanently access that essential information in a Notion database.

Distribution

The PCS app is a fun side project—not a source of potential future revenue. (I lack any desire to set up a dedicated support URL.) As such, you won't find it in the Slack App Directory. Rather, I'm open-sourcing it on GitHub.

Do with it what you wish. If you want to rename it, restrict its channels, or change its settings, have at it.

Using the App

Once you set the PCS up, you'll see it in your workspace app directory:

Click on the PCS app to view more information about it, just as you would any with other Slack creation:

Once you've finished setting up the app for your workspace, invoke it by running the bespoke Slack command /summarize:

Hit Enter and the magic begins.

A few minutes later, voilà! The entry exists in a Notion database:

Open up the recap and you see the detail:

Speaking of Notion, you'll notice a new Worker in your workspace:

A Quick Note on Billing

Notion Workers don't volunteer their services. Putting them to work requires purchasing Notion credits. The actual number hinges on how frequently you use the app and the amount of dialogue in your public Slack channels. In other words, the PCS app means that you'll continue to pay Salesforce nothing. You will incur, however, extra Notion fees.

Simon Says

Odds are you haven't unlocked the true power of Notion. What are you waiting for?

If there is a spectrum of software, the Claude Codes of the world sit at the exciting end of it. By contrast, one would never use that term to describe an enterprise resource planning systems. It's not all about sexy, though. Good luck running a firm without reliable payroll, benefits, accounts receivable, and accounts payable applications.

I know more about ERP systems than most. For more than a decade, I made my bones as an enterprise systems consultant. New back-office systems don't implement themselves. As I write in Why New Systems Fail, organizations have always needed seasoned folks to do for this critical job. Great, but which individuals?

Independents usually possess deep domain knowledge, but CXOs tended to view them as risky because the certification game remains alive and well. As the old maxim goes, “Nobody ever got fired for hiring IBM.” A partner's letterhead provided cover in case things broke bad.

And they often did.

My ERP days are long behind me, but not much has really changed.
These implementations are still massive in scope. Expect multi-million dollar engagements, year-plus timelines, and large teams. (Ditto for delays and organizational politics.) No single person—no matter how accomplished, versatile, or intelligent—could independently handle a gig of any consequence.

The Increasing Viability of the Solo Practitioner

For the last few years, Notion has been the focus of my development efforts. The popular, incredibly powerful tool has evolved considerably since I began using it in 2020. Foolish is the soul who views it as a note-taking app.

Make no mistake, though: the most daunting Notion project is far less complicated, time-consuming, and expensive than the simplest ERP implementation. Apples and coconuts. As a result, in the Notion universe, engaging a solo developer or consultant is far more common than in its ERP equivalent. Here are five reasons that firms in need of Notion expertise may prefer to engage a skilled and knowledgeable independent over a dedicated agency.

Steve Jobs, AI, and the 100X Quote

You may have heard the old Steve Jobs' quote, “The difference between the average software developer and the best is 50 to one; maybe even 100 to one.” Whether that statement has ever held water is anyone's guess, but the following facts are indisputable:

• Not all consultants and developers are created equal.
• Rock stars who have mastered AI and other automation tools are considerably more productive than those who are still dipping their toes in the water.

Brass tacks: significant constraints always limited what even the most talented individuals could realistically accomplish. Those boundaries haven't entirely disappeared, buy they have certainly eroded in the last few years.

Streamlined Sales Process

Working with me is straightforward. I can't envision a simpler process.

Even a three-person team can confuse who is supposed to do what when.

That's not to say, though, that bottlenecks don't occasionally emerge. A great deal hinges upon the organization hiring me. Some have pulled the trigger immediately after our discovery call. Others have dragged out the process for months.

No Box of Chocolates

My clients know that if they hire me then they'll get me. That is, I'll be the one asking the questions, gathering the requirements, explaining Notion's inner workings, building the databases, recording training videos, and setting up the workspace automations. Put differently, they won't get:

• A consultancy's B- or even C-team.
• A blended group of junior developers or consultants effectively learning from their senior counterparts while on the client's dime.
• The next available consultant or, if you like, whoever happens to currently be on the beach. (Cue obligatory Forrest Gump quote.)

I've seen all of these scenarios play out first hand. Things get ugly quickly.

Direct Communication

Even at boutique firms, different layers and communication styles can complicate effective collaboration. Issues can arise when:

• A person forgets to CC someone else on an email.
• Someone fails to follow protocol.
• A key team member goes on vacation and forgets to set her email auto-responder or Slack status.
• Person X suddenly exits the organization. Critical organizational knowledge leaves as well—permanently.

In my experience, the more people involved in a project, the more problematic the communication and the greater the chance for misunderstandings.

Unequivocal Accountability

All else being equal, there's far less finger-pointing and a more intense CYA mindset at smaller firms than at larger ones. I've worked for both. It's not even close.

Don't conflate less with none, though. Even a three-person team can confuse who is supposed to do what when.

Feedback

Do recent AI advances make you think differently about hiring an expert vs. a small team?

Since I began using Notion six years ago, it has morphed in ways that no one could have ever imagined. (Such is the case with no-code tools.)

These days, I'm particularly excited about Notion Workers—specifically, their ability to sync data from third-party systems. After noodling with them for the last month, I've started to implement them for myself and my clients.

In today's post, I'll explain how I replaced an effective but relatively expensive automation with a simpler, far cheaper one.

Early Automation Efforts

By way of background, I've used Notion as my CRM for years. When someone fills out the contact form on my site, Notion automatically generates a new prospect/client record in my CRM01 database. If the inquiry is legitimate, then I emailed the person a scheduling link. When that individual booked time with me via Calendly, a little automation magic:

• Matched the existing CRM01 record (via email address).
• Created a new meeting record in the related CRM02 database. (After our call, I'd post the Zoom meeting in that new CRM02 entry and the NotionAI meeting transcriptions. In total, there would be CRM02 entry per client or prospect per meeting.)

The automated matching process worked, but it was neither terribly elegant nor cost-efficient. In its most recent incarnation, I routinely fired a Notion custom agent to see if any new client or prospect meetings appeared in my Google Calendar. If the answer was yes, then the agent created a new CRM02 record and notified me.

Brass tacks: Over the last few months, I wasted plenty of tokens. Still, it was the best I could do under the circumstances.

Changes and Savings

Not too long ago, I made two significant changes. First, I ditched Calendly for TidyCal. Second, I began using Apple Calendar in lieu of Google's equivalent.

These shifts made me ask a fundamental question: Can I improve my own internal process? Thanks to Notion Workers, I could and did.

What else can I automate?

I created a TidyCal API key and went to work with the Notion CLI and Claude Code. In no time, I had spun up a new Notion Worker and database that pulls all my TidyCal bookings. A few fancy automations do the same matching for me and alert me of new CRM02 records.

Even better, I can view and edit those meetings right from client and prospect CRM01 database records:

I suspect that I reduced my supplemental Notion charges from this automation by roughly 90 percent. What's more, the new, far smoother process effectively nullifies Notion's über annoying Apple Calendar bug. Everybody wins.

Simon Says

There are more ways than ever to automate manual processes. In the Notion world alone, adroit developers can access:

1. Integrations.
2. Custom agents.
3. API calls.
4. MCPs.
5. Webhooks.
6. Native automations.
7. Zapier, Make.com, and other third-party tools.

Collectively, the Notion developer's toolbox has never packed more power. Of course, some methods are better and less expensive than others.

The broader lesson: Just because you've already automated a business process doesn't mean that you can't do better.

For years, I struggled to find cleaning supplies in my kitchen's utility closet. As a result, I'd sometimes buy duplicate products. "I could have sworn I recently bought Magic Erasers," I'd say to myself when rummaging through cluttered shelves. Random bags and plastic cups were everywhere. A proper system this was not.

In April, the situation reached a tipping point. I recently decided to do something about it. My bestie Claude didn't disagree:

See for yourself:

Challenge accepted.

The Big Cleanup

Over the course of a weekend, I removed everything from the closet. I cleaned the shelves and laid down some black shelf liner in case of future leaks or spills. Logical sections began replacing the utter chaos I had created. I picked up some industrial sprayers and refill bottles. Finally, I installed some under-shelf rechargeable lights. Why not go the full nine?

Night and day.

Here's a photo of a newly organized closet shelf. Let's just say that it looks nothing like its predecessor.

Now I can easily locate Formula 409, granite cleaner, and whatever else I need. Why I didn't undertake this project years ago mystifies me.

A Workplace Parallel

I suspect that many small business owners, CXOs, team leads, and department heads can relate to my little yarn. They routinely struggle to find key information. Teammates sloppily enter duplicate records in systems because they can't find what they need. Automated reporting is a pipe dream. Answering simple questions takes way too much time and effort. They pay for tech they don't use—at least as much as they could.

You get my drift.

If you want some help cleaning your tech closet, let's talk.

In the course of my 30 years around workplace tech, I've learned a thing or six. I've seen more times than I can count how people, teams, departments, and organizations use and misuse systems. Most of my books address the subject in one way or another—especially my four-part series on the future of work.

Full-length, well-written texts have impacted my life in profound ways. Many of them taught me new skills, frameworks, and ways to become more effective. It's no overstatement that, without books, I would be a much different, less informed, and less productive person.

At the same time, though, even the best books aren't panaceas. They're static, decidedly non-interactive artifacts. Thanks to the rise of generative AI, however, that limitation is eroding.

Drumroll…

Today I'm pleased to announce the beta launch of the Simon Workplace Tech Assessment. The SWTA is a relatively short questionnaire that analyzes how your team, department, or organization uses them in working together.

After I qualify the respondent, I'll generate and send you a specific, 700-ish-word assessment based upon my four-part series on the future of work:

1. Reimagining Collaboration: Slack, Microsoft Teams, Zoom, and the Post-COVID World of Work.
2. Project Management in the Hybrid Workplace.
3. Low-Code/No-Code: Citizen Developers and the Surprising Future of Business Applications.
4. The Nine: The Tectonic Forces Reshaping the Workplace.

The STWA offers bespoke advice from a deep corpus of knowledge—more than 1,100 pages on workplace tech, collaboration, organizational change, cultural issues, and the future of work.

It's launching today in beta.

In 2013, I attended a small business networking event in Las Vegas. A major marketing and tech vendor footed the bill for the shindig. More specifically, that company offered website maintenance, hosting, support, SEO, newsletter management, and other number of turnkey services. Additional options included occasional blogging.

After the Vendor X's salespeople gave their spiel, I spoke with a number of clients at my table. Eventually, the conversation turned to price. The recurring fee astounded me. Some of these companies paid $3,500 to $5,000 per month for these services.

Huh?

I shook my head in disbelief. The restaurateurs, lawyers, and other small-biz owners in attendance certainly knew their trades, but they lacked anything resembling expertise in contemporary tech. Vendor X's websites were largely cookie-cutter. They provided basic e-commerce functionality—a tough ask in 1996, but not in 2013. Even premium hosting had become affordable by that point. I'd bet my life that the vendor's profit margins were more Apple than Amazon.

Pay these vendors' monthly fees if you like, but the game has changed.

Nice work if you can get it. At least it pays for complementary sandwiches.

The More Things Change …

Fast-forward 13 years. Some turnkey outfits continue to make a killing off of their unsuspecting clients.

Case in point: I spoke with a friend of mine recently about this very subject. One vendor charged him $700 per month to do the following:

1. Publish AI-assisted blog posts.
2. Route them to his two WordPress sites.

I floored him when I mentioned that I could build a Notion-based tool for him that would save him at least $5,000 per year. In a way, not much has changed since my book The New Small dropped in 2010.

Simon Says: Open your mind.

Building bespoke systems used to be prohibitively difficult and expensive. For this reason, millions of small businesses overpaid for the very applications and services I just described. No doubt that many (even most) of these companies will continue doing so. Make no mistake, though: the game has changed. Thank the explosion of AI and no-code and low-code tools.

Pay these vendors' fees if you like. I can't stop you. I'm betting, though, that there's a much cheaper mousetrap out there for you if you open your mind.

For my entire career, workplace tech and collaboration have fascinated me. I suspect that my interest in these topics will never wane. Invariably at the gym, I catch a glimpse of people furiously pecking away at their keyboards. What applications are they using? Would any of them benefit my clients or me?

A Perplexing Mix

In a Slack workspace, I recently saw someone post a message in an AI channel on his use of Claude. I immediately knew that this individual:

1. Understood the power of generative AI and Claude in particular. (In that way, we're alike.)
2. Knew at least the rudiments of Slack—a noisy, often confusing morass of information.

Cool, I thought. This individual and I shared some common tech sensibilities. And four seconds later, I also knew that some pretty stark differences existed as well. From his post:

Wow.

You can use any software program in unconventional ways.

Person X copied the Claude session and pasted it into a Microsoft Word document.

How I Think About Collaboration

I'm not judging, but I would have shared my Claude chat in one of the following ways:

1. Making the Claude session public.
2. Blogging about it on my website. Think web, as I used to say.
3. Using Google Docs, Notion, or another contemporary collaboration tool.

If none of these options existed, I would have vibe-coded my own solution. Put differently, I'd never consider relying on a 43-year-old program best suited for manuscripts, reports, and their ilk.

Simon Says

Can you share Claude sessions via Word, Excel, or another tried-and-true application? Sure. You can use any software program in unconventional ways. A few examples:

• Some people have emailed me 40 MB attachments instead of using iCloud, Dropbox, OneDrive, Google Drive, or WeTransfer.
• Plenty of self-published authors use Word to "design" their books. The final products look decidedly amateur.
• It's downright silly to store reams of structured data in a PowerPoint file, but I've seen people do it. Hell, these days you might even be able to analyze it with Claude.

There's a chasm, though, between can and should.

Feedback

Which old stalwarts do you continue to use? Which ones do you use in, er, creative ways?

During the aughts, I paid my bills as an enterprise systems consultant. The projects varied, but my colleagues and I largely needed to be on site Monday through Thursday. Fridays were typically admin days. That is, we submitted our weekly expenses, sent our PMs status reports, participated in conference calls, and the like.

For consultants, recapping weekly activities has always been a necessary evil. We needed to justify our rates. Consulting engagement managers, client bean counters, project managers, and internal auditors don't like being kept in the dark. The tedious manual process traditionally took my peers anywhere from 15 to 30 minutes. I usually shaved about 50 percent off that number by starting from an existing template and updating it throughout the week.

Is There a Better Way?

What if you could automate that entire process? Even ten years ago, the answer to that question would have been a hard no. Today, it's easier than ever and, best of all, requires zero coding knowledge.

Last week, I built a simple Notion custom agent via the following prompt:

As I do with all of my Notion custom agents, I gave it a clever, phonetic name:

And voilà!

Results and Going Down the Rabbit Role

I'm now able to access a simple log of all of the Notion-related work I've performed the past seven days. (Oh, the power of metadata.) I suspect that I'll be able to learn a great deal about how I use Notion—and how I can improve in the future. A neat launchd job on my Mac sends my daily results to a separate Notion database. And, of course, I back up all of my code on GitHub.

I've created the same automation for my bestie Claude.

And why not toss in a simple but effective graph?

Finally, for good measure, I added a simple AI summary of the day's activities for easy viewing:

If you only consider Notion a note-taking app, you're really missing out.

Simon Says

No, you can't automate everything. At the same time, it's downright silly to stick with manual processes out of habit or laziness. Once one domino falls, you may be surprised with what you eventually create.

Feedback

What have you automated lately?

About a month ago, I wrote about how I used my bestie Claude Code to replace one automation solution with another. As it turned out, the fix turned out to be a Band-Aid. (Cue Craig Bruce quote.)

In today's post, I'll explain:

1. How I permanently automated posting to LinkedIn while abiding by its terms of service.
2. The lesson citizen developers can learn from my travails.

Let's light this candle.

Background

I had successfully automated sending my posts from this site and Racket Publishing to my LinkedIn profile and each entity's corresponding page. Claude Code helped me build a Python script that invoked Playwright—the powerful browser automation library. That promising solution, however, proved ephemeral.¹ LinkedIn's justifiable anti-bot detection methods thwarted my initial approach. I suspected that I was chasing my tail here, and Claude Code confirmed as much.

What to do? Would I have to revert to manually posting?

Most industry types knew that GitHub had become a big deal since its inception. I, for one, didn't realize how big until June 4, 2018. On that day, Microsoft dropped a cool $7.5 billion for the world's largest code repository. The acquisition turned out far better than the Nokia one did.

Over the years, I had dipped one foot in the GitHub pool. As a college professor, I had pushed some straightforward Python examples in a public repo for my students.

#say_my_name. 
counter = 1 #this is the counter that I metnioned before
guess = input("Say my name. ")
name = "Heisenberg"
while (guess != name):
    guess = input("Try again. ")
    counter = counter + 1 
if counter == 1: #note the double == here.
    print("\nYou are *!##%! right.", "It took you", counter, "try.")
elif counter in [2, 3, 4, 5]:
    print("\nYou are *!##%! right.", "It took you", counter, "tries.")
else: 
    print("\n\tSeriously? You don't watch this show at all.")

Still, no one would call me a power user. It's not like I committed code every week or every month.

Until suddenly I did.

In this post, I'll explain why.

Claude Code Got This Whole Train Rolling

Since going all in on Claude, I've been a busy little GitHub bee. Looking at my recent contributions confirms as much:

It didn't take that long to automate simple manual processes such as this one. Some of the more sophisticated ones, though, required cron jobs. Fortunately, GitHub actions fit the bill perfectly. No more backing up Ghost posts and pages in Notion. Claude Code helped me see the light and create a neat Apple Health interactive dashboard. Have at it on GitHub.

What Else Can I Replace?

Claude Code has awakened my inner open-source beast. Lately, I've been a bit of a demon finding free alternatives to paid SaaS staples. Case in point: my document signing needs are casual. A paid Docusign subscription never made sense. Dropbox Sign works, but the company's incessant attempts to upsell me leave me annoyed.

Claude Code has awakened the open-source beast.

Enter Documenso.

You're welcome.

The Claude Code-GitHub combo has also proved invaluable in other ways. My efforts to combat spam and add advanced automations to Notion databases come to mind.

Simon Says

Finding effective replacements—and creating new ones—is downright addicting. I suspect that many citizen developers feel the same way.

Feedback

What new tools have you adopted in the past year?

Sometimes people can't immediately size me up, and I can't blame them. After all, I wear a few different hats. That's not to say, however, that each one gets equal use. Far from it. Over the last four years, I have worn two caps more than the others combined. Together, they have paid my bills.

In today's post, I'll explain how my most important lines of business today—writing authors' books and building Notion tools—aren't all that dissimilar.

A Product at the End of the Project

I am not an executive coach or an occupational therapist. My Notion and ghostwriting clients hire me to help them accomplish a defined task. The new CRMs, bespoke event management systems, and physical books all had to meet some definition of done.

Admittedly, that simple, four-letter word can become squishy and contentious, especially on amorphous and flat-rate projects. To minimize confusion and conflict, I bill hourly. The benefits of doing so (avoiding scope creep) more than justify its minor administrative burden. (It's easy to automate time tracking in Notion.)

We Followed Agile Methods

Working on ERP systems for more than a decade taught me the profound limitations of Waterfall development. Of course, I could wait until the very end of the project to show a client a new dashboard, system, or manuscript. The odds that I'll stick the landing are remote, though.

Clients see alpha versions of Notion systems and rough tables of contents. (Ah, the beauty of Scrum.) By definition, they're not perfect. These prototypes provide invaluable directional feedback and minimize the risk of forthcoming surprises, frustration, and wasted time and money. If we're on the wrong track, we quickly find out, make necessary adjustments, and get on the same page.

Mutual Learning

The projects have varied considerably in many ways, but two things have happened on each one:

1. I've learned a great deal about my clients' needs and areas of expertise.
2. They've learned a considerable amount from me.

It's fair to call the transfer of knowledge symbiotic. My clients wouldn't have been able to complete their projects without their input and vice versa.

Unanticipated Delays

Never has even a medium-term engagement gone off without a hitch. At one extreme, a client vowed to follow up with me next week. I finally heard back from him a few weeks later. At the other, a ghostwriting client needed to pause her project for three months.

A New Respect for the Importance of Process

At the beginning of each project, I explain that no decision is irrevocable. Some bells, though, are harder than others to unring. Case in point: changing database structures and reorganizing book sections involves a great deal of rework. Intellectually, that statement is facile, but I make that key point several times before we sign anything. To use a housing metaphor, I ask them to triple-check if we're building a Colonial.

In a few cases, a client and I have reached the point of no return and the former has inexplicably reversed course. (“Yeah, I want a duplex now.”) Demolishing the foundation is expensive, and the burnt hand teaches best.

If we're on the wrong track, we quickly find out and make necessary adjustments.

Brass tacks: each of my clients has walked away with a heightened appreciation for our process.

Feedback

Do you see parallels between different lines of your business? What say you?

At its recent developer conference, Notion announced a powerful new way to extend the application. Still in beta, Notion Workers let users do many interesting things. In the company's words:

Workers are isolated sandboxes managed by Notion, so the code behind your syncs, tools, and workflows runs on our infra(structure) instead of your servers.

Most interesting to me: the ability to sync data from third-party systems. For example, say that your organization runs Salesforce as its CRM. Workers make it relatively easy to bring that data into your Notion workspace for additional analysis and tracking.

I've spent a good deal of time noddling with the new sync capability. Claude Code helped me navigate the new Notion CLI and run some tests with a simple Google Sheet. In today's post, I'll share some of the things I've learned so far.

Long story short: Workers aren't perfect, but they're remarkable. I suspect that over the next year I'll be doing more with them for my Notion clients.

Table of Contents

• Project & Worker Management
  • Useful CLI Reference Commands
  • Directory Context Matters
  • Finding Project Directories
  • Identifying a Worker's ID
  • Renaming a Worker
  • Deleting a Duplicate Worker
  • Code Reuse Across Workers
• Syncing
  • Triggering a Manual Sync
  • Finding the Correct Sync Key
  • Diagnosing a Sync That Runs But Writes Nothing
  • Diagnosing a Runaway Sync Loop
• Schema & Data
  • Adding a New Property to a Synced Database
  • Changing a Property Type
  • Replace Mode Only Manages Worker-Created Records
  • Identifying Read-Only vs. User-Defined Properties
  • Two-Way Sync
• Deployment & Debugging
  • TypeScript Compilation Errors During Deploy
  • Debugging Failed Deploys

Project & Worker Management

Useful CLI Reference Commands

Directory Context Matters

The ntn CLI resolves the target Worker from the workers.json file in the current directory. Always cd into the correct project folder before running Worker commands. Running commands from the wrong directory targets the wrong Worker or fails entirely.

cd /Users/your_drectory

Finding Project Directories

To locate all Worker projects on your machine:

find ~ -name "workers.json" 2>/dev/null

Identifying a Worker's ID

To find the Worker ID tied to a specific project directory:

cat /path/to/project/workers.json

The workerId field is the canonical identifier for that Worker.

Renaming a Worker

The CLI lacks a dedicated rename command. The display name derives from the name field in package.json. Update that field and redeploy to rename the Worker. The sync capability key — which you define in src/index.ts — is independent of the display name and continues to work without modification.

Deleting a Duplicate Worker

With two Workers sharing the same display name, confirm which ID belongs to the unwanted one via workers.json, then delete it:

ntn workers delete <worker-id>

Code Reuse Across Workers

Once you build a working Worker, save it as a GitHub repo or template. The Worker structure, deploy flow, and Notion API calls transfer to future projects. Swap out the data source and schema — the scaffolding stays intact.

Syncing

Triggering a Manual Sync

To bypass the schedule and trigger a sync immediately, run the following from your Worker project directory:

ntn workers sync trigger <syncKey>

The sync key is the string passed to worker.sync("...") in src/index.ts — it may differ from the Worker's display name in the Notion UI.

Finding the Correct Sync Key

If you don't know the sync key, run this from the project directory:

ntn workers capabilities list

This returns the exact key and type for every registered capability.

Diagnosing a Sync That Runs But Writes Nothing

All runs showing exit code 0 with no database changes usually means an incremental sync has recorded state and sees no new data. Reset the state to force a full re-fetch:

ntn workers sync state reset <syncKey>
ntn workers sync trigger <syncKey>

Diagnosing a Runaway Sync Loop

If the runs list shows dozens of executions firing every few seconds, you've set the schedule option in src/index.ts too aggressively (such as "continuous" or "1m"). Change it to "1h" (or another appropriate interval) and redeploy:

ntn workers deploy

Left unchecked, a runaway sync burns through Worker credits rapidly.

Schema & Data

Adding a New Property to a Synced Database

Adding a column to the Google Sheet does not automatically add it to Notion. The Worker only syncs properties explicitly defined in src/index.ts. Two changes are required:

1. Add the property to the schema block:

schema: {
  properties: {
    Descr: Schema.title(),
    Code: Schema.richText(),
    NewProp: Schema.richText(), // add here
  },
},

1. Add the property to the mapping inside execute:

properties: {
  Descr: Builder.title(row[1] ?? ""),
  Code: Builder.richText(row[0]),
  NewProp: Builder.richText(row[2] ?? ""), // add here
},

Then redeploy and resync:

ntn workers deploy
ntn workers sync state reset <syncKey>
ntn workers sync trigger <syncKey>

Changing a Property Type

Changing a property's type in src/index.ts (such as from Schema.richText() to Schema.number()) does not convert the existing property in Notion. Notion keeps the original type.

The fix: rename the property in src/index.ts to force Notion to create a fresh property with the correct type. The old property remains but sits empty — hide it from your views.

Replace Mode Only Manages Worker-Created Records

The Worker's replace mode mark-and-sweep only tracks and removes records it created. Records added manually in the Notion UI don't carry the Worker's internal tracking metadata, so the sync leaves them alone — even if they don't exist in the external source.

If orphaned manual records appear in a managed database, delete them directly in Notion. They won't be cleaned up automatically.

Identifying Read-Only vs. User-Defined Properties

Notion provides no visual indicator distinguishing synced (read-only) properties from user-defined ones. The reliable method: open a record and try to edit a field. Synced Worker properties are locked. User-defined properties accept edits.

From the code, read-only properties carry readOnly: true in the data source schema — these map directly to columns in the external source. Any property you add to the Notion database outside the Worker schema (such as a Status or ID field) remains fully editable and the sync won't touch it.

Two-Way Sync

Workers syncs are one-way by design: external source → Notion. To push Notion changes back to an external source, build a second Worker using worker.webhook(...). The flow:

1. The second Worker registers a webhook endpoint and gets a URL on deploy.
2. A Notion database automation triggers on page changes and fires a POST to that URL.
3. The webhook handler reads the payload and writes the change to the external source (such as Google Sheets via its API).

The Notion-side plumbing transfers to any external source. The external API client and auth (such as OAuth for Google Sheets) require rewriting per source.

Deployment & Debugging

TypeScript Compilation Errors During Deploy

A failed deploy (exit code 2) means the TypeScript compiler rejected the code. The error appears directly in the Terminal output when you run ntn workers deploy. Always read that output before troubleshooting elsewhere.

Common example: Builder.number() does not accept null. Use a numeric fallback instead:

// Wrong
Num: Builder.number(row[2] ? parseFloat(row[2]) : null)

// Right
Num: Builder.number(parseFloat(row[2] ?? "0") || 0)

Debugging Failed Deploys

Use ntn workers runs list to check exit codes. A deploy with exit code 2 failed — any sync runs after it use the last successful build, not your latest code. The full error appears in the Terminal output of ntn workers deploy itself, not in the run logs.