Servers Playground How we check Add a server Log in

AimYear

Working · 2.2 s

io.github.Yahhi/aimyear-mcpv0.4.2

Accountability partner in your agent: one yearly aim, one main step a day, a timer your agent runs.

Productivity

Source Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://mcp.aimyear.com/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

add_device

Register a device token so server reminders (stand up, break over) can reach it. The phone app registers itself; use this for testing or a manual token.

tokenstring, required

platformstring, required

labelstring

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

AimYear MCP server | mcptry

Tools (51)

add_device

Register a device token so server reminders (stand up, break over) can reach it. The phone app registers itself; use this for testing or a manual token.

Argument	Type	Description
label	string
token*	string
platform*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "token",
    "platform"
  ],
  "properties": {
    "label": {
      "type": "string"
    },
    "token": {
      "type": "string",
      "minLength": 20
    },
    "platform": {
      "enum": [
        "ios",
        "android",
        "macos",
        "windows",
        "web"
      ],
      "type": "string"
    }
  }
}

add_note

Add a one-line note to a running session (this connection's, or session_id). May classify a session that was unclassified.

Argument	Type	Description
note*	string
op_id	string	for apps replaying queued requests: an id the app minted before its first attempt and reuses on retries, so the write is applied once and a retry gets the first answer back. Do not invent one; an agent calling interactively leaves it out
session_id	string	from get_now; required with op_id

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "note"
  ],
  "properties": {
    "note": {
      "type": "string"
    },
    "op_id": {
      "type": "string",
      "maxLength": 128,
      "minLength": 8,
      "description": "for apps replaying queued requests: an id the app minted before its first attempt and reuses on retries, so the write is applied once and a retry gets the first answer back. Do not invent one; an agent calling interactively leaves it out"
    },
    "session_id": {
      "type": "string",
      "description": "from get_now; required with op_id"
    }
  }
}

add_post

Post the day's progress, only after the user explicitly said to post. text is the draft as the user edited it (default: the draft from get_post_draft). Goes to the networks chosen in settings, or the ones given. A network where the user already posted that day themselves is skipped. Each day goes to each network once: a retry never posts twice. Today or yesterday only. Pro.

Argument	Type	Description
date	string	YYYY-MM-DD in the user's timezone
text	string
networks	array	default: the networks chosen in settings

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    },
    "text": {
      "type": "string",
      "maxLength": 4000
    },
    "networks": {
      "type": "array",
      "items": {
        "enum": [
          "wip",
          "bluesky"
        ],
        "type": "string"
      },
      "description": "default: the networks chosen in settings"
    }
  }
}

add_session

Add past time that was not timed: minutes (ending now, or at end), or start+end as HH:MM on date. For calls, children, workout, paid work, or work done away from the agent. Apps replaying a queued entry pass op_id, so a retry does not count the time twice.

Argument	Type	Description
end	string	HH:MM local time
area	string	default work
date	string	YYYY-MM-DD in the user's timezone
task*	string
op_id	string	for apps replaying queued requests: an id the app minted before its first attempt and reuses on retries, so the write is applied once and a retry gets the first answer back. Do not invent one; an agent calling interactively leaves it out
start	string	HH:MM local time
itemId	string	plan item id
stepId	string	path step id
weight	number	attention weight vs other sessions at the same time, default 1
leverId

add_social_account

Connect WIP (wip.co) or Bluesky so AimYear can post the day's progress there when the user says Post (Pro). WIP: api_key from wip.co settings. Bluesky: handle and an app password (Settings → Privacy and security → App passwords), never the account password. The login is checked, stored encrypted and never shown again. The app's connect screen usually calls this; if the user pastes a key into the chat, use it once and do not repeat it.

Argument	Type	Description
handle	string	Bluesky only, e.g. name.bsky.social
api_key	string	WIP only
network*	string
app_password	string	Bluesky only: xxxx-xxxx-xxxx-xxxx

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "network"
  ],
  "properties": {
    "handle": {
      "type": "string",
      "maxLength": 253,
      "description": "Bluesky only, e.g. name.bsky.social"
    },
    "api_key": {
      "type": "string",
      "maxLength": 512,
      "minLength": 8,
      "description": "WIP only"
    },
    "network": {
      "enum": [
        "wip",
        "bluesky"
      ],
      "type": "string"
    },
    "app_password": {
      "type": "string",
      "maxLength": 64,
      "description": "Bluesky only: xxxx-xxxx-xxxx-xxxx"
    }
  }
}

add_steps

Add concrete steps to a milestone. A step is an action that fits a few work blocks ("email 10 people from the waitlist"), not "do marketing". Abstract steps are rejected. Put a hard-lever step first; preparation only where it blocks it (warns otherwise).

Argument	Type	Description
op_id	string	for apps replaying queued requests: an id the app minted before its first attempt and reuses on retries, so the write is applied once and a retry gets the first answer back. Do not invent one; an agent calling interactively leaves it out
steps*	array
milestoneId*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "milestoneId",
    "steps"
  ],
  "properties": {
    "op_id": {
      "type": "string",
      "maxLength": 128,
      "minLength": 8,
      "description": "for apps replaying queued requests: an id the app minted before its first attempt and reuses on retries, so the write is applied once and a retry gets the first answer back. Do not invent one; an agent calling interactively leaves it out"
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "title"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "leverId": {
            "type": "string"
          },
          "estimateMin": {
            "type": "integer",
            "maximum": 9007199254740991,
            "minimum": -9007199254740991
          }
        }
      }
    },
    "milestoneId": {
      "type": "string"
    }
  }
}

check_goal_draft

Check a goal that is not saved yet against the rubric (a countable metric with value today and target, or a done-or-not result you can check yes or no; deadline within 12 months; pace per week). Changes nothing. Returns problems[] and next_question: loop until problems is empty, then call set_goal. Prefer count; use done only when no honest number exists.

read-only

Argument	Type	Description
kind	string	count (default): a number from baseline to target, e.g. "15 paying customers". done: a one-time result checked yes or no, e.g. "launch v2 in the stores"; no metric, baseline or target, progress is the share of stages done
title	string
metric	string	the one number and its unit, e.g. "paying customers"
target	number
baseline	number	value today
deadline	string	YYYY-MM-DD in the user's timezone

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "kind": {
      "enum": [
        "count",
        "done"
      ],
      "type": "string",
      "description": "count (default): a number from baseline to target, e.g. \"15 paying customers\". done: a one-time result checked yes or no, e.g. \"launch v2 in the stores\"; no metric, baseline or target, progress is the share of stages done"
    },
    "title": {
      "type": "string"
    },
    "metric": {
      "type": "string",
      "description": "the one number and its unit, e.g. \"paying customers\""
    },
    "target": {
      "type": "number"
    },
    "baseline": {
      "type": "number",
      "description": "value today"
    },
    "deadline": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    }
  }
}

delete_agent

Disconnect one agent: its sign-in for this account is deleted and it can no longer read or change anything until it connects again. Only on the user's explicit request. client_id from list_agents.

destructive

Argument	Type	Description
client_id*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "client_id"
  ],
  "properties": {
    "client_id": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1
    }
  }
}

delete_device

Remove a device so it stops receiving reminders.

destructive

Argument	Type	Description
token*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "token"
  ],
  "properties": {
    "token": {
      "type": "string"
    }
  }
}

delete_plan_item

Remove one item from a day's plan. A routine item is skipped for that day only.

destructive

Argument	Type	Description
date	string	YYYY-MM-DD in the user's timezone
itemId*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "itemId"
  ],
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    },
    "itemId": {
      "type": "string"
    }
  }
}

delete_session

Delete a session, running or finished, so it no longer counts. Pass session_id from get_now or list_sessions; without it, only this connection's single running session is deleted, never another one.

destructive

Argument	Type	Description
op_id	string	for apps replaying queued requests: an id the app minted before its first attempt and reuses on retries, so the write is applied once and a retry gets the first answer back. Do not invent one; an agent calling interactively leaves it out
session_id	string	required with op_id

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "op_id": {
      "type": "string",
      "maxLength": 128,
      "minLength": 8,
      "description": "for apps replaying queued requests: an id the app minted before its first attempt and reuses on retries, so the write is applied once and a retry gets the first answer back. Do not invent one; an agent calling interactively leaves it out"
    },
    "session_id": {
      "type": "string",
      "description": "required with op_id"
    }
  }
}

delete_social_account

Disconnect a network and delete its saved login. Posts already made stay there.

destructive

Argument	Type	Description
network*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "network"
  ],
  "properties": {
    "network": {
      "enum": [
        "wip",
        "bluesky"
      ],
      "type": "string"
    }
  }
}

delete_step

Delete one step from the path.

destructive

Argument	Type	Description
stepId*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "stepId"
  ],
  "properties": {
    "stepId": {
      "type": "string"
    }
  }
}

edit_milestone

Change one milestone: title, kind (count or steps), metric, target, due date or status. status=retired drops it without finishing; done or retired moves the path to the next milestone. Its steps are kept.

Argument	Type	Description
due	string	YYYY-MM-DD in the user's timezone
kind	string	count: progress is a recorded value against target ("talk to 20 people"); steps: progress is steps done ("implement the onboarding flow"), no metric needed. Default: count when metric and target are given, else steps; an existing milestone keeps its kind
title	string
metric	string
status	string
target	number
milestoneId*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "milestoneId"
  ],
  "properties": {
    "due": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    },
    "kind": {
      "enum": [
        "count",
        "steps"
      ],
      "type": "string",
      "description": "count: progress is a recorded value against target (\"talk to 20 people\"); steps: progress is steps done (\"implement the onboarding flow\"), no metric needed. Default: count when metric and target are given, else steps; an existing milestone keeps its kind"
    },
    "title": {
      "type": "string"
    },
    "metric": {
      "type": "string"
    },
    "status": {
      "enum": [
        "todo",
        "doing",
        "done",
        "retired"
      ],
      "type": "string"
    },
    "target": {
      "type": "number"
    },
    "milestoneId": {
      "type": "string"
    }
  }
}

edit_plan_item

Change one plan item: mark it done or not done, rename it, change its estimate, area or links, or make it the main step. done=true also completes its linked path step. For a weekly routine, count says how many units this tick did (talked to 2 people today). For a routine, level minimum says only its bad-day minimum was done: it counts for the day, reported apart from full.

Argument	Type	Description
area	string
date	string	YYYY-MM-DD in the user's timezone
done	boolean
count	integer	units done in this tick, for a routine with perWeek; above 0 ticks it, 0 unticks it
level	string	routines only; sets done unless done is given
title	string
itemId*	string
stepId	string
leverId	string
projectId	string

edit_session

Fix a session, running or finished: start and end (HH:MM on date; an end before the start means it ran past midnight), task, area, project, lever, step, plan item, summary, outcome, attention share, weight. It is classified again after a change. Use it when a timer was forgotten or a session was labelled wrong.

Argument	Type	Description
end	string	HH:MM local time
area	string	default work
date	string	local date of start and end; default the session's own date
task	string
start	string	HH:MM local time
itemId	string	plan item id
stepId	string	path step id
weight	number	attention weight vs other sessions at the same time, default 1
leverId	string
outcome	string
summary

edit_step

Change one step: title, status (todo/doing/done), order, lever, estimate.

Argument	Type	Description
order	integer
title	string
status	string
stepId*	string
leverId	string
estimateMin	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "stepId"
  ],
  "properties": {
    "order": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991
    },
    "title": {
      "type": "string"
    },
    "status": {
      "enum": [
        "todo",
        "doing",
        "done"
      ],
      "type": "string"
    },
    "stepId": {
      "type": "string"
    },
    "leverId": {
      "type": "string"
    },
    "estimateMin": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991
    }
  }
}

find_gaps

Untimed stretches of 20+ minutes between the first and last session of a day. Ask the user what happened there.

read-only

Argument	Type	Description
date	string	YYYY-MM-DD in the user's timezone

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    }
  }
}

find_leaks

Where time leaks: comfortable goal work while the main step waited, overrides, unplanned work, gaps, switching, missed main steps, days without a plan. Default the last 7 days.

read-only

Argument	Type	Description
to	string	YYYY-MM-DD in the user's timezone
from	string	YYYY-MM-DD in the user's timezone

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    }
  }
}

get_capacity

Weekly time budget out of 168 hours: overhead, hours committed per area, focus windows, and what is still unaccounted for. Nothing is assumed.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {}
}

get_commitments

Recurring weekly time: commitments (school runs, training, classes), overhead (sleep, meals) and focus windows.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {}
}

get_goal

The one yearly goal: kind (count or done), metric, starting value, current value, target, deadline, progress, levers (hard/comfortable) and other projects. Call first in most flows.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {}
}

get_insights

Week (the last 7 days) or month (the last 30 days) ending on to (default today): minutes per day on the aim, other work and life; hard vs comfortable share of aim time; an hour × weekday heatmap of aim minutes (6:00–23:00, Mon–Sun) with its hard part and the peak; main-step days; and comebacks (active days after 2+ days away, over 90 days). Wall minutes of finished sessions, as the app shows them.

read-only

Argument	Type	Description
to	string	last day, default today
range	string	default week

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "last day, default today"
    },
    "range": {
      "enum": [
        "week",
        "month"
      ],
      "type": "string",
      "description": "default week"
    }
  }
}

get_now

What is happening now: running sessions with attention shares, the timer, today's main step, today's minutes, the streak and a one-line nudge.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {}
}

get_path

Milestones with kind, progress (recorded value or steps done), pace (ahead/on_pace/behind) and their steps. current_milestone_id is the one to work on.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {}
}

get_plan

The plan for a day (default today).

read-only

Argument	Type	Description
date	string	YYYY-MM-DD in the user's timezone

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    }
  }
}

get_planning_context

Everything needed to plan a day: goal and pace, next_steps, yesterday's summary and undone items, week balance, days since a hard lever. Defaults to tomorrow. The agent plans; then call set_plan.

read-only

Argument	Type	Description
date	string	YYYY-MM-DD in the user's timezone

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    }
  }
}

get_post_draft

The day's progress post drafted from the record (aim and progress, main step done or not, minutes on the aim and on hard work, routines, comebacks), at most 300 characters, ending with aimyear.com; and per network whether it is ready, already posted, or skipped because the user already posted there that day. Posts nothing. Pro.

read-only

Argument	Type	Description
date	string	YYYY-MM-DD in the user's timezone

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    }
  }
}

get_routines

Routines: small steps that repeat on fixed weekdays, e.g. "talk with one person on Reddit", or that count up to a number a week, e.g. "talk to 5 people a week", each with an optional bad-day minimum. The server adds them to each matching day's plan, so every device and agent sees the same checks. With no routines yet, returns ready-made starters for the aim's area to offer as they are.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {}
}

get_settings

Timezone, where reminders go (desktop or mobile), timer settings, and which networks get progress posts (post_to).

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {}
}

list_agents

Agents connected to this AimYear account (Claude, ChatGPT, Claude Code, the AimYear app…): name, client_id, when it connected and when it was last active. current marks the one calling.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {}
}

list_devices

Which devices can receive reminders, and when each was last seen.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {}
}

list_sessions

Sessions in a date range (default the last 7 days), with ids, optionally filtered by area or project.

read-only

Argument	Type	Description
to	string	YYYY-MM-DD in the user's timezone
area	string
from	string	YYYY-MM-DD in the user's timezone
projectId	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    },
    "area": {
      "enum": [
        "health",
        "relations",
        "work",
        "money",
        "happiness"
      ],
      "type": "string"
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    },
    "projectId": {
      "type": "string"
    }
  }
}

list_social_accounts

Connected networks (handle, since when), which of them get progress posts, and whether the user has Pro. Never returns any key or password.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {}
}

next_steps

Open steps of the current milestone, hard-lever steps first: the candidates for today's main step.

read-only

Argument	Type	Description
count	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "count": {
      "type": "integer",
      "maximum": 20,
      "minimum": 1
    }
  }
}

record_progress

Record the current value of the goal metric ("I now have 4 customers"), or of a countable milestone when milestoneId is given ("I have talked to 7 people"). For a done-or-not goal, 1 marks it done. One value per date: calling again for the same date corrects it. Says when the target is reached; a countable milestone that reaches its target is done.

Argument	Type	Description
date	string	YYYY-MM-DD in the user's timezone
value*	number
milestoneId	string	a countable milestone instead of the goal

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "value"
  ],
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    },
    "value": {
      "type": "number"
    },
    "milestoneId": {
      "type": "string",
      "description": "a countable milestone instead of the goal"
    }
  }
}

set_commitments

Replace the list of recurring weekly commitments. days are ISO weekdays 1=Mon..7=Sun; use timesPerWeek instead when there are no fixed days. Pass existing ids to keep them.

destructive

Argument	Type	Description
commitments*	array

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "commitments"
  ],
  "properties": {
    "commitments": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "title",
          "minutes"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "area": {
            "enum": [
              "health",
              "relations",
              "work",
              "money",
              "happiness"
            ],
            "type": "string",
            "description": "required for kind commitment"
          },
          "days": {
            "type": "array",
            "items": {
              "type": "integer",
              "maximum": 7,
              "minimum": 1
            }
          },
          "kind": {
            "enum": [
              "commitment",
              "overhead",
              "window"
            ],
            "type": "string",
            "description": "commitment = unavailable and belongs to an area; overhead = unavailable and belongs to no area (sleep, meals, hygiene, moving between places); window = time available for focus work. Default commitment."
          },
          "note": {
            "type": "string"
          },
          "start": {
            "type": "string",
            "pattern": "^\\d{1,2}:\\d{2}$",
            "description": "HH:MM local time"
          },
          "title": {
            "type": "string"
          },
          "assumed": {
            "type": "boolean",
            "description": "true when the number is your inference, not something the user stated"
          },
          "minutes": {
            "type": "integer",
            "maximum": 9007199254740991,
            "minimum": 1
          },
          "projectId": {
            "type": "string"
          },
          "timesPerWeek": {
            "type": "integer",
            "maximum": 7,
            "minimum": 1
          },
          "usableForWork": {
            "type": "boolean",
            "description": "committed but still workable (waiting, being a passenger)"
          },
          "insideWindowId": {
            "type": "string",
            "description": "id of a kind:window entry this commitment is carved out of, so the window is not counted twice"
          }
        }
      }
    }
  }
}

set_day_mode

Tracking for a day: full (everything recorded, the default) or off (timer and reminders only, nothing stored, no plan required).

Argument	Type	Description
date	string	YYYY-MM-DD in the user's timezone
mode*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "mode"
  ],
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    },
    "mode": {
      "enum": [
        "full",
        "off"
      ],
      "type": "string"
    }
  }
}

set_goal

Save the yearly goal, or replace it with the next one. Rejects with problems[] if the rubric fails. Keeps levers and projects. area is which of the five life areas the goal belongs to.

destructive

Argument	Type	Description
why	string
area	string	default money
kind	string	count (default): a number from baseline to target, e.g. "15 paying customers". done: a one-time result checked yes or no, e.g. "launch v2 in the stores"; no metric, baseline or target, progress is the share of stages done
title*	string
metric	string	required for kind count
target	number	required for kind count
baseline	number	value today; required for kind count
deadline*	string	YYYY-MM-DD in the user's timezone

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "title",
    "deadline"
  ],
  "properties": {
    "why": {
      "type": "string"
    },
    "area": {
      "enum": [
        "health",
        "relations",
        "work",
        "money",
        "happiness"
      ],
      "type": "string",
      "description": "default money"
    },
    "kind": {
      "enum": [
        "count",
        "done"
      ],
      "type": "string",
      "description": "count (default): a number from baseline to target, e.g. \"15 paying customers\". done: a one-time result checked yes or no, e.g. \"launch v2 in the stores\"; no metric, baseline or target, progress is the share of stages done"
    },
    "title": {
      "type": "string"
    },
    "metric": {
      "type": "string",
      "description": "required for kind count"
    },
    "target": {
      "type": "number",
      "description": "required for kind count"
    },
    "baseline": {
      "type": "number",
      "description": "value today; required for kind count"
    },
    "deadline": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    }
  }
}

set_levers

Replace the list of levers: the recurring kinds of goal work. At least one must be kind=hard (the work the user avoids). keywords/repos are hints for classifying sessions from their task text. Pass existing ids to keep them.

destructive

Argument	Type	Description
levers*	array

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "levers"
  ],
  "properties": {
    "levers": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "kind"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "enum": [
              "hard",
              "comfortable"
            ],
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "repos": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "examples": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

set_milestones

Replace the list of 2–6 ordered milestones under the goal, each countable (metric and target) or measured by its steps, with a due date before the goal deadline. Pass each existing id, or that milestone's steps are deleted. To change one milestone, use edit_milestone.

destructive

Argument	Type	Description
milestones*	array

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "milestones"
  ],
  "properties": {
    "milestones": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "title",
          "due"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "due": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "YYYY-MM-DD in the user's timezone"
          },
          "kind": {
            "enum": [
              "count",
              "steps"
            ],
            "type": "string",
            "description": "count: progress is a recorded value against target (\"talk to 20 people\"); steps: progress is steps done (\"implement the onboarding flow\"), no metric needed. Default: count when metric and target are given, else steps; an existing milestone keeps its kind"
          },
          "title": {
            "type": "string"
          },
          "metric": {
            "type": "string"
          },
          "target": {
            "type": "number"
          }
        }
      }
    }
  }
}

set_plan

Replace the plan for a day. Exactly one item must have isMainStep=true (the step toward the goal), ideally linked by stepId from next_steps and on a hard lever. Warns when no item is on a hard lever. Other items: paid work, family, workout, etc. with their area. Items that stay keep their done state.

destructive

Argument	Type	Description
date	string	YYYY-MM-DD in the user's timezone
items*	array

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "items"
  ],
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "title",
          "area"
        ],
        "properties": {
          "area": {
            "enum": [
              "health",
              "relations",
              "work",
              "money",
              "happiness"
            ],
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "stepId": {
            "type": "string"
          },
          "leverId": {
            "type": "string"
          },
          "projectId": {
            "type": "string"
          },
          "isMainStep": {
            "type": "boolean"
          },
          "estimateMin": {
            "type": "integer",
            "maximum": 9007199254740991,
            "minimum": -9007199254740991
          }
        }
      }
    }
  }
}

set_projects

Replace the list of other projects (paid work, other products, life routines), so their sessions count as other work or life, not goal work. Pass the whole list: leave one out to remove it, change its name or hints to edit it. Pass existing ids to keep them.

destructive

Argument	Type	Description
projects*	array

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "projects"
  ],
  "properties": {
    "projects": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "area"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "area": {
            "enum": [
              "health",
              "relations",
              "work",
              "money",
              "happiness"
            ],
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "repos": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

set_routines

Replace the list of routines: small steps that repeat on fixed weekdays. From today on, each one appears as a plan item on its days; tick it with edit_plan_item, skip it for one day with delete_plan_item. set_plan keeps them. days are ISO weekdays 1=Mon..7=Sun, default every day. perWeek makes it a weekly count: each tick adds its count (default 1), and once the week reaches perWeek it leaves the plan until Monday. Link it to the goal with leverId. minimum is the small version for a bad day ("read one thread" for "talk to one person"). Pass existing ids to keep them.

destructive

Argument	Type	Description
routines*	array

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "routines"
  ],
  "properties": {
    "routines": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "title",
          "area"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "area": {
            "enum": [
              "health",
              "relations",
              "work",
              "money",
              "happiness"
            ],
            "type": "string"
          },
          "days": {
            "type": "array",
            "items": {
              "type": "integer",
              "maximum": 7,
              "minimum": 1
            }
          },
          "title": {
            "type": "string"
          },
          "leverId": {
            "type": "string"
          },
          "minimum": {
            "type": "string",
            "description": "the bad-day version, e.g. \"read one thread\""
          },
          "perWeek": {
            "type": "integer",
            "maximum": 9007199254740991,
            "minimum": 1,
            "description": "weekly count, e.g. 5 for \"talk to 5 people a week\""
          },
          "projectId": {
            "type": "string"
          },
          "estimateMin": {
            "type": "integer",
            "maximum": 9007199254740991,
            "minimum": -9007199254740991,
            "description": "default 15"
          }
        }
      }
    }
  }
}

set_settings

Change any of: timezone (IANA name, e.g. Europe/Madrid; it sets where each day starts and ends), workplace for reminders, stand-up interval workMin, breakMin, longBreakEvery, longBreakMin, standup on/off, post_to (networks for progress posts).

Argument	Type	Description
post_to	array	which connected networks get the day's progress post (the app sets it); [] for none
standup	boolean
workMin	integer
breakMin	integer
timezone	string
workplace	string
longBreakMin	integer
longBreakEvery	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "post_to": {
      "type": "array",
      "items": {
        "enum": [
          "wip",
          "bluesky"
        ],
        "type": "string"
      },
      "description": "which connected networks get the day's progress post (the app sets it); [] for none"
    },
    "standup": {
      "type": "boolean"
    },
    "workMin": {
      "type": "integer",
      "maximum": 120,
      "minimum": 5
    },
    "breakMin": {
      "type": "integer",
      "maximum": 60,
      "minimum": 1
    },
    "timezone": {
      "type": "string"
    },
    "workplace": {
      "enum": [
        "desktop",
        "mobile"
      ],
      "type": "string"
    },
    "longBreakMin": {
      "type": "integer",
      "maximum": 60,
      "minimum": 5
    },
    "longBreakEvery": {
      "type": "integer",
      "maximum": 10,
      "minimum": 1
    }
  }
}

split_attention

Set attention weights of the running sessions at once, e.g. {"abc": 0.7, "def": 0.3}. Applies to the whole session. For a finished session use edit_session.

Argument	Type	Description
shares*	object

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "shares"
  ],
  "properties": {
    "shares": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "number",
        "minimum": 0
      }
    }
  }
}

start_session

Start a session of work and, if none is running, the timer. Returns a verdict: ok | stop | plan_first. On "stop" NO session is created: relay the message, ask the user; if they insist, call again with override=true. Several sessions may run at once (two terminals) and share attention by weight. Apps replaying a queued start pass op_id, their own session_id and start_at; an agent leaves all three out.

Argument	Type	Description
area	string	default work
task*	string	what you are about to do, specific
op_id	string	for apps replaying queued requests: an id the app minted before its first attempt and reuses on retries, so the write is applied once and a retry gets the first answer back. Do not invent one; an agent calling interactively leaves it out
itemId	string	plan item id
stepId	string	path step id
weight	number	attention weight vs other sessions at the same time, default 1
leverId	string
minutes	integer	length for a down timer, or the stand-up interval for an up timer

stop_session

Stop a running session with a summary and outcome. Pass session_id from get_now; without it, only this connection's single running session is stopped, never another one. The timer keeps running for other sessions. outcome=done completes the linked plan item or path step. Without end_at or op_id it refuses a session that already ended: use edit_session for that. With end_at (apps delivering a stop queued offline) a second stop on the same session is merged, whatever order they arrive in: the earliest end wins, done wins over any other outcome, the first summary stays and a different later one goes to the notes; the answer says applied: ended | shortened | recorded.

Argument	Type	Description
op_id	string	for apps replaying queued requests: an id the app minted before its first attempt and reuses on retries, so the write is applied once and a retry gets the first answer back. Do not invent one; an agent calling interactively leaves it out
end_at	string	when the work ended as ISO 8601 with offset, e.g. 2026-10-20T14:05:00+02:00. For apps delivering a request queued offline; an agent calling interactively leaves it out. Rejected before the session start; a clock more than 2 minutes ahead of the server is taken as now
outcome*	string
summary*	string
session_id	string	from get_now; required with op_id or end_at
attention_share	number

stop_timer

Stop the timer ("pause", "stop", "stand up") and every running session with it. There is no paused state: resuming starts a new session. Pass summary and outcome to save them on the sessions it closes, or call stop_session first. Returns the break length.

destructive

Argument	Type	Description
outcome	string	default partial
summary	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "outcome": {
      "enum": [
        "done",
        "partial",
        "abandoned"
      ],
      "type": "string",
      "description": "default partial"
    },
    "summary": {
      "type": "string"
    }
  }
}

summarize_day

Full summary of a day: wall and attention minutes per area, classification and lever, sessions, gaps, overlaps, overrides.

read-only

Argument	Type	Description
date	string	YYYY-MM-DD in the user's timezone

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD in the user's timezone"
    }
  }
}

summarize_week

A week, Monday to Sunday (to today for the current week): main-step days, goal share, hard share, area balance, overrides, streak, milestone pace.

read-only

Argument	Type	Description
date	string	any day of the week, default today

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "any day of the week, default today"
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "task"
  ],
  "properties": {
    "area": {
      "enum": [
        "health",
        "relations",
        "work",
        "money",
        "happiness"
      ],
      "type": "string",
      "description": "default work"
    },
    "task": {
      "type": "string",
      "description": "what you are about to do, specific"
    },
    "op_id": {
      "type": "string",
      "maxLength": 128,
      "minLength": 8,
      "description": "for apps replaying queued requests: an id the app minted before its first attempt and reuses on retries, so the write is applied once and a retry gets the first answer back. Do not invent one; an agent calling interactively leaves it out"
    },
    "itemId": {
      "type": "string",
      "description": "plan item id"
    },
    "stepId": {
      "type": "string",
      "description": "path step id"
    },
    "weight": {
      "type": "number",
      "minimum": 0,
      "description": "attention weight vs other sessions at the same time, default 1"
    },
    "leverId": {
      "type": "string"
    },
    "minutes": {
      "type": "integer",
      "maximum": 120,
      "minimum": 5,
      "description": "length for a down timer, or the stand-up interval for an up timer"
    },
    "override": {
      "type": "boolean",
      "description": "true only after the user confirmed past a stop"
    },
    "start_at": {
      "type": "string",
      "description": "when the work began as ISO 8601 with offset, e.g. 2026-10-20T14:05:00+02:00. For apps delivering a request queued offline; an agent calling interactively leaves it out. Rejected before the session start; a clock more than 2 minutes ahead of the server is taken as now"
    },
    "direction": {
      "enum": [
        "up",
        "down"
      ],
      "type": "string",
      "description": "up (default) counts elapsed time and runs until stopped, with a stand-up reminder every workMin; down is a fixed timebox, for a break"
    },
    "exclusive": {
      "type": "boolean",
      "description": "true: nothing else was happening then"
    },
    "projectId": {
      "type": "string"
    },
    "workplace": {
      "enum": [
        "desktop",
        "mobile"
      ],
      "type": "string"
    },
    "session_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 6,
      "description": "for apps: the session id the app minted itself. Create-if-absent: if a session with this id exists it is returned and nothing is created. An agent leaves it out; the server mints the id"
    }
  }
}