# Roadstar

> Roadstar is a staff of AI agents for one small-business owner. These docs are for those agents: how chats, threads, hand-offs, routines and the owner's yes work, every tool with its input, result, limits and whether it needs the owner's yes, and worked examples from one design studio.

## How to read these docs

- Every page is markdown at its address with `.md` added, as linked below. A page's plain address returns markdown too when the request sends `Accept: text/markdown`.
- [Every page in one file](https://docs.roadstar.app/llms-full.txt). [Every tool as JSON](https://docs.roadstar.app/tools.json): inputs, result types, the owner's yes, limits and models.
- Inside Roadstar, the `help` tool group searches and reads these pages.
- Tool pages are written from the code each time the docs are built, so they match the tools as deployed. Call tools by the names shown, such as `mail.send`, through `use_tool`.
- The examples are Fernhill Studio, Sam Rivera's design studio, and its agents Client desk, Proposal writer and Bookkeeper.

## Start

- [Roadstar for agents](https://docs.roadstar.app/index.md): What Roadstar is, where an agent runs in it, and how to read these docs.

## How it works

- [Agents and the chart](https://docs.roadstar.app/how-it-works/agents.md): Roadstar and the agents it makes, job descriptions, the chart, models and budgets.
- [Chats and threads](https://docs.roadstar.app/how-it-works/chats-and-threads.md): An agent's chat sends work and answers, in at most four steps; its threads do the work.
- [Hand-offs](https://docs.roadstar.app/how-it-works/hand-offs.md): Giving work to another agent: the packet, where the answer goes, and how deep work can be handed on.
- [Finding and using tools](https://docs.roadstar.app/how-it-works/tools.md): How a thread finds and runs tools, what comes back, and how changes reach the owner's Home with Undo.
- [The owner's yes](https://docs.roadstar.app/how-it-works/the-owners-yes.md): Which actions are checked before they run, what the check reads, go / ask / stop, the reasons, and how to ask.
- [Home and asks](https://docs.roadstar.app/how-it-works/home-and-asks.md): What the owner sees on Home, how an agent asks, where the answer comes back, and cards.
- [Routines and skills](https://docs.roadstar.app/how-it-works/routines-and-skills.md): Work an agent does on its own, on a schedule or when something happens, and skills, its how-tos for one kind of work.
- [Notes, About and memory](https://docs.roadstar.app/how-it-works/notes-and-memory.md): What an agent keeps: its notes on how the owner likes work done, Roadstar's About, and its memory of each conversation.
- [Macs and outside AI apps](https://docs.roadstar.app/how-it-works/computers-and-apps.md): Agents that run in Claude Code or Codex on the owner's Mac, and AI apps that connect to Roadstar's MCP server.

## Tools

- [All tools](https://docs.roadstar.app/tools.md): Every tool group and agent tool, how many tools each has, and where each agent tool is offered.
- [Contacts](https://docs.roadstar.app/tools/contacts.md): The people the business deals with, shared by all the owner's agents. 11 tools.
- [Companies](https://docs.roadstar.app/tools/companies.md): The businesses the owner deals with, each with its people, Context and a timeline of conversations. 11 tools.
- [Projects](https://docs.roadstar.app/tools/projects.md): Projects group the business's docs, tables and contacts. 4 tools.
- [Docs](https://docs.roadstar.app/tools/docs.md): Docs agents write and keep for the owner, such as proposals, briefs, checklists and recurring reports. 5 tools.
- [Mail](https://docs.roadstar.app/tools/mail.md): The owner's Gmail, read live, with drafting and sending. 4 tools.
- [Files](https://docs.roadstar.app/tools/files.md): The owner's Google Drive and OneDrive, read live, with Google Docs and Sheets writing. 15 tools.
- [Calendar](https://docs.roadstar.app/tools/calendar.md): The owner's Google Calendar, read live, and time held on it. 2 tools.
- [Books](https://docs.roadstar.app/tools/books.md): Invoices and what customers owe, read live from the owner's QuickBooks. 2 tools.
- [Workspace](https://docs.roadstar.app/tools/workspace.md): Your own folder on a small computer with Python, Node and a shell. 5 tools.
- [Templates](https://docs.roadstar.app/tools/templates.md): Agents, teams, departments and skills someone already made, ready to add. 4 tools.
- [Web](https://docs.roadstar.app/tools/web.md): Search the open web and read pages. 2 tools.
- [Connected apps](https://docs.roadstar.app/tools/integrations.md): The apps the owner has connected or could connect, and a card that asks them to connect one. 2 tools.
- [Search](https://docs.roadstar.app/tools/search.md): One search over the copy of the owner's mail, files and meetings, and the workspace's own docs, tables and contacts. 2 tools, where search is on.
- [Help](https://docs.roadstar.app/tools/help.md): These docs, from inside Roadstar. 2 tools.

## Agent tools

- [browse, find, use](https://docs.roadstar.app/tools/catalog.md): browse_tools, find_tools and use_tool, how a thread reaches every tool group.
- [Team](https://docs.roadstar.app/tools/team.md): hand_off, remember, make_agent and change_agent, for working with the owner's other agents.
- [Threads](https://docs.roadstar.app/tools/threads.md): start_thread, message_thread, read_thread and close_thread, how a chat sends work to its threads.
- [Routines](https://docs.roadstar.app/tools/routines.md): triggers and skills, for work an agent does on its own and how it does one kind of work.
- [Memory](https://docs.roadstar.app/tools/memory.md): zoom_memory and message_date, for reading back further in an agent's own memory.

## Use cases

- [A new client enquiry](https://docs.roadstar.app/use-cases/new-client-enquiry.md): Client desk answers Juniper Dental's request for a quote, Proposal writer prices it from the rate card, and Sam approves it before it goes.
- [Chasing overdue invoices](https://docs.roadstar.app/use-cases/overdue-invoices.md): Bookkeeper's Monday routine reads QuickBooks, emails Ortiz Bakery about an overdue invoice, and sets a follow-up.
- [Making an agent](https://docs.roadstar.app/use-cases/make-an-agent.md): Sam asks Roadstar for help with proposals, and Roadstar makes Proposal writer from a job description and hands it the first piece of work.
- [Filling Contacts from mail](https://docs.roadstar.app/use-cases/contacts-from-mail.md): Client desk works out who Sam writes to most from sent mail, reads their signatures, and saves them as contacts.
- [A proposal from the template](https://docs.roadstar.app/use-cases/proposal-from-template.md): Proposal writer copies the proposal template in Drive, fills it in for Ortiz Bakery, and hands Sam the link.
- [A month of hours](https://docs.roadstar.app/use-cases/hours-spreadsheet.md): Bookkeeper totals October's hours per client from the timesheet in the workspace, and saves the summary to Drive as a Google Sheet.
- [Booking a kickoff call](https://docs.roadstar.app/use-cases/kickoff-call.md): Client desk finds a free hour in Sam's calendar, holds it, offers it to Dana at Juniper Dental, and sets a follow-up.

## Reference

- [Limits](https://docs.roadstar.app/reference/limits.md): Steps per turn, groups per browse, tools per find, open threads, packet sizes, hand-off depth and agents per owner.
- [Models](https://docs.roadstar.app/reference/models.md): The models an agent can think with, when to pick each, their prices, and thinking levels.
- [Errors](https://docs.roadstar.app/reference/errors.md): What a failed tool returns, what the check returns when it holds an action back, and what to do next.

## Optional

- [Research pages](https://docs.roadstar.app/tools/pages.md): Optional. Question and thesis pages that Roadstar's research writer makes. 6 tools.
- [Comments](https://docs.roadstar.app/tools/comments.md): Optional. Comments on research pages. 2 tools.
- [Research tables](https://docs.roadstar.app/tools/tables.md): Optional. Tables whose rows agents find and whose cells they fill from sources. 6 tools.
- [Filings](https://docs.roadstar.app/tools/filings.md): Optional. Public companies' SEC filings. 2 tools.
- [Newsfeed](https://docs.roadstar.app/tools/newsfeed.md): Optional. The stories the workspace's newsfeed follows. 1 tool.