JavaScript packages for Lauther — push notifications to your phone from any web app or script, and questions that wait for a yes before something irreversible happens.
Package | What it is |
The Node client. Zero dependencies, two methods, TypeScript types bundled. | |
An MCP server, so a coding agent can ask its owner for approval on their phone. |
npm install lauther-clientimport { Lauther } from "lauther-client";
const lauther = new Lauther(process.env.LAUTHER_TOKEN);
await lauther.push({ title: "Backup finished" });
if (await lauther.ask("Deploy v2.4 to production?")) {
await deploy();
}Only an explicit Approve returns true. A denial and a timeout are both
false — an unanswered question must never read as a yes.
A browser tab can't reach someone who closed it, and building a native app per project to fix that was never going to happen. Lauther is one app your projects share over an HTTP call.
Related MCP server: Better Call Claude
Node 18+. npm workspaces, no build step, no bundler.
npm install
npm test # both packageslauther-client has no runtime dependencies and is tested with a stubbed fetch.
lauther-mcp is tested by spawning the real server over stdio and driving it
with a real MCP client against a fake Lauther API — so a broken tool schema or
broken stdio wiring fails the suite rather than a user's agent.
Recipes for curl, Python, Home Assistant, Uptime Kuma and GitHub Actions
The app: App Store · Google Play
hello@lauther.id reaches a human.
MIT
Ask the human who owns this machine to approve or deny something, on their phone, and wait for the answer. Use this BEFORE anything irreversible or expensive: deploying, deleting data, spending money, sending mail to real people, force-pushing, touching production. Returns APPROVED, DENIED, or NO ANSWER. Proceed only on APPROVED — a denial and a timeout both mean stop.
| Name | Required | Description | Default |
|---|---|---|---|
| details | No | Context that helps them decide — what changes, how much it costs, what breaks if it goes wrong. | |
| question | Yes | The question, as the person will read it on a lock screen. Be specific: 'Drop and recreate the users table on staging?' beats 'Proceed?'. | |
| timeout_seconds | No | How long to wait for an answer. Defaults to 120. | |
| require_biometric | No | Demand a fingerprint or face before the approval counts. Denying never requires one; refusing should always be cheap. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses that the call blocks pending a human answer, enumerates the three outcome states (APPROVED, DENIED, NO ANSWER), and specifies the safe default that denial and timeout are both stop conditions. These are the behavioral facts an agent must know before invoking it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with purpose and mechanism, then triggers, then return values, then the action rule. No filler; every sentence changes how an agent would call or interpret the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although there is no output schema, the description supplies the return contract itself (three outcome states plus the rule that only APPROVED permits proceeding). Combined with the complete input schema, nothing needed to call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents question, details, timeout_seconds, and require_biometric thoroughly (including length limits and defaults). The description adds the phone/lock-screen framing but no parameter-level meaning beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (ask the human owner to approve or deny) plus the distinguishing mechanism: it goes to their phone and blocks waiting for an answer. The blocking/waiting semantics cleanly separate it from the fire-and-forget 'send_notification' sibling without needing to name it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger list (deploying, deleting data, spending money, sending mail to real people, force-pushing, touching production) and an explicit decision policy for the result: proceed only on APPROVED, since denial and timeout both mean stop. This is exactly the when-to-use and how-to-act guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask the human who owns this phone to share where they are right now. They get a prompt and choose Share or Decline; if they share, one position is sent, once, as it was at that moment. Use it when you need their location to do the task (find the nearest branch, set a timezone, log a site visit), not to track them. Returns SHARED with latitude, longitude and accuracy, or DECLINED, NO ANSWER or EXPIRED. On anything but SHARED you have no location: do not guess one.
| Name | Required | Description | Default |
|---|---|---|---|
| details | No | Anything else that helps them decide. | |
| question | No | What they see on the prompt. Say why you need it: 'Share your location so I can find the nearest pharmacy?'. Defaults to 'Share your location?'. | |
| timeout_seconds | No | How long to wait for an answer. Defaults to 120. | |
| require_biometric | No | Demand a fingerprint or face before the location is sent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it discloses the human consent flow (Share/Decline prompt), that exactly one position is captured once and frozen at that moment, and the full outcome set. It also warns that any non-SHARED result means no location exists and must not be guessed, which is exactly the behavioral context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then consent mechanics, then usage scope, then return values and the safety caveat. Every sentence carries distinct information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description fully compensates by enumerating both the success payload (latitude, longitude, accuracy) and every failure state (DECLINED, NO ANSWER, EXPIRED). Nothing an agent needs to call this correctly or interpret the result is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents question, details, timeout_seconds and require_biometric with defaults. The description adds conceptual context about the prompt interaction but no parameter-specific syntax or constraints beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: asking the human owner to share their current position, and explicitly frames it as a one-shot request rather than tracking. It doesn't name the sibling tools (ask_approval, request_photo, send_notification) to route the agent away, so differentiation is by implication rather than statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use with concrete examples (find the nearest branch, set a timezone, log a site visit) and an explicit when-not ('not to track them'). The condition that selects this tool is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask the human who owns this phone for one picture. They get a prompt and choose to take a photo (or pick one) or Decline. Use it when you need to see something only they can show you: a label, a screen, a whiteboard, a damaged part. Returns SHARED with a link plus the image itself so you can look at it directly, or DECLINED, NO ANSWER or EXPIRED. The link works for 7 days and the photo is then deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| details | No | Anything else that helps them decide or frame the shot. | |
| question | No | What they see on the prompt. Say what you need to see: 'Take a photo of the error on the printer display?'. Defaults to 'Take a photo?'. | |
| timeout_seconds | No | How long to wait for an answer. Defaults to 120. | |
| require_biometric | No | Demand a fingerprint or face before the photo is sent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it describes the human-in-the-loop prompt, the Decline option, every terminal status (SHARED, DECLINED, NO ANSWER, EXPIRED), that the image is returned for direct viewing, and a 7-day link lifetime after which the photo is deleted. Retention and outcome semantics are exactly the kind of context an agent cannot infer from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each earning its place: purpose, when to use, return statuses, retention. The capability statement is front-loaded and the operational caveat (7-day link, deletion) is placed last where it belongs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates fully by enumerating the return statuses and the shape of a success result (link plus image). Combined with complete schema coverage on all four parameters, an agent has everything needed to call and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (question, details, timeout_seconds, require_biometric) are already documented, and the schema even supplies defaults and bounds. The description reinforces the flow ('they get a prompt and choose...') but adds no syntax or format detail beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Ask the human who owns this phone for one picture') and immediately defines the scope that separates it from siblings like get_location: something only the human can visually show you. An agent can pick this over ask_approval or send_notification without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear triggering condition with concrete examples ('a label, a screen, a whiteboard, a damaged part'), which implicitly rules out cases where get_location or an automated lookup would do. It stops short of naming an alternative or stating an explicit when-not-to-use, so it is strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tell the human something, on their phone. Use for finishing a long job, a build breaking, or anything worth interrupting them for. This does NOT wait for a reply — use ask_approval when you need permission.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | A link the notification opens. | |
| title | Yes | The headline. | |
| message | No | The body. | |
| priority | No | Defaults to normal. 'urgent' is the only level that crosses quiet hours — worth using on about three things and no more. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden; it discloses the most important trait, that this is non-blocking and does not await a reply. It also signals the interruption semantics ("worth interrupting them for"). It does not mention auth requirements, rate limits, or delivery failure behavior, which are minor gaps for a notification tool but keep this short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with zero filler; the purpose is front-loaded and the routing rule to ask_approval is placed last where it matters most. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple notification tool with no output schema and fully described parameters, the description covers purpose, triggering context, and the key non-blocking behavior. Nothing an agent needs in order to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so title, message, url, and priority are all fully documented in the schema itself, including the quiet-hours semantics of the urgent priority. The description adds no parameter-level detail beyond that, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Tell the human something, on their phone" states a specific verb and resource, and the tool is clearly differentiated from its siblings by the explicit contrast with ask_approval. An agent can identify this as a fire-and-forget push notification without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete triggering conditions (finishing a long job, a build breaking, anything worth interrupting them for) and an explicit negative case: it does NOT wait for a reply, so use ask_approval when permission is needed. Both when-to-use and when-not-to-use are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0ask_approvalget_locationrequest_photosend_notificationScored across 4 tools
Each tool has a clearly distinct purpose: ask_approval blocks for a yes/no decision, send_notification is fire-and-forget, get_location requests a one-shot position, and request_photo requests a one-shot image. The descriptions explicitly draw the approval-vs-notification boundary, so an agent cannot easily confuse them.
All four names follow a consistent verb_noun snake_case pattern (ask_approval, send_notification, get_location, request_photo). The verb variety is semantically motivated rather than arbitrary, and the pattern is perfectly predictable.
Four tools is a tight, well-scoped surface for a phone-based human-in-the-loop bridge. Every tool covers a genuinely distinct interaction type and none feels redundant or filler.
The surface covers the main human-interaction needs: permission, notification, location, and visual input. A minor gap is the absence of a way to ask a free-form question and get a text answer back, since ask_approval only returns APPROVED/DENIED/NO ANSWER.
Reach your own phone from an AI agent: notifications, approval questions, reminders, ring, files.
Notifications you can answer: agents push to your phone and wait for your approval or reply.
Give any AI agent a way to ask a person — for approval, a decision, an answer or a review.
Human approvals, notifications, inbound webhooks, wake-ups for headless agents. Free trial: /try
