{"id":"firstmate","repo":"gpambrozio/paseo-plugins","url":"https://github.com/gpambrozio/paseo-plugins/tree/main/firstmate","package":"@gpambrozio/paseo-firstmate","npm":{"package":"@gpambrozio/paseo-firstmate","version":"0.1.1","integrity":"sha512-MDm4GCJ+ogqmKeeYpbCsm0iPSrw7qNlU7woxkEcBXPdQphnqtbctSvRpY/S9sC3zft8y9WgDDGm5b1U+i1JOxg==","publishedAt":"2026-09-24T23:53:08.549Z","downloadsLast30Days":0},"name":"firstmate","description":"Paseo plugin: talk to one first mate agent that runs a crew of Paseo agents in their own worktrees, with a live board of the crew","categories":["orchestration","productivity"],"platforms":[],"caveats":["Requires Paseo 0.9.0 or newer on both the daemon and the device running the app","Paseo's agent tools must be turned on (they ship off); the panel offers a one-press switch","The first mate needs a capable model: Claude Sonnet or better, or a comparable Codex model"],"images":["https://raw.githubusercontent.com/gpambrozio/paseo-plugins/572a27b127fb37808600172a6ed761c01b3f15fc/firstmate/docs/demo.webp","https://raw.githubusercontent.com/gpambrozio/paseo-plugins/572a27b127fb37808600172a6ed761c01b3f15fc/firstmate/docs/landed.png","https://raw.githubusercontent.com/gpambrozio/paseo-plugins/572a27b127fb37808600172a6ed761c01b3f15fc/firstmate/docs/board.png","https://raw.githubusercontent.com/gpambrozio/paseo-plugins/572a27b127fb37808600172a6ed761c01b3f15fc/firstmate/docs/watch.png"],"themes":[],"health":{"manifestValid":true,"hasReadme":true,"hasLicense":true,"hasTests":true,"hasTypecheckScript":true,"updatedRecently":true},"scannedAt":"2026-09-25T05:34:34.531Z","addedAt":"2026-09-25T05:03:15Z","npmSecurity":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-25T05:23:25.331Z","version":"0.1.1","integrity":"sha512-MDm4GCJ+ogqmKeeYpbCsm0iPSrw7qNlU7woxkEcBXPdQphnqtbctSvRpY/S9sC3zft8y9WgDDGm5b1U+i1JOxg=="},"path":"firstmate","version":"0.1.1","security":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-25T05:23:25.331Z","commit":"572a27b127fb37808600172a6ed761c01b3f15fc"},"license":"MIT","paseoVersionRequirement":">=0.9.0","descriptionNodes":[{"type":"text","text":"Paseo plugin: talk to one first mate agent that runs a crew of Paseo agents in their own worktrees, with a live board of the crew"}],"caveatNodes":[[{"type":"text","text":"Requires Paseo 0.9.0 or newer on both the daemon and the device running the app"}],[{"type":"text","text":"Paseo's agent tools must be turned on (they ship off); the panel offers a one-press switch"}],[{"type":"text","text":"The first mate needs a capable model: Claude Sonnet or better, or a comparable Codex model"}]],"manifest":{"id":"firstmate","description":"Talk to one first mate; it runs a crew of agents in their own worktrees","requirements":{"paseo":">=0.9.0"}},"repoMeta":{"stars":9,"defaultBranch":"main","pushedAt":"2026-09-25T05:30:19Z"},"owner":{"login":"gpambrozio","avatarUrl":"https://avatars.githubusercontent.com/u/672135?v=4"},"installNotesHtml":"
paseo plugin install npm:@gpambrozio/paseo-firstmate\n
\n

To hack on it, clone the repository and run paseo plugin install \"$PWD\" from this folder after\nnpm install and npm run typecheck. Everything the plugin writes into the first mate's home — its\ncharter, the records it starts with, the home's icon — is in templates/, as the files it becomes;\npaseo plugin reload firstmate puts a change to work.

","limitationsNotesHtml":"","readmeText":"# FirstMate\n\nA [Paseo](https://paseo.sh) plugin: talk to one agent, ship with a crew.\n\nYou talk to a single agent — the **first mate** — and it runs the crew for you. Every task goes to a\n**worker**: its own Paseo agent, in its own git worktree, so parallel work on one repository never\ncollides. The first mate writes each worker's instructions, supervises it to the end, and brings you\nfinished pull requests, investigation findings, and only the decisions that are really yours. You are\nthe captain.\n\nA **FirstMate** panel in the sidebar puts the conversation with the first mate beside a board of its\ncrew — Queued, Working, Blocked, Parked, Done, Failed and Idle — with each worker's last word on what\nit is doing and a link to its pull request.\n\n![A 30-second loop of FirstMate at work, zooming in on each step: one message to the first mate asks\nfor a dark mode toggle and a speed-conversion fix in a small web app; two cards appear in Queued and\nmove to Working, each worker in its own worktree; one worker is watched live, its commands and edits\nscrolling past; each card reaches Done with \"Captain's call: land branch …\" beside the first mate's\nreport; the message \"land both\" sends them to main, and the first mate's Bearings report, with both\ncards marked landed, closes it out.](docs/demo.webp)\n\nThis is a Paseo-native take on [firstmate](https://github.com/kunchenguid/firstmate) by Kun Chen, by\nway of [ABorakati/paseo-firstmate](https://github.com/ABorakati/paseo-firstmate). Where those run the\ncrew in terminal sessions and supervise it with shell scripts, this one uses nothing but Paseo: the\nworkers are ordinary Paseo agents you can open, read and type into like any other, in worktrees Paseo\nmanages, and Paseo itself tells the first mate when a worker finishes, fails or asks for permission.\nThere is nothing else to install.\n\n## What you need\n\n- Paseo **0.9.0 or newer**, on the daemon and on the device running the app.\n- **Paseo's agent tools turned on.** They are how the first mate starts its workers and hears back from\n them, and Paseo ships with them off. The panel says so and turns them on with one press; it is the\n *Agent tools* switch in the FirstMate settings too.\n- A capable model for the first mate. It spends its day reading records and deciding who does what,\n and a small model gets the tools wrong. Claude Sonnet or better, or a comparable Codex model, works.\n- The `paseo` command on the daemon machine, which a Paseo install puts there. It is used to find the\n plugin's own files, to interrupt a worker from the board, and to name the first mate's project in\n Paseo's sidebar.\n\n## Install\n\n```bash\npaseo plugin install npm:@gpambrozio/paseo-firstmate\n```\n\nTo hack on it, clone the repository and run `paseo plugin install \"$PWD\"` from this folder after\n`npm install` and `npm run typecheck`. Everything the plugin writes into the first mate's home — its\ncharter, the records it starts with, the home's icon — is in `templates/`, as the files it becomes;\n`paseo plugin reload firstmate` puts a change to work.\n\n## Getting started\n\n1. Open **FirstMate** in the sidebar, pick the first mate's model, and press **Launch the first mate**.\n If you already started an agent for the job, adopt it from the list below the button instead.\n2. Tell it about a project: \"the web app is at ~/code/web — ship through pull requests\". It keeps a\n registry, so you only say this once.\n3. Ask for work: \"fix the flaky login test and add dark mode\". Two workers appear on the board, each in\n its own worktree. Minutes later:\n\n > PR ready for review, captain: https://github.com/you/web/pull/42 (fix the flaky login test - risk: low - CI green)\n\n4. \"Merge it.\" The first mate never merges without your word, unless you have told it a project may.\n\n## Talking to the first mate\n\n- The chat in the panel — Enter sends and Shift+Enter starts a new line, as in Paseo — or open the\n first mate in Paseo for the whole session, every tool call and its output. The chat follows new\n messages while you are at the bottom; scroll up to read, and the round button at the bottom brings\n you back.\n- **How full its memory is** — the ring at the end of the chat's buttons shows how much of the first\n mate's context window is used, the way Paseo's own chat does: amber from 70%, red past 90%. Hover\n over it, or tap it on a phone, for the share and the token counts.\n **Compact** has it summarise its conversation to free room, as `/compact` does in Paseo. **Restart**\n starts a new first mate from scratch, with the same model and settings, after asking you. Both wait\n until the first mate is between turns. On a restart its records carry over, the old conversation stays in\n Paseo's history, and workers already running keep going — the new first mate checks on them\n regularly, since Paseo tells only the agent that started a worker when it finishes.\n- **Questions it asks you** — which option, whether to go ahead, a plan to approve — appear in the\n chat as a form you answer there, the same as in the first mate's own tab.\n- **`/fm `** in any composer sends the message to the first mate, from wherever you are.\n- **`/bearings`** — where everything stands, in four sections: what needs your call, what landed,\n what is under way, and what is next. `/bearings file` also writes it to a dated report in the first\n mate's home; `/bearings include PRs` checks the live pull requests too.\n- **`/ahoy`** — what happened since you last spoke, then every open decision, one at a time, with a\n recommendation.\n- *Bearings* and *Ahoy* are also buttons above the chat, and *FirstMate: bearings* is in ⌘K.\n\n![After the voyage: the first mate's Bearings report in the chat — Captain's Call: nothing needs your\naction; Recently Landed: the knots fix and the dark mode toggle, both landed on main; Underway and\nCharted Next: nothing — beside the board, where both cards sit in Done marked \"landed\".](docs/landed.png)\n\n## The board\n\n![The FirstMate panel mid-voyage: the first mate's chat on the left explaining the two workers it sent\noff; on the right the board, with \"Add a dark mode toggle to the header\" in Working, its card open on\nWatch, Steer, Interrupt, Relaunch and End, and \"Fix knots-to-km/h conversion and add a test\" in Done,\nreading \"Done: ready in branch fm/fix-knots-kmh\" and \"Captain's call: land branch\nfm/fix-knots-kmh\".](docs/board.png)\n\nEach card is a worker, a backlog item, or both. Press one for its actions:\n\n- **Watch** — the worker's card beside everything it is doing, live, in place of the board: the brief\n it was given, its reasoning, each command and file it touched (press one for what it ran and what\n came back), its plan, and its replies. Anything it is waiting on — a question, a permission — is\n answered there. The chat with the first mate stays beside it; **Crew** takes you back to the board,\n and **Open in Paseo** shows the worker's whole session.\n- **Steer** — a word straight to the worker. It counts as coming from you, and the first mate is told\n what you said and what the worker answered.\n- **Interrupt** — stops the worker's current turn.\n- **Relaunch** — asks the first mate for a fresh worker in the same worktree, with your note. The work\n on disk carries over; the conversation does not.\n- **End** — archives the worker. Its workspace and worktree are left exactly as they are.\n\n![Watching a worker: the chat with the first mate stays on the left; in the board's place, the worker's\ncard with its actions beside its live transcript — the brief it was given, then Read, Edit and Shell\nrows for each step (npm test among them), its notes between them, and a spinner on the step under\nway.](docs/watch.png)\n\nA column with nobody in it is hidden, so the board shows only what has workers in it. On a wide\nscreen up to three columns sit side by side; past three they take two rows, with the extra one in the\nsecond row. Columns fold to a strip and move with the arrows in their headers, and the split between\nchat and board drags. The layout is remembered, including where a hidden column goes when it fills\nagain.\n\nOpening the panel counts as looking at the first mate: when it has finished a turn, its workspace in\nPaseo's sidebar turns to done, as it would if you had opened the first mate itself. One waiting on\nyour permission stays flagged until you answer.\n\nA worker's workspace and session also get a **FirstMate** tab showing its card, with a box for telling\nthe first mate something about it.\n\n## The first mate's home\n\nThe **Files** view — next to the crew board, or its own tab on a phone — shows everything in the home\nand opens any text file for editing, with a preview for Markdown. Cmd/Ctrl+S saves on a desktop. The\nfirst mate writes these files too, so a save never silently replaces its newer version: you are told\nit changed, and choose to load theirs or overwrite it with yours.\n\nThe first mate lives in a directory of its own — by default inside Paseo's plugin data, or anywhere you\nchoose in the settings. It writes there and nowhere else; your projects are read-only to it, and every\nchange is a worker's job.\n\nIn Paseo's sidebar the first mate's project and workspace are called **FirstMate** rather than after\nthe folder, and the project shows FirstMate's ship, from `icon.svg` in the home — Paseo picks up a\nproject's icon from its folder. Rename either, replace the file, or upload an icon in the project's\nsettings, and your choice is kept.\n\n- `AGENTS.md` — its charter: how it takes requests, briefs and supervises workers, and talks to you.\n Written from `data/charter.md` every time the plugin starts or the first mate is launched, so do not\n edit it here.\n- `data/charter.md` — **the charter itself, yours to change.** It starts as FirstMate's own charter, and\n while you leave it alone, a new version of the plugin brings its improvements. Once you edit it, your\n version is kept; if FirstMate's charter changes after that, the board tells you, **Compare** opens the\n new one beside yours (`data/charter.new.md`) and **Done** marks yours up to date. Saving it in the panel\n rewrites `AGENTS.md` at once; the first mate reads it at its next session, or when you ask it to re-read\n its charter. The note at the top lists the `{{placeholders}}` filled in for you, notes between `` are left out, and an empty file goes back to FirstMate's charter.\n- `data/captain.md` — **your standing orders.** Anything you write here outranks the charter (except\n its hard rules: it never writes to a project, never merges without your word, never throws away\n unlanded work). Never overwritten.\n- `data/opening.md` — **the first thing a new first mate is told**, when you launch it and when you\n restart it. Change the words, the language, or what it should do before anything else; keep asking\n it to read `AGENTS.md` and take the helm, which is what makes it a first mate. Notes between `` are left out, a restart adds a note of its own after yours about the first mate before, and\n an empty file means FirstMate's own wording. Never overwritten.\n- `data/projects.md` — the project registry, and how each one ships:\n - `direct-PR` — the worker opens a pull request ready for review;\n - `reviewed-PR` — the worker also reviews its own diff, runs the full test suite and waits for CI;\n - `local-only` — no remote; the worker leaves a clean branch, and the first mate lands it when you say.\n - `+yolo` after the mode lets the first mate merge green work on that project without asking.\n- `data/backlog.md` — every task, in flight, queued and done. The board reads it.\n- `data//brief.md`, `data//report.md` — each worker's instructions, and an investigation's\n findings.\n\nBecause all of it is on disk, a restart is a non-event: the first mate reads its records, checks them\nagainst the live crew, and carries on.\n\n## Settings\n\n**Settings › Plugins › FirstMate** — or the gear in the panel's header, or *FirstMate settings* in ⌘K.\n\n- **First mate** — which agent it is, and *Release* to forget it (the agent keeps running).\n- **Home directory** — where the first mate lives. It can be moved only while no first mate is aboard.\n- **Crew model and mode** — what every worker runs, unless you tell the first mate otherwise for a\n task. \"Let the first mate choose\" gives workers its own model.\n- **Agent tools** — Paseo's switch, described above.\n- **Refresh every** — how often the board polls.\n\n## Limitations\n\n- **Nothing is merged or thrown away without you.** Workers push their own branches and open pull\n requests, but merging needs your word (or `+yolo` on that project), and a worker's worktree is only\n cleaned up after its work has landed.\n- **A worker you prompt by hand** in its own tab is not watched by anyone until the first mate next\n reviews the fleet (it keeps a half-hourly check while work is under way). Steer from the board\n instead, and the first mate hears about it.\n- **The first mate's model, thinking and mode** are changed from its own tab in Paseo, not from the\n board.\n- **Attachments** — images, files — go to the first mate from its own tab, not from the panel's chat.\n- **Watch shows a worker's latest activity**, not its whole history; a long-running worker's earlier\n work is in its own session in Paseo.\n- It does not reproduce firstmate's second mates, relay to X and Discord, away mode, or the\n `no-mistakes` pipeline (`reviewed-PR` stands in for the last).\n- The panel has not yet been checked on a phone.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n"}