Docs / Reference / Full user guide

Full user guide

Every panel, the island, the tray, settings files and the API table.

Written for v2.1.0 · updated 2026-11-20

The current release is v2.0.0 (TiroAgents), for Windows, macOS and Linux.

This guide covers every part of the app. For install, update and uninstall see the README. For a link index see RESOURCES.md.

Contents: What it is - Starting - The dashboard - Giving work - Approvals - The team - Goals, Today and Reports - The office - Scheduler - Agent history - Tiro on your desktop - The island - Tray - Settings files - API reference - Keyboard and accessibility - Troubleshooting - FAQ - Security notes

What it is

TiroAgents is a pixel office for your own Claude Code agents. Tiro is the manager. You give Tiro a task, it plans, asks you to approve each specialist it wants to hire, files reports, and remembers things in an Obsidian-style vault of plain Markdown notes. The office itself uses no tokens; models only run while an agent works, through your own Claude Code install and plan.

Starting

The dashboard

The header is one row of pills: manager auto-approval, usage and plan limits, reports, and the switches menu. Below it is the office, with the Today panel, the Team panel and the detail pane over it.

The whole office with the eight specialists at work, the goal board on the left and the status bar on top

Giving work

  1. Type a task in the dispatch box (for example "Review the README and list any wrong claims") and send it. It is added to today's board as a goal and Tiro is told about it.
  2. Tiro reads the board, plans, and works. For anything it cannot do itself it asks you to hire a specialist (see Approvals).
  3. When a goal produces findings, Tiro files a report and marks the goal done.
  4. Tiro keeps going between turns while Autopilot is on and goals are open. Switch Autopilot off if you want it to work only when you send something.

You can also message any agent directly from its detail pane, interrupt a running turn, or Reset Tiro's conversation (goals and reports stay; Tiro starts a fresh session next time).

Approvals

There are two kinds, and both show on the dashboard and in the island.

Hire approvals (strict hiring gate). Starting a specialist with the Agent tool needs your approval. Tiro sends a request with the specialist, the goal and a reason; a card appears with Approve and Deny. One approval buys exactly one hire of that type and expires after 10 minutes. Requests are refused automatically if hiring is switched off, the goal is not open, the reason is too short, 8 specialists are already working, or that specialist is already on the team and idle (Tiro is told to reuse it). Pending cards and unused approvals are cleared when Tiro's session ends or resets or when hiring is switched off. Details: Agents and memory.

Tiro asking to hire Warden, with the goal, the reason and Approve hire and Deny buttons

Tool approvals. Tiro and the agents run on your own Claude Code configuration: your allow, deny and ask rules, permission mode, hooks and settings decide what happens. Only a request Claude Code itself would ask you about shows up (in the dashboard detail pane and the island), with the full tool input and Claude Code's own choices: Yes, Yes, and don't ask again (offered only when Claude Code suggests a rule; it writes that same rule to the same settings file Claude Code would), and No, optionally with a note telling Claude what to do instead. Nothing is edited, auto-approved or timed out into an answer; a prompt waits until you answer. Questions Claude asks (the multiple-choice question tool) appear as a question card in the island. Terminal sessions still ask in their own dialog when no tab is open. See Permissions and Claude Code parity.

Security Guard

On top of your Claude Code permissions, the Security Guard asks before something risky happens: secrets leaving this computer (a curl that uploads a .env, a git push whose files include a key, a secret written to OneDrive), downloaded scripts or startup entries, credential stores and environment dumps, screen or clipboard capture, and the first action after a web page or mail contained instructions aimed at the AI. It shows the matched rule, the files (values masked), the destination and whether the payload is exact or estimated, and you answer Yes, No, or No with a note. It can only ask; it never allows or blocks anything. Turn categories to ask, log or off in the Breaker box (Security Guard) or the island Settings; turning one down needs a confirmation window only the app can open, and an agent that edits kiro.json cannot weaken it. The Audit log button lists what was asked or noted. Details, limits and the full list of prompts: Security Guard.

The team

Tiro leads eight specialists:

NameRoleModel
PixelFrontend engineersonnet
ForgeBackend engineersonnet
WardenSecurity revieweropus
ProbeQA and test engineersonnet
AtlasDeep researcheropus
CabalanResearcherhaiku
TallyTask checker and organizerhaiku
ScribeSOP and document writersonnet

Each specialist is one person with one desk. If a second agent of the same type ever starts, it is drawn as a labelled "helper" of the first.

Renaming. In the Team panel you can give Tiro and each specialist a display name of up to 20 characters. A name cannot equal another agent's current or default name. Blank resets to the default. Renames only change what is shown: ids, desks and memory folders stay the same, so history stays with the agent.

The Team panel: a role card and a rename box per agent. Forge shows the name Ember being typed as a rename example; it is not saved until you press Rename

SOPs. In the filing cabinet, Tiro's brief and each specialist's instructions are editable notes. Edits apply from Tiro's next turn. Each specialist's note can set description, tools and model in its frontmatter.

Goals, Today and Reports

The Reports bookshelf with the daily summary and three demo reports, with PDF and Excel export

The office

The world is isometric with five zones: Tiro's glass office (top left), the focus area with eight desks, the garden and park (top right, with a gate), the playroom (bottom right) and a utility strip (bottom left). The garage and Scheduler station sit beside the playroom.

The desk area: each specialist at their own desk with a name tag and status dot

Tiro, the office manager, at the desk in the glass office

The garden and park, with agents thinking on benches

The playroom with idle agents on the sofa and at the arcade

Hovering a desk draws a yellow outline that follows its shape

Scheduler station

The Scheduler station is the garage and the mailbox. Click either to open a read-only panel showing the last check time, the count of tasks and needs found, when Tiro was last updated, the next check, a note, and the item list (title, kind, time). The panel reads ~/.claude/agent-office/scheduler.json through POST /api/scheduler. It says "no data yet" until the scheduler job has written the file.

The garage and the scheduler character with its "Checked ... 3 items" bubble

The Scheduler and Garage panel: last mail check, items found, next check and subject-only items

The job, its feed file and its mailbox setting are in Scheduler. TiroAgents has no mail access built in.

Agent history

The Agent history button (bottom left) opens a three-pane browser: agents on the left, that agent's tasks (with search) in the middle, and the task summary on the right with the transcript path and the agent's folder paths. Every hire starts in a fresh context; the only thing carried over is that agent's own memory folder. Folders are under ~/.claude/agent-office/agents/tiro/<type>/{memory,history}. Summaries are redacted for secrets. See Agents and memory.

Agent history: every agent with task counts and Forge's past tasks

One past task opened: summary, transcript reference and the final report

Power saver

The animated parts of TiroAgents (the office canvas, Tiro's window, the island) can use a surprising share of a GPU if they redraw at full speed all day. Power saver (on by default) keeps them calm: the office redraws about 30 times a second only while characters move or you interact with it, about 8 times a second for seated animations, about twice a second when nothing is happening, and not at all while the window is hidden or minimised. Tiro holds still after a few idle seconds and blinks now and then; the island stops its idle breathing while collapsed. Anything that changes (new data, a hover, a click) shows immediately.

Turn it off with the Power saver button next to Labels in the office, or in the island's Settings, to get the old constant motion. prefers-reduced-motion is always honoured. The setting is stored as islandSettings.powerSaver in kiro.json and mirrored in the browser as ao.powerSaver.

Tiro on your desktop

Tiro lives as a small always-on-top character on your desktop. Click to chat, give tasks and approve requests; double-click to open the office. Its mood follows the work: idle, typing, waving a flag when you are needed, confetti when a goal is done, asleep when paused. Hide or show it from the tray.

The small Tiro desktop character with its greeting bubble

The island

The island is the notch: a small panel fixed to the top centre of the screen, flat against the top edge with rounded bottom corners. It is small when closed and opens into a wide, shallow panel with tabs.

Tabs. Each tab is the full version of a card on Home.

Notes, timers and counters are kept on this PC only, in notch-store.json.

Calendar link. The Calendar tab reads one private calendar link (an ICS address). It is read only: nothing is ever written to your calendar.

Game mode (Windows). When a game is in front, the closed notch shows <fps> FPS · <gpu>% GPU · <temp>°C · <cpu>% CPU (a value that cannot be read is left out, never shown as 0), and opening it lands on Performance. A waiting approval then only adds its count to that line instead of opening the notch over your game; open the notch to answer it.

Settings (the gear on the right of the tab row):

Not in this version: calendar sign-in (Microsoft 365 or Google accounts), editing events, syncing notes, timers or counters to other devices, a clipboard history, file shelf, launcher, weather, volume or brightness indicators, app notifications, an overlay inside exclusive-fullscreen games, and frame rate on macOS or Linux.

Tray

The tray menu has: Open office, Show notch (checkbox), Island (mode, chime on approval or done, display choice), Show Tiro, Start with Windows (packaged app only) and Quit TiroAgents.

Settings files

All state is under ~/.claude/agent-office/ (your home folder). Nothing here needs editing by hand, but it is plain JSON and safe to inspect.

File or folderWhat it holds
bridge.jsonServer port and the terminal bridge key (opens /bridge/* only). The UI key is never stored.
kiro.jsonDesktop and island preferences: agentNames, islandMode, islandMute, islandDisplay, islandSettings (including notchEnabled, notchShortcut, look, homeCards, gameMode and games), updateAuto, tiroIdleMinutes, limitsProbeMinutes, hidden, optional schedulerMailbox.
notch-store.jsonThe notch's notes, timers, counters and Pomodoro lengths.
calendar-link.binThe private calendar link, encrypted with the OS key storage (only when you added one).
switches.jsonBreaker box switches.
manager.jsonTiro auto-approval on or off.
manager-session.jsonId of Tiro's current session (one per day).
goals.jsonToday's board.
credits.jsonExtra-usage credit log.
scheduler.json, scheduler-seen.json, inbox-feed.jsonScheduler status, its dedupe list, and its input feed.
agents/tiro/...Per-agent memory and history.

Reports, daily notes, memory and SOPs live in your vault (Agent Office/ folder). Claude Code transcripts stay in ~/.claude/projects. Environment variables: AGENT_OFFICE_PORT (server port), AGENT_OFFICE_TEAM_ONLY=1 (show only Tiro and its team), AGENT_OFFICE_MAILBOX (scheduler mailbox) and CLAUDE_CODE_PATH (where Claude Code is).

API reference

The dashboard, island and tools talk to a local HTTP API. Every call to /api/... is a POST with a JSON body, authenticated by the UI session cookie (there is no key in URLs or headers; the bridge key only opens /bridge/*). Decision endpoints (/api/decide, /api/hire/decide, /api/switch, /api/send, /api/task, /api/sops/save, /api/boss-reset) also need the per-session nonce in the x-nonce header. Not signed in returns 401, a missing nonce 403, a wrong Host header 403. GET /api/stream is a Server-Sent Events feed of the live snapshot. The bridge plugin also uses /bridge/ask and /bridge/poll.

EndpointBodyPurpose
/api/stream (GET)noneLive snapshot (agents, goals, approvals, usage).
/api/send{id, text}Message an agent session.
/api/interrupt{id}Interrupt a running turn.
/api/decide{askId, decision, always?, message?, answers?}Answer a Claude Code permission prompt (allow, deny, terminal); always writes Claude Code's suggested rule, message tells Claude what to do instead, answers answers a question card.
/api/task{text}Add a goal and tell Tiro.
/api/goal{id, action}accept, dismiss, done or reopen a goal.
/api/bossnoneNudge Tiro to read the board.
/api/boss-resetnoneForget Tiro's conversation (goals and reports stay).
/api/hire/decide{id, approve, note?}Approve or deny a hire request.
/api/rosternoneThe eight specialists with names, roles and models.
/api/names, /api/names/set, /api/names/reset{key, name} / {key?}Read, set or reset display names.
/api/agents/overview, /api/agents/tasks, /api/agents/task{key, q?} / {key, id}Per-agent history browser.
/api/schedulernoneScheduler status (read-only).
/api/reports, /api/report, /api/daily{file} for oneList and read reports and the daily summary.
/api/memory/graph, /note, /delete, /linkby note nameBrowse and edit vault notes.
/api/sops, /api/sops/save{name, text}Read and edit SOPs.
/api/switch{name, on}Flip a breaker box switch.
/api/rack, /api/limitsnoneServer stats; plan limits.
/api/tidynoneClear finished goals and idle desks.

Also: GET /print/report, /print/daily, /export/report.xlsx and /export/daily.xlsx (key required) produce printable pages and Excel files.

Keyboard and accessibility

Troubleshooting

ProblemWhat to try
Dashboard is blankReload. If it persists, check the app is up to date (older builds before 1.2.5 could not load their scripts under the security policy).
"Connecting" banner staysThe server is not running. Restart TiroAgents. If another copy holds the port, quit it first.
401 "not signed in" from a scriptThe API needs the UI session cookie, which only the desktop app (or the one-time sign-in link of a standalone run) has. The bridge key in bridge.json opens /bridge/* only.
Tiro does nothingCheck the Breaker box (Tiro on, plan guard not paused) and that Claude Code is installed and logged in.
Far more (or fewer) prompts than beforePrompts now follow your Claude Code permission rules and mode; edit your allow, deny and ask rules or permissions.defaultMode (Permissions and Claude Code parity).
Hire card never appearsHiring switch may be off, or Tiro asked for a goal that is not open.
Scheduler says "no data yet" or "No mail feed file yet"The job has not run, or nothing writes inbox-feed.json. See Scheduler.
SmartScreen warns on installThe build is not code-signed. Compare the SHA-256 with the one on the GitHub release.
Update refusedThe feed has no SHA-256, or the hash did not match.

FAQ

Does the office cost tokens? No. Only agents working cost tokens, and only on your Claude Code plan.

Can an agent hire without asking me? No. Every hire needs your one-shot approval.

Where is my data? On your machine: ~/.claude/agent-office, your vault, and Claude Code's own ~/.claude/projects. Model calls go to Anthropic through Claude Code, as in the terminal.

Does it read my email? No. The scheduler reads a local feed file that you must produce yourself.

Can I rename agents and keep their history? Yes; history follows the type, not the name.

Why a vendored React and Babel? So the dashboard works under a strict security policy and fully offline; the fonts are vendored too.

Security notes

The server is local only, requires a random key, checks the Host header and sends a strict Content-Security-Policy. Electron windows are sandboxed with context isolation and no Node integration. Installs and updates are https only and SHA-256 verified. Windows and macOS builds are unsigned. Full list in the README.

Background work and memory

TiroAgents keeps its background work small. Two settings in kiro.json tune it:

What you may notice: an old Claude Code session that you resume can take up to a minute to show up on a desk; the live view updates once every 3 seconds while all windows are hidden; the first message after a long break starts Tiro a moment later because its session is resumed. To re-measure on your own machine see tools/perf/README.md.