Feature Documentation

1. What Happy Squid does

Happy Squid is an intelligent blocker. You block the websites and apps that pull you away most often, and Happy Squid keeps them out of reach, without cutting off the parts of them that are worth keeping.

1.1 The idea

Most blockers treat a website as one thing: either you can open it or you cannot. But you might block Instagram and still need to message a friend, block YouTube and still need to watch a lecture, block Reddit and still need the one answer somebody posted three years ago.

Happy Squid can be as strict as you want it to be, up to a wall over the whole web that you cannot uninstall your way out of (section 11.7). What makes it different is what it does at the other end.

It blocks the site and lets you name the reasons worth making an exception for. Pick one of the exceptions Happy Squid suggests, write your own, or chat with Happy Squid to explain something you never saw coming. If your reason checks out, Happy Squid unblocks the site and holds you to that reason while you are there.

1.2 The words used in this guide

• Block. One thing you have blocked, together with everything that governs it: its exceptions, its Free Time, its schedule, its lock. A block can hold one website, several websites, a whole category, or apps.
• Exception. A reason you have written down in advance for visiting a blocked site. Picking one opens the site, and Happy Squid checks that what you do there fits the reason you picked.
• Task. A stretch of time where you tell Happy Squid what you are working on, and it blocks everything unrelated for the duration.
• Free Time. A budget of minutes you can spend on your blocked sites, in your own time, without giving any reason at all.
• Lock. A commitment with a deadline. While a lock runs you can make your blocks stricter, and you cannot make them looser.
• Angry Squid. A harder mode. Your written exceptions come off the blocked page, and the only way through is to convince Happy Squid.
• The blocked page. What you see instead of a blocked site. It is where your exceptions, Free Time and the chat all live.

1.3 The markers you will see

A few things in Happy Squid are drawn rather than written:

• An open padlock. On a block's row: nothing is locked, and pressing it is how you lock the block.
• A closed padlock with a time beside it. That block is locked, and that is how long is left. Pressing it offers Extend lock.
• A padlock that shakes. You pressed something a lock does not allow. The padlock that shakes is the one refusing.
• A padlock where the add button usually sits. On a block's Domains tab, or in Add Block → Domain: that website is locked somewhere and cannot be added here (section 3.3).
• A chain-link marker, next to a website's name. Another one of your blocks names that site as well, so a lock on either one covers both (section 3.3).
• A clock with a time beside it. On a block's row, what that block has left of its own Free Time (section 8.6). In the Mac menu bar, Free Time draining right now.
• A flame, on the Task Goals row. Your streak. Press it to see the count.
• The squid on the blocked page. It changes with the situation. The happy squid means you opened a blocked site. The blocked squid, above the words “has been blocked”, means Happy Squid took you off a page you were already on. The angry squid means Angry Squid is running (section 13).

1.4 The language you write in

For normal use Happy Squid's contextual evaluation is extremely solid in any language, but we have noticed improved performance in edge cases when exceptions and Tasks are written in English, especially when they are very short.

What Happy Squid collects, why, and what you can ask us to do with it is set out in our Privacy Policy.

2. Where you can use it

Happy Squid runs in your browser, on your Mac, and on your phone. You sign in with the same account everywhere, and your blocks and settings are there when you arrive.

2.1 The browser extension

The extension is where most people start, and it works on its own, and nothing else has to be installed. It is available for Chrome, Edge, Firefox and Safari, and the Chrome version also covers the other Chromium browsers such as Brave, Arc, Opera and Vivaldi. You can find all of them on our download page.

Install it, sign in with your Happy Squid account, and you are ready to make your first block.

2.2 The desktop app

The desktop app runs on macOS and is what makes Happy Squid hard to walk away from. It adds three things the extension cannot do on its own.

• It blocks applications, not just websites.
• It closes any browser that is not running Happy Squid. Switch on Close browsers running without the extension and a browser opened without Happy Squid working in it is given a short grace period to connect, and then closed. Installing a second browser, or running one with the extension removed or disabled, is therefore not a way round your own blocks. It is your whole machine that is covered, not the one browser you set things up in.
• It cannot be uninstalled while a lock is running. Happy Squid protects its own app on your Mac for as long as any lock is active, so deleting it is not an escape either. Once the lock ends it uninstalls normally.

Once the app is running, a small squid sits in the menu bar at the top of your screen. Click it to bring Happy Squid forward, and click it again to put it away. It also carries a countdown: a number on its own is a running Task, and a number behind a clock is Free Time draining.

Windows support is coming soon.

2.3 The phone apps

The phone apps run on Android and iOS. They block websites and applications on the phone itself, and they carry the same blocks, Tasks, Free Time and locks you set anywhere else.

2.4 What is available where

• In your browser. Blocking websites, exceptions, the chat, Tasks, Free Time, schedules and locks.
• On your Mac. Everything above, plus blocking applications and closing browsers that open without the extension.
• On your phone. Everything above except closing browsers, plus blocking applications.

3. Blocking websites

Everything starts with Add Block. You pick a Block type (Domain, Group, Category or App), and what you pick decides the shape of the block.

3.1 Blocking one website

Add Block → Domain, then type the address of the site: youtube.com, instagram.com, news.ycombinator.com. You do not need https:// or www., and the mobile version of a site counts as the same site, so blocking youtube.com covers m.youtube.com too.

A subdomain is usually its own site. Blocking youtube.com does not block music.youtube.com, so if you want both, add both. Sites whose content lives on their subdomains are the exception: blocking substack.com blocks every publication on it. If you want every block to work that way, turn on Block subdomains in Advanced Settings.

For sites Happy Squid already knows, the editor offers a short list of ready-made exceptions you can tick straight away. See section 6.

3.2 Blocking part of a site rather than all of it

Add a path after the address and only that part of the site is blocked. youtube.com/shorts blocks Shorts and leaves the rest of YouTube open. reddit.com/r/politics blocks one subreddit. The path matches itself and everything under it, so youtube.com/shorts also covers youtube.com/shorts/anything.

3.3 Putting several websites in one block

Add Block → Group gives one block that holds as many websites as you like. Give it a name, such as “Socials”, “News” or “Shopping”, and add the addresses on the Domains tab. The Exceptions tab beside it holds the exceptions the whole group shares.

A group is one block, not several: one switch, one set of exceptions, one Free Time budget, one schedule and one lock cover every site in it.

You can add a website to a group at any time, a locked group included, because a site added covers more than the block covered before. A website already in a locked group stays in it until the lock ends.

A chain-link marker next to a website's name on the Domains tab means another one of your blocks names that site as well. It is worth reading, because a lock does not stop at the block you set it on.

Locking a group locks every block that shares one of its websites, for the same length of time, and the lock dialog lists those blocks by name before you confirm. It works the other way round too: lock the individual block on youtube.com and a group holding youtube.com is locked along with it, countdown and all, even though you never locked the group.

While a website is locked, it cannot be pulled into another block. Type it into a group's Domains tab and the add button turns into a padlock, and the site stays out until the lock ends. The same padlock appears in Add Block → Domain and in Add websites to this category. Without these two rules a lock would be a formality: the locked website could be named in a block of its own, handed a fresh set of exceptions and a Free Time budget of its own, and opened with the lock still running.

3.4 Turning a block off, and deleting it

Every block has its own switch on the settings list. Switching a block off keeps everything you set up (the websites, the exceptions, the Free Time) and simply stops it blocking. Switching it back on picks up exactly where it left off. This is what you want for a block you use some weeks and not others.

Deleting a block, from the block editor, removes it and the websites that only existed inside it.

3.5 A website in more than one block

The same website can sit in several blocks at once: instagram.com might be in your “Socials” group, in the social media category, and have its own individual block as well. That is fine, and each block keeps its own switch, its own exceptions and its own Free Time.

You build that up while the website is free to be added, though. Once a website is locked, it cannot be put into a further block until its lock ends, as section 3.3 describes.

When you land on the blocked page, Happy Squid shows you the most specific block that covers the site: an individual block first, then a group, then a category. If more than one block applies you can pick between them right there. See section 7.2.

4. Categories and the Everything block

Sometimes naming websites one at a time is the wrong tool. A category blocks a whole kind of website at once, and Happy Squid keeps the list of what belongs to it.

4.1 Blocking a category

Add Block → Category, then pick one:

• Social media
• Streaming
• Shopping
• Gambling
• Adult content
• Everything: the whole web, covered in section 4.5

A category block behaves like any other block. It has its own switch, its own exceptions, its own Free Time, its own schedule and its own lock. What it does not have is a list of websites for you to maintain: Happy Squid keeps it, and it grows as new sites are added.

4.2 Adding your own websites to a category

Add websites to this category adds a site of your own to a category block. If a shopping site you use is not in the shopping category, add it there and it is blocked and unblocked along with the rest of them. Your additions sit alongside the built-in list.

4.3 Exempting websites from a category

Exempt websites from this category is the other direction: a site inside the category that you want left alone. Exempt it and the category blocks everything else as before.

The exemption list has its own switch, so you can turn every exemption off for a while without losing the list.

4.4 Hiding a block

Hide this block in advanced settings moves a block's row out of the main settings list and into Advanced Settings. It is there for discretion (the adult content category is what it was built for), and it changes nothing about how the block works. It keeps blocking exactly as before.

4.5 The Everything block

Everything is the category that covers the whole web. Switch it on and every website is blocked, without you naming a single one.

It is built to be reached for rather than left on. Because it blocks everything, the way you shape it is by punching holes in it: Exempt websites from this category lists the sites that stay open while the wall is up. Happy Squid also offers a few ready-made exemptions to tick, such as Wikipedia and PDF files.

Everything you can do with any other block, you can do with this one: give it exceptions, give it Free Time, schedule it, lock it.

It also makes the strictest way of working Happy Squid supports. Leave the Everything block switched on all the time, give it no exceptions, and the only way onto any website is to start a Task and say what you are working on. Nothing is reachable by habit, and everything is reachable by saying what it is for.

4.6 Include all apps

Include all apps, on the Everything block, extends it from every website to every application on your phone. As with websites, there is no list to keep, so an app you install tomorrow is covered the first time you open it.

Underneath it, Show exempted apps opens the list of apps that stay open anyway. Happy Squid ticks a sensible starting set for you (your clock, your wallet, your messaging app), and you add whatever else you need. A short list of apps is never blocked at all, so calls, messages and your keyboard always work.

4.7 Morning Lock

Morning Lock is a standing overnight commitment, set up in Advanced Settings. It is for the hours you would rather not spend on your devices at all, late at night and the first stretch after waking up, and it holds on every device you use at once: unlocking on your phone lifts the wall on your laptop too.

While its window runs it walls the whole web, and every application on your phone with it. There is no list to keep: everything is behind the wall until the morning lets it out.

Free Time is off for as long as the window runs, on websites and applications alike, and there is no setting for it. The Free Time button is greyed out and nothing is spent, so your minutes are there when it ends.

It has four settings:

• Unlock delay after button press: how long the wall stays up after you say you are awake. In the morning your devices show an Unlock your devices card, and its Start Unlock button starts this countdown, so the phone is not the first thing your morning goes on. One press is enough, on whichever device is nearest: the countdown is shared, so they all unlock together. On Android that button is on the Morning Lock notification too, so you can start the countdown without opening the app.
• Disable unlock button for: hours at the start of the window with no Start Unlock button at all. Until it runs out the only thing that can end the morning is Automatically unlocks at, so a commitment made at night cannot be lifted an hour later. It is zero unless you change it, which leaves the button there from the moment the wall goes up.
• Start lock at: the time each night the wall goes up.
• Automatically unlocks at: the backstop. The lock ends at this time whether or not anybody pressed anything, so it can never outlast the morning.

It carries two lists of its own:

• Exempt websites: the sites that stay open through a morning. It offers no ready-made exemptions, because what you want reachable at seven in the morning is not what you want reachable all day.
• Exempt apps: the same for applications on your phone. Switch it on and Happy Squid ticks the ones you actually need, such as your messages app, your clock and your wallet, so a morning never stands between you and a sign-in code. Add and remove ticks from there.

Changes you make while a window is already running land on the next morning: today's wall stands on the settings it went up with. The two that would open a hole in the wall standing right now are the lists above, and those can be tightened mid-morning but not loosened, so you can always take something away and never hand it back before the morning is over.

Morning Lock can be locked itself, from the padlock beside its heading. Press it, choose how long, and confirm, exactly as you would lock a block. That is what turns a nightly habit into a commitment: without it the whole thing can be moved or switched off in the evening you did not fancy it. While that lock runs, everything here stays as you set it, times and exemptions alike.

5. Blocking apps

Applications are blocked on your Mac and on your phone. When a blocked app is opened, Happy Squid closes it and shows you the same kind of wall a blocked website gets, carrying that block's Free Time and the chat.

App blocks do not have intelligent exceptions yet. Free Time and the chat are the ways through one.

5.1 Blocking an app

Add Block → App. On your phone you get the list of what is installed and tick as many apps as you like; on your Mac you pick the application itself.

One block can hold several apps, and they share everything the way websites in a group do: one switch, one Free Time budget, one schedule, one lock. A “Socials” app block covering Instagram, TikTok and X is one row, not three.

5.2 Blocking an app before you install it

On Android, search for it by name in the app picker and it appears even if it is not on the phone. Tick it and it is blocked from the moment it is installed, which is what makes “I do not want TikTok on this phone” a block you can actually make, rather than one you can only make after giving in once.

5.3 Adding apps to a website block

A website block on a phone is only half a block, because most sites have an app sitting one tap away. Add Apps to this Block, at the bottom of the block editor, closes that gap.

On Android you do not usually have to think about it: when you block a website, Happy Squid works out which installed apps match and ticks them for you. Block youtube.com and the YouTube app is already ticked. Block the social media category and the social apps you have are already ticked. Untick anything you would rather keep.

The result is one block over the site and the app together: one row on your home screen, one switch, one Free Time budget, one lock.

5.4 Blocking every app

To block every application at once rather than naming them, use Include all apps on the Everything block. See section 4.6.

6. Exceptions

Exceptions are what make cutting back on a website different from cutting it off. Each one is a reason, written in your own words, for opening a site you have blocked. They live in the block editor, under Exceptions, and they appear on the blocked page as buttons you can press.

Picking an exception opens the site. While you are there, Happy Squid checks that the pages you visit fit the reason you picked, so an exception is a door into part of a website, not the whole of it.

6.1 The exceptions Happy Squid suggests

For sites we already know about, the block editor offers ready-made exceptions the moment you type the address. On YouTube that is things like watching a lecture or looking up a tutorial; on Instagram, messaging somebody. Tick the ones that apply.

Some of them go straight where they are useful rather than to the homepage. An exception for managing your own content on YouTube opens YouTube Studio.

6.2 Writing your own

Press Add exception and describe the reason in your own words. “Look up a recipe”, “Reply to my team”, “Watch football highlights”. Add detail gives you more room to be specific, and being specific helps: the more precisely you say what counts, the more accurately Happy Squid can hold you to it.

Exceptions belong to the block they are written in, so every website in a group shares them, and a category block's exceptions cover every site in the category.

6.3 Advanced Exceptions

Switch on Enable advanced exceptions in Advanced Settings and each exception gains two extra controls.

• Redirect to: a page the exception opens instead of the site's front page. If your reason for opening a shopping site is a delivery you are tracking, send the exception straight to the orders page and skip the shop front.
• Retain context for the day: normally each use of an exception starts fresh. Tick this and Happy Squid picks up where the last use of that exception left off for the rest of the day. An exception of “watch one episode” is the case it is built for: with this ticked, one episode is all you get for the whole day, because the second use knows about the first.

7. When a site is blocked

Opening a blocked site takes you to the blocked page. Everything you can do about the block is on it, so there is nothing to go and find in settings.

7.1 What is on the blocked page

• Which site is blocked, and which of your blocks is blocking it.
• Your exceptions for that block, as buttons.
• Free Time, if you have any left and this block allows it.
• The chat, for a reason you did not write down in advance.
• Edit Block, which opens the editor for the block that is blocking you.
• Lock Website, if you want to commit to the block on the spot.
• Continue task, while a Task is running.

7.2 Picking which block you are blocked from

When a site sits in more than one of your blocks, the blocked page lets you choose which one you are dealing with. Happy Squid selects the most specific one for you (an individual block first, then a group, then a category), and the picker lists the others.

The choice matters, because a block's exceptions and its Free Time belong to it. If instagram.com is both in your “Socials” group and in the social media category, picking the group shows the group's exceptions and spends the group's Free Time; picking the category shows the category's. Pick the one whose reasons you are actually here for.

7.3 Using an exception

Press the exception that matches why you are here and the site opens. Happy Squid then keeps an eye on whether the pages you visit fit that reason, so picking “watch a lecture” and then opening the homepage feed will not last long, while picking it and watching a lecture will.

7.4 Chatting with Happy Squid

For the reasons you did not see coming, there is the chat. Explain why you need the site. If your reason checks out, Happy Squid unblocks it for you, for as long as that reason takes.

This works the other way round too. If Happy Squid is about to block a page you are on, the chat is where you make your case. See 7.6.

7.5 How long you get in for, and when access ends

Access is granted to the tab you are in, and it normally has no timer on it at all. You picked a reason, and you keep the site for as long as you are there for that reason. What ends it is going off that reason, not a clock running out.

A timer appears only when Happy Squid gives you one. If you talk your way in through the chat and what you asked for is the sort of thing that has a natural length, it may let you in for that long and say so. Free Time is the other timed case, and there the clock is your budget.

So access ends when:

• the time you were given runs out;
• you close the last tab you were using it in;
• you keep browsing well away from the reason you gave, and Happy Squid blocks the site again;
• Free Time runs out;
• you start a Task, which replaces whatever was open with the Task's own rules;
• the day rolls over. A Happy Squid day starts at 4 in the morning, not at midnight, so a late evening is still the same day.

7.6 If Happy Squid is about to block you

Happy Squid usually does not close a page out from under you. If you drift onto something that does not fit the reason you gave, it will normally say so in the chat first and give you about twenty seconds before the block lands.

That is your chance to answer. Tell Happy Squid why you need this page, and if your reason holds up the page stays and the block is called off. Going back to what you were doing calls it off too.

7.7 The emergency button

On a phone with no connection, the chat has nothing to reach, so the blocked page offers an Emergency button instead. One press opens the blocked site or app for three minutes.

You get one press a day, and the button only appears while your phone is actually offline. With a connection, the chat is right there and is the better door.

8. Free Time

Free Time is a budget of minutes you can spend on your blocked sites without giving a reason. It is the answer to wanting a break rather than an exception: you keep every block exactly as it is, and Happy Squid puts them back the moment your minutes are gone.

You spend it from the blocked page: press Free Time and the site opens while the clock runs.

8.1 Free Time Settings

Free Time Settings is where you set how much you get and how often it comes back. Choose the number of hours and minutes, and whether the budget refills each Day or each Week.

A daily budget refills at 4 in the morning; a weekly one refills on Sunday at the same time. This budget covers every block you have, unless you change that below.

8.2 Schedule Free Time

Schedule Free Time sets the hours Free Time may be spent in, one row per day of the week. Use it to keep your break out of your working hours, so Free Time is available in the evening and refused during the day, without you having to remember.

8.3 Disable Free Time for specific Blocks

Disable Free Time for specific Blocks lists your blocks and lets you take Free Time off any of them. That block is then not something Free Time opens, and its blocked page says so. Everything else still spends from the same budget.

This is how you keep casual browsing available for most of your blocks while one of them stays firm.

8.4 Disable Free Time during Angry Squid

Free Time stays available during Angry Squid unless you say otherwise. Disable Free Time during Angry Squid, in Free Time Settings, is the switch that takes it away, and it is off until you turn it on. Turning it on makes Angry Squid a good deal harder: the written exceptions are already gone, so with Free Time gone too the chat is the only way through.

8.5 Free Time during Morning Lock

A Morning Lock window takes your Free Time away for as long as it runs, on every block you have, and there is nothing to switch: a commitment you can spend fifteen minutes out of is not a commitment. Nothing is spent while it holds, so your minutes are there when the morning ends. Section 4.7 covers it.

8.6 Enable per Block Free Time

Switch on Enable per Block Free Time in Advanced Settings and each block editor gains a Free Time section of its own. A block with its own budget spends that one instead of the shared one: thirty minutes a day for YouTube specifically, separate from the hour you have for everything else.

8.7 Using it, and what happens when it runs out

Free Time counts down while you are actually using the site or app. It is shown as a countdown in the Happy Squid popup, on the blocked page and in the desktop app's menu bar, and it is the same budget everywhere, so minutes spent on your phone are minutes gone on your laptop.

When the budget runs out, every site it was holding open is blocked again straight away, and the blocked page comes back. Your exceptions and the chat still work; only Free Time is spent. It returns at the next daily or weekly refill.

On the desktop, Don't count Free Time while application is minimized stops the clock while a blocked app is minimised or hidden, so minutes go on the time you actually spend.

9. Tasks

Blocks are for the distractions you can name in advance. A Task is for everything else: you tell Happy Squid what you are working on, and it blocks whatever is unrelated for as long as you are on it, while letting through the sites your work actually depends on.

Say you start a Task and tell Happy Squid you are studying for an exam. It stops you scrolling social media, and lets you watch a lecture, look up a formula and find exercises on the topic. You do not have to anticipate every website that could pull you off course, or every exception you might need.

9.1 Starting a Task

New Task, then two things: what you are working on, and a Task Duration in hours and minutes. Press Start Task and it begins.

Only one Task runs at a time.

9.2 Describing what you are working on

Write it the way you would tell a colleague. “Finish the Q3 slides”, “Study organic chemistry chapter 4”, “Plan the trip to Lisbon”. Happy Squid judges every page you open against this description, so a specific one gives you a Task that guards you well.

Check if my Task is productive, in Advanced Settings under Task Settings and on by default, has Happy Squid look at the description before the Task starts and check that it is genuinely work. If it is not convinced, it says so and you can make your case in the chat. A Task that sounds like an excuse gets asked about, and a real one is waved through.

If your idea of productive is your own, Specify what productive means to you, on the same card, lets you write it down, and that definition is used from then on.

9.3 What is blocked while a Task runs

A Task's authority goes wider than your blocks. While it runs, Happy Squid judges every website you open against what you said you were doing, not only the ones you had blocked. That is the difference between a Task and an exception: an exception opens a door in a wall you built, and a Task builds the wall around the work.

Two things stay open regardless:

• Critical sites, which are always reachable: password managers, online banking, checkouts and sign-in pages, emergency helplines, and weather and travel warnings.
• Anything you have listed under Whitelist websites during Task in Advanced Settings: your own list of sites Happy Squid leaves alone while a Task is on.

If a page you genuinely need is about to be blocked, Happy Squid tells you in the chat first. Explain why you need it and, if your reason checks out, it stays open for the rest of the Task.

9.4 Pausing, stopping and finishing

• Pause task suspends it. Your blocks go back to normal and the clock stops where it is.
• Resume task picks it up with the same time remaining.
• Cancel Task stops it. The Task is over and your blocks go back to normal.

A Task that reaches its duration ends on its own, and that is what counts as finishing it: Happy Squid celebrates. However a Task ends, the time you worked on it goes towards your Task Goal (section 9.7).

Once a Task has ended, Happy Squid offers a +15m button, for when the work turned out not to be quite done. It also remembers the Task for five days, so starting the same work again is one press.

9.5 Lock task

Lock task turns a running Task into a commitment. While it is locked you cannot pause it, stop it, re-describe it or shorten it. You either see it through or wait it out.

The lock covers the rest of the Task's time, and it ends when the Task does.

9.6 Enable Free Time during Task

Enable Free Time during Task in Advanced Settings lets a Task allow Free Time browsing for its whole duration. It is off by default.

9.7 Task Goals

Enable Task Goals, in Advanced Settings, sets a target for how much Task work you do per day or per week. Give it a number of hours and minutes, pick the period, and Happy Squid tracks your progress against it.

Every Task counts towards it, and what counts is the time it actually ran: a Task you finish, one you stop and one you cancel all add the time you worked, and time spent paused adds nothing.

Reach the goal in a period and your streak goes up by one; miss a period and it goes back to zero. Raising the goal, or switching between daily and weekly, starts the streak again, because the streak belongs to the commitment you are keeping.

10. Integrations

Happy Squid connects to Todoist and Obsidian. More integrations are on the way.

10.1 Todoist

An item on your Todoist list can become a Happy Squid Task, and the two then keep each other in step.

10.1.1 Starting a Task from an item

With the integration installed, Happy Squid appears in the ⋯ menu of any Todoist task. Choosing it starts a Happy Squid Task for that item, so the thing you are protecting your attention for is the thing already written on your list, and you do not describe it twice.

Happy Squid takes the whole position of the item, not just its title: the project it sits in, the section, the parent task and its notes. “Fix the callback” under “Ship the auth rewrite” in “Work” is a different piece of work from the same four words under “Rebuild the garden shed”, and that context is what lets Happy Squid judge a website against it properly.

The Task then behaves like any other: the same chat, the same Free Time, the same lock. It has no duration of its own and runs until it is finished.

What the integration adds is that the two stay in step, in both directions. Mark the Task complete in Happy Squid and the Todoist item is ticked off for you. Tick the item off in Todoist and the Happy Squid Task stops, because the work it was protecting is done.

Marking a Task complete is only there for a Task that came from an integration. A Task you typed into Happy Squid runs to its duration or is stopped by you.

10.1.2 Installing it

Happy Squid is not in the Todoist app directory yet, so this link is how you add it. Open it while signed in to Todoist:

https://app.todoist.com/app/install/180455_c2b89a1dd4cfb237f3519f74

Todoist runs extensions like this one on Todoist for desktop and on the web, so starting a Task from the ⋯ menu works in both. The Todoist mobile apps do not host extensions yet, and Happy Squid will be there the day they do.

10.1.3 Connecting your Happy Squid account

The first time you choose Happy Squid on a Todoist task, it asks for the email address of your Happy Squid account and sends you a six-digit code to confirm it is you. Enter the code and the two accounts are linked.

You only do this once. After that, starting a Task from Todoist is a single choice from the menu.

10.2 Obsidian

Happy Squid starts, stops and completes Tasks from the checkboxes in your notes, and gives you the ability to insert cards that turn your Happy Squid activity into valuable insights. Markers you type put the time you worked on Tasks, the Free Time you spent, the times you were blocked and the morning you unlocked into any note, each about the day you name and as plain text you can wrap in anything. Two of them are styled cards: your Task Goal for that day, which opens onto every Task you worked on during it, and the Daily Summary, which gathers three of those figures with Happy Squid's own account of the day underneath. Your note keeps that account after Happy Squid has let it go.

10.2.1 Tasks

Type {task} at the end of a checkbox line in a note and it draws as start task. Pressing it starts a Happy Squid Task for that line, so the thing you are protecting your attention for is already written in your notes and you do not describe it twice.

Happy Squid takes the whole position of the line, not just its words: the folder, the note, the headings above it, the list item it sits under and that item's own notes. A task under “Ship the auth rewrite” in a work note is a different piece of work from the same words under a note about the garden, and that context is what lets Happy Squid judge a website against it properly.

The Task has the same chat, the same Free Time and the same lock as any other, and it runs until you stop or finish it. Starting one from a note takes over from whatever Task is running, so you do not have to go and stop the old one first.

The control says what pressing it would do:

• start task: nothing is running for this line.
• starting… and stopping…: Happy Squid has been asked, and the answer is on its way. A second press sends nothing.
• stop task: this line is the Task running now, and pressing it stops the Task, in your note and in Happy Squid. Stopping is not finishing, and the checkbox stays as it is. To finish the Task, tick the checkbox in your note, or press Complete in Happy Squid, which ticks the checkbox for you.
• task deemed unproductive: Check if my Task is productive (section 9.2), in Advanced Settings under Task Settings, looked at the line before starting and was not convinced it was work. The review opens in Happy Squid itself, in the extension or the app, and you can chat with Happy Squid about it there: say what the task actually is, and if your reason checks out it starts. The verdict is on the control in your note, and rewriting the line clears it, because the marker goes by the task's own words.
• current task locked: the Task running is a locked one. Lock task (section 9.5) is a commitment to see that Task through, so a new Task pushing it aside would be a way straight out of the lock, and it is the one thing a start from a note does not displace. The control says so until that Task's lock ends. Rewriting the line changes nothing here, because your words are not what is being refused.
• out of tasks this week: the free version's one Task a week is spent (section 15.2).

Starting and stopping is quickest with the Happy Squid desktop app installed: it is always running, so it picks the Task up the moment you press. Without it, a browser or a phone takes it instead, and it can take a few seconds longer.

Press Enter at the end of a marked line and the next one is marked too, so a run of tasks costs one marker rather than one per line. To take a marker off, put the cursor inside the control and it turns back into the text you typed. There is also a command, Start or stop task at caret, which works on any marked line in Live Preview, reading view and source mode.

If Happy Squid starts a task under wording of its own, after you have talked it round in the review, that wording is added as a new task line directly under yours, wearing your bullet and your indent and showing stop task. Finishing the Task ticks both.

10.2.2 Installing it

Happy Squid is in Obsidian's community plugin directory. In Obsidian, open Settings → Community plugins, choose Browse, search for Happy Squid, then install it and turn it on. It works in Obsidian on your computer and on your phone.

10.2.3 Connecting your Happy Squid account

Open Settings → Happy Squid in Obsidian and enter the email address of your Happy Squid account. It sends you a six-digit code, and entering it links the two. You only do this once.

10.2.4 Choosing the day a marker is about

Happy Squid draws several things into a note, and every one of them is about one day. Which day is part of the marker itself, and there are four ways to say it. They work the same on every marker in 10.2.5, with {taskgoal} as the example here.

• {taskgoal} is the day you wrote it. It stays live until that midnight and is fixed from then on, so a note about last Tuesday goes on saying what last Tuesday came to. Shortly after you type one, Happy Squid writes the date into it for you, and {taskgoal} becomes {taskgoal:2026-08-30}. It waits until you have stopped typing, leaves alone any marker your cursor is inside, and only ever writes to a note you have edited today. It is a single edit, so one undo takes it back.
• {taskgoal:today} is always today, whenever and wherever the note is read.
• {taskgoal:2026-08-29} is that day, forever. Write the month in the middle, with something between the numbers: 29.08.2026, 2026-08-29, 29/8/26 and 29_08_2026 all read, year first if you start with a four-digit year and day first otherwise. A month written out can go on either side, so Aug 29, 2026 and 29 Aug 2026 both work. 08/29/2026 and 20260829 are not read, and a date Happy Squid cannot read stays on the page exactly as you typed it, so you can see it did not take.
• {taskgoal:template} is for a marker in a template. It draws today where it stands, so you can see what you are writing, and every note you then create from that template gets a plain {taskgoal}, dated a moment later to the day that note was made.

Happy Squid keeps the last eight days that have ended, and they are filed away in your vault as it sees them, so a note about any day in the past week works even if Obsidian was closed all week, and your own notes keep them from there. A day Happy Squid knows nothing about has nothing to draw, and the marker stays as the text you typed.

10.2.5 What you can put in a note

Each of these takes all four forms from 10.2.4: the bare marker, :today, a date, and :template.

• {taskgoal}, your Task Goal for that day, drawn as a card in your own theme, with the flame that shows your streak. {taskgoal:today}, {taskgoal:2026-08-29}, {taskgoal:template}. Press the card open and it lists the Tasks that day was made of: when each one started, how long you worked on it, how many times Happy Squid blocked you while it ran, and what you called it, with a Task you cancelled marked as cancelled. A day with nothing on it has nothing to open, and a day with no Task Goal draws the card anyway, saying that Task Goals are switched off.
• {tasktime}, the total amount of time you worked on Tasks that day, as 1h 13m. {tasktime:today}, {tasktime:2026-08-29}, {tasktime:template}. It needs no Task Goal. A Task counts once it has ended, so time from one that is still running is added when it stops, and today reads 0m until the first Task of the day has ended.
• {timesblocked}, how many times Happy Squid blocked you that day, as 0, 1, 7. {timesblocked:today}, {timesblocked:2026-08-29}, {timesblocked:template}. It counts the times Happy Squid actually blocked you, taking a page away and putting the blocked page in front of you, and not the times you arrived on the blocked page: a blocked site sends you there again on every visit and every reload, so counting arrivals would be counting keystrokes rather than blocks. One page taken away is one block, however long you sit on the blocked page afterwards, and a block Happy Squid warns you about in the chat first counts when it warns you, whether or not you leave before it takes effect.
• {freetime}, the Free Time you spent that day, as 25m or 1h 19m. {freetime:today}, {freetime:2026-08-29}, {freetime:template}. It is the calendar day, so time you spend after midnight counts towards the new day even though your Free Time budget itself refills at 4 in the morning, and Free Time you are spending right now is added when you stop.
• {morningbutton}, the time you pressed Start Unlock on the Morning Lock that day, as 6:42 AM. {morningbutton:today}, {morningbutton:2026-08-29}, {morningbutton:template}. A morning you did not press it reads no button unlock.
• {daysummary}, the day at a glance, drawn as a card in your own theme, with Happy Squid's own account of it underneath. {daysummary:today}, {daysummary:2026-08-29}, {daysummary:template}. See 10.2.6.

The four figures carry no styling of their own, so they take whatever you wrap them in: a heading, a table cell, a callout, bold text.

10.2.6 The Daily Summary card

{daysummary} draws the day's three figures as one line, 3h 17m tasks · 47m free time · 8 blocks, and opens onto what Happy Squid wrote about that day. Happy Squid writes it at 4 in the morning, when the day is folded away, so a note you are writing today shows its figures straight away and gains its paragraph overnight.

Happy Squid keeps a written summary for seven days, and your note keeps it for good. Once it has been drawn into a note it stays there, so a daily note from last year still reads the way it did when you wrote it.

Settings → Happy Squid has a Daily Summary switch for each of the four things the card shows: Time spent on tasks, Free Time spent, Times blocked and Written summary. They change what the card draws, and everything goes on being recorded either way.

11. Locks

A lock is a commitment with a deadline. It is what makes a block something you decided once rather than something you decide again every time it gets in the way.

11.1 What a lock does

While a lock runs, you can make your setup stricter and not looser. You can add websites to a locked block, add a new block, delete an exception, shorten your Free Time or extend the lock itself. You cannot delete the block, switch it off, add an exception, or end the lock early.

Adding a website to a locked block means the block is locked, not the website. A website that is itself locked is the other case, and it cannot be added to any further block until its own lock ends, whether that block is locked or not (section 3.3).

A lock covers your settings, not your browsing. Everything you set up still works exactly as before: your exceptions still open sites, Free Time is still spendable, the chat still answers. A lock is not a stricter block, it is a block you have committed to.

11.2 Locking one block

Every block has a padlock on its row, and it works the same way whether the block holds websites or apps. Press it, choose how long, and confirm. The blocked page has the same control as Lock Website, for the moment you realise you want to commit.

A lock follows the websites in it. If a site is in more than one of your blocks, locking one of those blocks locks the site everywhere it appears, for the same length of time. Otherwise the block next door would stay free to give that same site a fresh set of exceptions and a Free Time budget of its own, which is a way through a lock that is still running. The lock dialog names the other blocks this will reach.

11.3 Global Lock

Global Lock is the same commitment over everything at once. It locks every block you have, your Free Time and your settings, for the length you choose. It is the one to reach for when the thing you want to commit to is your whole setup rather than one block in it.

The Everything block is the deliberate exception: while it is switched on, its own settings stay editable even under a Global Lock, so there is always a way to lift a whole-web wall.

11.4 Extend lock

Extend lock pushes a running lock further out. Locks only ever move later, so extending one is always available and shortening one never is. The same control starts a fresh lock when none is running.

11.5 The settings you can lock on their own

Sometimes what you want to commit to is not a block but the way Happy Squid behaves. Five things can be locked on their own, each with its own deadline, without locking your blocks:

• Lock Free Time, in Free Time Settings. Your Free Time can then only be reduced, its window only lengthened, and no block may gain a Free Time budget it did not already have. Free Time a block already has stays editable.
• Task Settings, from the padlock on that card. Check if my Task is productive cannot be switched off, Enable Free Time during Task cannot be switched on, your definition of productive cannot be rewritten, and no site can be added to the Task whitelist. Removals still work.
• Desktop Settings, from the padlock on that card. Close browsers running without the extension cannot be disarmed, and Don't count Free Time while application is minimized cannot be switched on.
• Lock custom instructions, on the Custom Instructions screen. Your instructions stay as written for the length of the lock.
• Morning Lock, from the padlock beside its heading. Its times and its exemptions stay as you set them for the length of the lock, so the morning cannot be edited away the night before. See section 4.7.

A Global Lock covers all five as well, so these are for committing to one of them on its own.

11.6 What you can still do while a lock runs

Everything about using Happy Squid carries on: exceptions, Free Time, the chat, Tasks. You can also add new blocks, add any website that is not itself locked to an existing block, and make any lock longer.

What a lock will not let you do is step around it. A lock is a commitment across every device you use, so for as long as one is running:

• Happy Squid cannot be uninstalled from your Mac. The desktop app protects itself while any lock is active, so removing it is not a way out of one.
• You cannot log out, which would otherwise take your blocks with it.
• You cannot delete your account, which is the same escape by a longer route.
• You cannot switch to a browser Happy Squid is not in, while Close browsers running without the extension is on, because that browser is closed for you.

All four are available again the moment the lock runs out.

11.7 How far a commitment can go

Happy Squid is built to be as strict as you decide to make it, and everything below can be switched on together. At its firmest it is a commitment your own future self cannot talk down.

What a lock itself holds:

• A lock can only ever be made longer. It cannot be shortened, lifted early, or turned off.
• Global Lock puts every block, your Free Time and your settings under one deadline at once.
• Schedule Lock makes that recur every week without you setting it again, and Morning Lock holds the whole web overnight and into the morning.
• Logging out and deleting your account both wait for the lock, so neither is a way out.

What it holds on your Mac:

• Happy Squid cannot be uninstalled while a lock is running.
• Any browser running without Happy Squid connected to it is closed, so a second browser, or one with the extension removed, is not a way round your blocks.
• Applications are blocked as well as websites.

What it holds on your phone:

• On Android, Happy Squid cannot be uninstalled while it is an active device administrator, and while a lock runs it also closes the system settings pages about itself, including the one carrying the uninstall button.
• Applications are blocked, and Include all apps covers every app on the device, including ones installed later.

And what it holds everywhere:

• Your blocks and locks are on every device you use, so moving to another one is not an escape.
• The Everything block walls the whole web, leaving only what you exempt.
• Angry Squid takes your written exceptions off the blocked page, so the only way through is to convince Happy Squid, and it is a harder conversation.

11.8 How a lock ends

A lock ends when its time is up, and it then disappears on its own, and there is nothing to unlock. A scheduled lock ends when its window closes, and Morning Lock ends in the morning, as described in section 4.7.

12. Schedules

Three things in Happy Squid can run on a weekly schedule: a block, your Free Time, and a lock. All three are set the same way, with a row per day of the week, each with its own start and end time. A window that starts later than it ends runs past midnight, so 22:00 to 06:00 is a night.

12.1 Schedule Block

Switch on Enable scheduled Blocks in Advanced Settings and each block editor gains Schedule Block. Set the hours and the block switches itself on and off to match: blocked during your working day, open in the evening, or the other way round.

A schedule only hands back what it took. If a window switched a block on, it switches it back off at the end; if you switch a block off yourself mid-window, the schedule leaves your decision alone.

12.2 Schedule Free Time

Schedule Free Time sets the hours your Free Time may be spent in. See section 8.2.

12.3 Schedule Lock

Switch on Enable scheduled Locks in Advanced Settings and the lock dialogs gain Schedule Lock. Inside the window your blocks are locked exactly as if you had locked them by hand, every week, without setting it again.

It works on a single block's lock and on the Global Lock alike. While the window is running the schedule is part of the commitment and cannot be moved, which is what stops it being lifted from the inside.

12.4 Morning Lock

Morning Lock is the nightly wall over the whole web and every application. It needs no opt-in and is set up in Advanced Settings. Section 4.7 covers it in full.

13. Angry Squid

Angry Squid is Happy Squid in a harder mood, for the days when your ordinary blocks are not holding. Switch it on and it stays on until you switch it off.

What changes:

• Your written exceptions come off the blocked page. The buttons are not there to press, so the reasons you set up in calmer moments cannot be used on autopilot.
• The chat is the way through, and it is a harder conversation. Happy Squid still listens, and a genuinely good reason still works. It just takes a better one.
• Free Time still works, unless you have switched on Disable Free Time during Angry Squid in Free Time Settings, which makes Angry Squid considerably harder: with the exceptions gone and Free Time gone, the chat is the only way through.

Two things survive it, on purpose:

• A running Task's Continue task button. A commitment you have already made stays keepable.
• Any exception Happy Squid handed you itself during a conversation. It gave you that one knowing the mood it was in.

In the browser and on your Mac you switch it on by clicking the squid, in the popup or on the settings page. On a phone it is the first row of Advanced Settings, labelled Angry Squid. While a Global Lock is running you can switch it on but not off, because turning it on is a tightening and turning it off would be a loosening.

14. Advanced Settings

Advanced Settings is where the extras live. Everything in it is optional, and Happy Squid works without touching any of it.

14.1 Custom Instructions

Custom Instructions is where you tell Happy Squid, in your own words, how you want your blocks handled. It applies everywhere, on top of the exceptions on your individual blocks.

Use it for the standing preferences that would be tedious to repeat on every block: how strict to be, what kind of reason you find acceptable, which sorts of pages are always fine for you. Lock custom instructions commits to what you have written for a set time.

14.2 Task Settings

• Check if my Task is productive: on by default. Happy Squid checks a new Task's description before the Task starts.
• Specify what productive means to you: your own definition, used in that check.
• Whitelist websites during Task: sites Happy Squid leaves alone while any Task is running.
• Enable Free Time during Task: off by default. See section 9.6.

14.3 Desktop Settings

• Close browsers running without the extension: closes any browser running without Happy Squid working in it, after a short grace period to let it connect. Installing another browser, or disabling or removing the extension in one, is then not a way round your blocks. Happy Squid signs your browsers into your account for you, so they all end up on the same one.
• Don't count Free Time while application is minimized: stops the Free Time clock while a blocked app is minimised or hidden.

14.4 The optional features

Each of these switches on a feature described elsewhere in this guide.

• Enable scheduled Blocks: adds Schedule Block to every block editor (section 12.1).
• Enable scheduled Locks: adds Schedule Lock to the lock dialogs (section 12.3).
• Enable per Block Free Time: gives a block its own Free Time budget (section 8.6).
• Enable advanced exceptions: adds Redirect to and Retain context for the day to your exceptions (section 6.3).
• Enable Task Goals: sets a daily or weekly target for Task work (section 9.7).
• Block embedded content: replaces content embedded from a blocked site inside another page, such as a YouTube player on a blog, with a small placeholder. Any lock you have running holds this on.

14.5 Notifications

The phone posts three countdown notifications, each with its own switch, and all three are on by default.

• Task monitoring: while a Task is running.
• Unlock monitoring: while a site is open under an exception or a grant.
• Free Time countdown: while Free Time is being spent.

14.6 Appearance

Use device appearance, on by default, follows whatever your device is set to. Switch it off and you can pick Light mode or Dark mode yourself.

Appearance is set per device, so a phone in a dark room and a laptop under an office light can each be read the way that suits them.

15. Your account and subscription

15.1 Signing in

Sign in with Google, or with your email address and a six-digit code we send you. Use the same account on every device and your blocks and settings are there when you arrive.

You need an account to use Happy Squid. Signing in is what makes your blocks, exceptions, Tasks, Free Time and locks work, and it is what carries them to your other devices.

Signing out does not lift anything you have already set up. Your blocks keep standing, and nothing can be changed or unblocked until you sign back in, so signing out is never a way past them.

15.2 Free Happy Squid and Happy Squid Pro

Happy Squid is free to use, and the free version is a real one: you get one blocked website and one Task a week, with Tasks up to an hour. Intelligent exceptions, the chat, Free Time and locks all work.

Happy Squid Pro lifts the limits: unlimited blocks, unlimited Tasks of any length, and category blocking. Prices are on our pricing page.

15.3 The free trial

Happy Squid Pro comes with a 7-day free trial. Choose the plan you would like to try and the trial starts automatically, which gives you time to use the paid features properly before committing to anything.

15.4 Managing or cancelling your subscription

Manage Subscription, in Advanced Settings, is where your plan lives. You can cancel any time, there or on our cancellation page, and you keep your subscription and its features until the end of the billing period you have already paid for.

If you bought Happy Squid through the App Store, your subscription is managed in your Apple account rather than here.

15.5 What happens when a subscription ends

When a subscription ends, all your blocks, including locked ones, are switched off, and you keep one, along with a Task a week. Nothing is deleted: everything you set up is still there, greyed out, and comes straight back if you subscribe again.

16. Common questions

16.1 Questions people ask

What makes Happy Squid different from other blockers? Traditional blockers block a website with no exceptions, so when you need to watch a lecture or find a recipe they will not let you. Happy Squid understands the difference between distractions and the content you need. Share your exceptions when you set up a block and it holds you to them; for anything you did not see coming, chat with it.

Can I use my account on several devices? Yes. Sign in with your Happy Squid account on each one and your blocks and settings are there.

Do I need the desktop app? No. The extension works perfectly on its own. The desktop app adds blocking applications, and closing browsers that open without the extension.

Can I block a website only during working hours? Yes. Switch on Enable scheduled Blocks and use Schedule Block in that block's editor.

Can I block just one part of a website? Yes. Add the path when you create the block: youtube.com/shorts blocks Shorts and leaves the rest of YouTube open.

Can I block apps as well as websites? Yes, on your Mac and on your phone. On a phone, blocking a website also ticks the matching apps for you.

Can I undo a lock? A lock runs until its time is up. You can always make it longer, add blocks, or make your setup stricter while it runs.

What happens to my blocks if I stop paying? They are switched off, locked ones included, and you keep one. Nothing is deleted. See section 15.5.

16.2 If something is not working

A site is not being blocked. Check the block's switch is on, and check the address. A subdomain is usually its own site, so blocking youtube.com does not cover music.youtube.com unless Block subdomains is on in Advanced Settings. If the block has a schedule, check whether you are inside its window. If Free Time is running, that is what is holding the site open, and it will block again when the minutes are gone.

The blocked page keeps coming back. That is Happy Squid deciding the pages you are on do not fit the reason you picked. Pick the exception that matches what you are actually doing, or explain it in the chat.

Happy Squid keeps blocking a page I need. Say so in the chat when it warns you. If your reason checks out the page stays. For something you need often, write it into that block as its own exception, or add it to Whitelist websites during Task if it only comes up during Tasks.

My Free Time is gone. It is one budget across all your devices, so minutes spent on your phone are minutes gone on your laptop. It refills daily at 4 in the morning, or weekly on Sunday at the same time.

I cannot change a setting. A lock is running. Look for the padlock. It may be on that block, or it may be a Global Lock, a scheduled lock, or one of the settings locks in section 11.5. You can still make things stricter while it runs.

Something else. Advanced Settings has a Report a bug option that sends us what happened, and you can always write to us at support@happy-squid.com.