{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/vamoose-banner.png\" alt=\"vamoose\" width=\"100%\">\n</p>\n\n<h1 align=\"center\">vamoose</h1>\n\n<p align=\"center\">Calendar workflows, minus the tedium.</p>\n\n<p align=\"center\">\n  <a href=\"https://vamoose.dev\"><img\n    src=\"https://img.shields.io/badge/docs-vamoose.dev-d9a441\" alt=\"Docs at vamoose.dev\"></a>\n  <a href=\"https://github.com/dcadolph/vamoose/releases\"><img\n    src=\"https://img.shields.io/github/v/release/dcadolph/vamoose\" alt=\"Latest release\"></a>\n  <img src=\"https://img.shields.io/github/go-mod/go-version/dcadolph/vamoose\" alt=\"Go version\">\n  <a href=\"LICENSE\"><img\n    src=\"https://img.shields.io/badge/license-MIT-blue\" alt=\"License\"></a>\n</p>\n\nThe moose does the paperwork. You go to the beach.\n\nFour calendar backends behind one workflow engine that branches, approves, waits, recurs, and files real leave with your HR system, driven from your terminal, Claude, Slack, or a local dashboard, and authorable by an AI agent over MCP. Every run is recorded, and the daemon resumes exactly where it left off after a crash. Install with `brew install dcadolph/tap/vamoose`.\n\nCalendar busywork is death by a thousand cuts: create the hold marked free, invite\nyour manager, Slack them for the yes, go back in and add the team one by one, add a\nsecond blocked event so your own calendar says away, then file the leave in the HR\nportal. vamoose turns those chores into **workflows** it runs for you and advances\nin the background. Time off is the flagship workflow, and you can define your own.\n\n<p align=\"center\"><img src=\"assets/vamoose-demo.gif\" alt=\"vamoose demo\" width=\"100%\"></p>\n\n## Two minutes to running\n\n```sh\nbrew install dcadolph/tap/vamoose\nvamoose login --provider google   # sign in; Outlook and iCloud setup in docs\nvamoose off next week --watch     # hold the dates, invite your manager\nvamoose daemon                    # advances the workflow when the manager accepts\nvamoose app                       # or watch and run everything from a dashboard\n```\n\nThat is the whole flow: the hold shows as free so it blocks nobody, your manager's\ncalendar accept is the approval, and the daemon notifies your team the moment it lands.\n\n## How it works\n\n1. **Declare.** A workflow is ordered steps in JSON: create a hold, gate on approval,\n   branch on the outcome, wait, message a channel, file the leave. Time off ships built\n   in; author your own in a file, on the dashboard's workflow canvas, or through an AI\n   agent.\n2. **Run.** Drive it from the terminal, Claude, Slack, or `vamoose app`, against\n   Microsoft Graph, Google, iCloud, or any CalDAV host. Same workflow, any backend.\n3. **Advance.** The daemon moves runs forward on its own: your manager accepting the\n   invite is the approval signal (no separate approval product), timeouts and waits\n   fire on the clock, recurring schedules re-run, and every step lands in the run\n   history.\n\nThe built-in **pto** workflow is the flagship: hold shown **free**, manager approves by\naccepting, team added as **optional attendees** so nobody's calendar gets blocked.\n`request`, `check`, and `promote` are fronts over its steps. See [Workflows](#workflows).\n\n<p align=\"center\"><img src=\"assets/vamoose-builder.png\" alt=\"The workflow canvas\" width=\"720\"></p>\n\nFour backends ship behind one provider interface: Microsoft Graph (Outlook,\nMicrosoft 365, and Teams), Google Calendar, Apple iCloud, and any standard CalDAV host.\nPick one with `--provider` or the `VAMOOSE_PROVIDER` environment variable, and every\ncommand works the same across them. Approval detection is the one exception: iCloud\nsends invites but does not report accept/decline over CalDAV, so on iCloud you promote\nby hand. See [providers](docs/providers.md).\n\n## Why not just calendar rules?\n\nYou can rig a version of this with one calendar's rules or a saved email. vamoose\nearns its keep the moment you have more than one account:\n\n- **One brain for every account.** The same workflows, commands, and setup whether\n  you are on Google, Outlook, or Microsoft 365. Learn it once, not once per client.\n- **No rebuilding per client.** Native rules live inside one app and stop at its edge.\n  Define a workflow once and point it at any backend with `--provider`.\n- **No drift.** Change your time-off flow in one place. Hand-built rules drift the day\n  you update Outlook and forget Gmail.\n- **Workflows are files, not clicks.** JSON you can read, diff, share, version, and\n  dry-run, instead of a settings panel you rebuild by hand on every machine.\n- **Runs where you already are.** The CLI, Claude, and Slack, not one vendor's web UI.\n\n## Install\n\nmacOS and Linux:\n\n```sh\nbrew install dcadolph/tap/vamoose\n```\n\nWindows:\n\n```powershell\nscoop bucket add vamoose https://github.com/dcadolph/scoop-vamoose\nscoop install vamoose\n```\n\nDocker (for [hosting](docs/hosting.md)):\n\n```sh\ndocker run --rm ghcr.io/dcadolph/vamoose:latest version\n```\n\nOr with Go 1.26 or newer:\n\n```sh\ngo install github.com/dcadolph/vamoose@latest\n```\n\nZips and tarballs for every platform are on the\n[releases page](https://github.com/dcadolph/vamoose/releases).\n\nNew to vamoose? The [Quickstart](docs/quickstart.md) takes you from zero to a first approved\nhold in a few minutes.\n\n## Setup\n\nSet one calendar backend and export its credentials, then run `vamoose doctor` to check the\nsetup. Every backend, including iCloud and any CalDAV host, is covered in [providers](docs/providers.md).\n\n### Microsoft 365 / Outlook\n\nvamoose talks to Microsoft Graph as you, using the OAuth device-code flow.\n\n1. Register an application in the Microsoft Entra admin center (single tenant is\n   fine). Enable **Allow public client flows** so device code works.\n2. Grant these delegated permissions and admin consent:\n   - `User.Read`, `User.Read.All` (read your manager and their direct reports)\n   - `Calendars.ReadWrite` (create and update the hold)\n   - `MailboxSettings.ReadWrite` (reserved for the out-of-office reply)\n   - `offline_access` (stay signed in between runs)\n3. Export the settings:\n\n```sh\nexport VAMOOSE_CLIENT_ID=<application-client-id>\nexport VAMOOSE_TENANT=<tenant-id-or-organizations>\nexport VAMOOSE_TIMEZONE=America/Chicago\n```\n\nThe first command opens a device-code prompt. Tokens are cached under your user\nconfig directory and refreshed automatically after that. Run `vamoose whoami`\nfirst to confirm auth and directory access before creating any holds.\n\n### Google Calendar\n\nFor `--provider google`, create an OAuth **desktop app** client in the Google Cloud\nconsole, enable the Google Calendar API, then sign in:\n\n```sh\nexport VAMOOSE_PROVIDER=google\nexport VAMOOSE_GOOGLE_CLIENT_ID=<oauth-desktop-client-id>\nexport VAMOOSE_GOOGLE_CLIENT_SECRET=<oauth-desktop-client-secret>\nvamoose login\n```\n\n`login` opens your browser for consent on a local loopback address, then caches and\nrefreshes tokens after that. Two things catch people out. Consent is denied until you add\nthe signing-in account under Google Auth Platform, Audience, Test users. And while the app\nsits in Testing status, Google expires its refresh tokens after seven days, so `login`\ncomes back around once a week. Both are covered step by step, with a troubleshooting\ntable, in [the Google guide](https://vamoose.dev/providers.html#google-calendar).\n\nGoogle Calendar has no directory, so pass your approver with `--manager` and set your team\nwith `vamoose team set`.\n\n### Apple iCloud\n\nFor `--provider icloud`, create an app-specific password at appleid.apple.com and export:\n\n```sh\nexport VAMOOSE_PROVIDER=icloud\nexport VAMOOSE_ICLOUD_USERNAME=you@icloud.com\nexport VAMOOSE_ICLOUD_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx\n```\n\niCloud sends invites but does not report approvals over CalDAV. Recover them with the macOS\nEventKit helper or a Slack Approve button, or promote by hand. See [providers](docs/providers.md).\n\n### Any CalDAV host\n\nFor `--provider caldav`, point at any standard CalDAV server, such as Fastmail or Nextcloud:\n\n```sh\nexport VAMOOSE_PROVIDER=caldav\nexport VAMOOSE_CALDAV_URL=https://caldav.fastmail.com\nexport VAMOOSE_CALDAV_USERNAME=you@fastmail.com\nexport VAMOOSE_CALDAV_PASSWORD=xxxx-xxxx-xxxx-xxxx\n```\n\n### HR system, for balance and leave filing\n\nCalendar setup is enough for holds, coverage, and approvals. Reading your remaining\nbalance with `vamoose balance`, and filing approved time off as real leave, both need an\nHR system as well. Skip this section if you only want the calendar side.\n\nPoint at BambooHR directly:\n\n```sh\nexport VAMOOSE_BAMBOOHR_SUBDOMAIN=<your-bamboohr-subdomain>\nexport VAMOOSE_BAMBOOHR_API_KEY=<bamboohr-api-key>\nexport VAMOOSE_BAMBOOHR_EMPLOYEE_ID=<your-employee-id>\n```\n\nOr post to any HR system through a webhook:\n\n```sh\nexport VAMOOSE_BALANCE_WEBHOOK_URL=https://hr.example.com/balance\nexport VAMOOSE_LEAVE_WEBHOOK_URL=https://hr.example.com/leave\nexport VAMOOSE_HRIS_EMPLOYEE_ID=<your-employee-id>\n```\n\nWithout one of these, `vamoose balance` exits reporting that no HR system is configured.\nRun `vamoose doctor` to see which parts are set.\n\n## Usage\n\n```sh\n# Confirm auth and directory access work in your tenant.\nvamoose whoami\n\n# Create the hold and invite your manager. Manager is resolved from the directory.\nvamoose request --start 2026-07-20 --end 2026-07-24 --subject \"Out: beach week\"\n\n# Or request time off from a plain-language phrase. It reports the working days,\n# skipping weekends and configured holidays.\nvamoose off next week --subject \"Out: beach week\"\n\n# Just the afternoon.\nvamoose off tomorrow --half pm\n\n# Who else is off that week, and what do you have left?\nvamoose coverage next week\nvamoose balance\n\n# See whether your manager has approved.\nvamoose check\n\n# Once approved, fan out to the team as optional attendees.\nvamoose promote\n\n# Changed plans? Cancel the hold and notify everyone.\nvamoose cancel\n\n# Or let check promote the moment approval lands.\nvamoose check --promote\n\n# Hands-off: watch for approval and let the daemon auto-promote in the background.\nvamoose off next week --watch\nvamoose daemon\n\n# Run the daemon unattended (prints a launchd or systemd manifest to install).\nvamoose service\n\n# See what every hold did and who approved it.\nvamoose history\n\n# Open the local dashboard: run workflows, author them, act on holds.\nvamoose app\n```\n\nTimes accept `YYYY-MM-DD` for all-day holds or RFC3339 for partial days. Pass\n`--manager you@work.com` to skip directory lookup, or `--dry-run` on request to\npreview without sending. `off` also accepts explicit `--start`/`--end`.\n\n## Quick actions\n\nNot everything needs approval:\n\n```sh\n# Block yourself out of office over a range, no approval or fanout.\nvamoose away --start 2026-07-20 --end 2026-07-24\n\n# Create a quick event, optionally inviting others.\nvamoose event --start 2026-07-20T15:00:00Z --end 2026-07-20T15:30:00Z \\\n  --subject \"1:1\" --attendees boss@work.com\n```\n\n## Workflows\n\nA workflow is an ordered list of steps that vamoose runs and the daemon advances.\nThe request-approve-promote flow above is the built-in **pto** workflow. Run a\nworkflow by name, with a date phrase or explicit `--start`/`--end`:\n\n```sh\nvamoose run pto next week --watch\nvamoose run notify-only next week\nvamoose run away --start 2026-07-20 --end 2026-07-24\nvamoose workflows            # list the available workflows\n```\n\nThree workflows ship built in:\n\n| Name          | Steps                                | Use                               &nbsp; |\n| ------------- | ------------------------------------ | ---------------------------------------- |\n| `pto`         | hold shown free, approve, notify     | Time off that a manager approves.        |\n| `notify-only` | hold shown free, notify              | Tell the team, no approval needed.       |\n| `away`        | out-of-office block                  | Personal out of office, no fanout.       |\n\nDefine your own by dropping a JSON file in `~/.config/vamoose/workflows/<name>.json`.\nA file there overrides a built-in of the same name.\n\n```json\n{\n  \"name\": \"team-heads-up\",\n  \"description\": \"Hold shown free, tell the team, no approval.\",\n  \"steps\": [\n    { \"verb\": \"hold\", \"showAs\": \"free\" },\n    { \"verb\": \"notify\", \"team\": \"optional\" }\n  ]\n}\n```\n\nThen `vamoose run team-heads-up next week`. Steps use these verbs:\n\n- `hold` creates the event and invites the manager when an `approve` step follows.\n- `approve` waits for the manager to accept the invite.\n- `notify` adds the team as optional attendees.\n- `away` marks you out of office with no attendees.\n- `event` creates a plain event, with attendees from `--attendees`.\n- `cancel` deletes the hold.\n\nA workflow starts with exactly one creating step (`hold`, `away`, or `event`).\nApproval waits on the manager that only a `hold` invites, so an `approve` step\nneeds a `hold`, and only `notify` may follow approval. With `--watch`, the hold is\nrecorded and `vamoose daemon` runs the remaining steps once the manager accepts.\n\n## Defining your team\n\nBy default `promote` derives your team from the directory: your manager's direct\nreports, minus you. That assumption breaks if you are the manager, your team is a\ndistribution list, or the directory is sparse. Set an explicit team instead:\n\n```sh\nvamoose team set alex@work.com jordan@work.com sam@work.com\nvamoose team list     # show the current team\nvamoose team clear    # revert to the directory\n```\n\nThe list is stored as JSON under your user config directory\n(`team.json`). When it is set, `promote` and `whoami` use it; when it is absent,\nthey fall back to the directory.\n\n## Claude (MCP)\n\n`vamoose mcp` speaks the Model Context Protocol over stdio, exposing the commands as\ntools so Claude can book time off for you. Point an MCP client at the binary:\n\n```json\n{ \"mcpServers\": { \"vamoose\": { \"command\": \"vamoose\", \"args\": [\"mcp\"] } } }\n```\n\nAuthenticate once first with `vamoose whoami`; the server reuses the cached token.\n\n## Docs\n\nThese guides are also on the site at [vamoose.dev](https://vamoose.dev).\n\n| Guide                                    | What                                                   &nbsp; |\n| ---------------------------------------- | ------------------------------------------------------------ |\n| [Quickstart](docs/quickstart.md)         | Zero to a first approved hold in a few minutes.              |\n| [Concepts](docs/concepts.md)             | Holds, approval, workflows, and the three adapters.          |\n| [Commands](docs/commands.md)             | Every command, flag, and environment variable.               |\n| [Workflows](docs/workflows.md)           | Built-in and custom workflows: branching, delays, guards.    |\n| [Providers](docs/providers.md)           | Microsoft Graph, Google, iCloud, and CalDAV setup.           |\n| [Slack](docs/slack.md)                   | Drive vamoose from Slack, with approval buttons.             |\n| [Claude](docs/claude-guide.md)           | The MCP server and the skill.                                |\n| [Hosting](docs/hosting.md)               | Run it as a service, secrets encrypted at rest.             |\n| [Architecture](docs/architecture.md)     | Surfaces, core, and adapters.                                |\n\n## Roadmap\n\n- Live-prove per-user Slack against a real workspace, then drop its experimental label.\n- A signed, notarized native desktop app wrapping the dashboard.\n- Auto-promote via Graph change-notification webhooks instead of polling.\n- Set the scheduled out-of-office auto-reply for the time-off window.\n- More HR systems behind the leave seam, as users ask.\n\n## More tools\n\n- [kibble](https://github.com/dcadolph/kibble), test your README's install steps in a clean container\n- [preen](https://github.com/dcadolph/preen), split a messy working tree into clean, atomic git commits\n- [slop-chop](https://github.com/dcadolph/slop-chop), strip the AI tells out of your writing\n- [whodar](https://github.com/kordloom/whodar), find who to talk to about X across your work tools\n\n## License\n\nMIT (see [LICENSE](LICENSE)). Use it, change it, ship it, sell it. No conditions\nbeyond keeping the copyright notice.\n",
  "bytes": 16011,
  "sha": "9382b61cdde743be960587ee9600fc89de761b8253a4f1947f81885bea0f298a",
  "repo_slug": "dcadolph/vamoose",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dcadolph_vamoose_e463c4c0/readme"
}