{ "version": 1, "site": "https://perched.fyi", "updated": "2026-10-23", "collections": [ { "category": "use-cases", "title": "Use cases", "heading": "Your workflow. Your agents. One place to check.", "description": "Explore Perch for developers, founders, agencies and parallel coding sessions, with dedicated Claude Code, Codex and Cursor workflows.", "lead": "Find the workflow that looks like yours. Each page explains where Perch helps, what the integration supports and what stays in your existing development process.", "url": "https://perched.fyi/use-cases/" }, { "category": "guides", "title": "Guides", "heading": "A clear next step.", "description": "Practical Perch guides for setup, agent compatibility, answering, keyboard shortcuts, privacy, troubleshooting and local sticky notes.", "lead": "Connect your first session, understand a request or work through a missing state. Start with the task you want to complete.", "url": "https://perched.fyi/guides/" }, { "category": "alternatives", "title": "Compare", "heading": "Find the right place for Perch.", "description": "Compare Perch with manual terminal checks, notifications and shared agent dashboards. Understand the tradeoffs without unverified product rankings.", "lead": "Compare ways of managing your attention around coding agents. Start with the problem you have: checking tabs, missing a handoff or needing a shared view.", "url": "https://perched.fyi/alternatives/" }, { "category": "blog", "title": "Blog", "heading": "Notes on working with agents.", "description": "Original Perch articles about parallel coding agents, deliberate approvals, local status monitoring and reducing the checking loop.", "lead": "Practical ways to keep agents moving while staying close enough to review their work. Written by the Perch team.", "url": "https://perched.fyi/blog/" }, { "category": "glossary", "title": "Glossary", "heading": "The words, in plain language.", "description": "Understand agent hooks, sessions, tool approvals, local-first software, human-in-the-loop decisions and context switching in Perch.", "lead": "Short definitions with the context that matters in a Perch workflow, and a useful next step for each term.", "url": "https://perched.fyi/glossary/" } ], "pages": [ { "category": "use-cases", "slug": "developers", "title": "A coding-agent monitor for developers on Mac", "description": "See Claude Code, Codex and Cursor activity at the edge of your Mac. Review requests, keep notes and return to the coding session that needs you.", "lead": "Your editor, terminal and browser are all open. Your agent is in one of them, waiting for a decision. Perch puts session status at the edge of your Mac so you can find the next thing that needs you without checking every window.", "sections": [ { "title": "Keep implementation and review moving", "paragraphs": [ "A coding session alternates between work the agent can do and decisions only you should make. Perch shows that distinction with three states: a blue ring while work is running, an amber dot when a session needs you, and a green check when a turn finishes.", "The shelf groups sessions into Needs you, Working and Recent. Use it to choose which session to open. A finished turn is a cue to review the result; it does not mean the code is correct." ] }, { "title": "A practical development loop", "steps": [ "Give the agent a bounded task and agree on how you will check its result.", "Continue your own implementation or review while it works.", "When a session needs you, read the request. Respond from Perch where supported, or open the agent’s app.", "Inspect the completed change and run the checks appropriate to the task." ] }, { "title": "Know what each integration can answer", "paragraphs": [ "With answering enabled, Claude Code supports tools, questions, plans and replies. Codex supports allow, deny and replies. Cursor supports replies after a turn finishes; its passive hooks do not expose awaiting-permission status. Answering is off by default, and every answer has two seconds to undo." ], "links": [ { "label": "Read the compatibility guide", "href": "/guides/agent-compatibility/" } ] }, { "title": "Keep the next thought nearby", "paragraphs": [ "Leave a review reminder or the next prompt in one of Perch’s ten local sticky notes. Copy it when you are ready. Perch does not automatically dispatch notes or turn them into a task queue." ] } ], "faqs": [ { "q": "Does Perch write code?", "a": "No. Your agents do the work. Perch displays activity and passes along the answers you choose." }, { "q": "Which Macs are supported?", "a": "The current offer is for Apple silicon Macs running macOS 14 or later." } ], "related": [ "/guides/getting-started/", "/use-cases/parallel-agents/", "/blog/monitor-multiple-coding-agents/" ], "updated": "2026-10-23", "url": "https://perched.fyi/use-cases/developers/", "markdown": "https://perched.fyi/content/use-cases/developers.md" }, { "category": "use-cases", "slug": "founders", "title": "Keep agents moving while you run the business", "description": "See when a coding agent needs a decision while you work on product, customers and the rest of your business. A local workflow with Perch for Mac.", "lead": "A small product team often means one person moving between implementation, customer feedback and product decisions. Perch keeps the state of your local coding sessions visible while you do the work around the code.", "sections": [ { "title": "Notice the decision, then make it deliberately", "paragraphs": [ "An agent waiting for permission and an agent still working need different responses from you. Perch’s screen-edge tab helps you tell them apart. Open the shelf when something needs attention and read the request before deciding.", "You might ask Claude Code to update onboarding, then move to a customer email. If Claude needs a choice about the flow, you can review its numbered question in Perch when answering is enabled. You still make the product decision." ] }, { "title": "Build a handoff you can evaluate", "steps": [ "Give the agent one small change with a clear outcome.", "Write your acceptance criteria in a working document or local note.", "Respond to questions and approvals after checking their scope.", "Review the finished work in the project before shipping." ] }, { "title": "A companion for your Mac", "paragraphs": [ "Perch does not host agents or supply a shared company dashboard. It works alongside sessions on your Mac. Your agent subscriptions and usage are separate.", "Actions vary by provider. Cursor supports activity and replies after a turn, rather than in-card tool approvals. Codex supports approvals and replies, while Claude Code also supports questions and plans. Use the compatibility guide to check your workflow." ] } ], "faqs": [ { "q": "Can I use Perch from my phone?", "a": "Perch does not provide phone or remote access. It works on your Mac." }, { "q": "Does Perch approve requests automatically?", "a": "No. Answering is opt-in, and Perch sends only the answer you choose." } ], "related": [ "/guides/agent-compatibility/", "/guides/sticky-notes/", "/blog/human-in-the-loop-coding/" ], "updated": "2026-10-23", "url": "https://perched.fyi/use-cases/founders/", "markdown": "https://perched.fyi/content/use-cases/founders.md" }, { "category": "use-cases", "slug": "agencies", "title": "Keep client coding sessions in view on your Mac", "description": "Track local coding sessions across client projects with Perch. Check project context before reviewing an agent request or a completed handoff.", "lead": "Client work can leave you with several projects and several agents open at once. Perch gives the sessions on your Mac a shared place to show their status, so you can choose the right one before responding.", "sections": [ { "title": "Check the project before the request", "paragraphs": [ "When sessions belong to different clients, the first question is which project is asking. Perch keeps status alongside project context and lets you rename sessions locally. Clear names make it easier to spot a familiar command in the wrong project.", "The shelf groups attention by state. Start a review in Needs you, leave running tasks in Working, and find completed turns in Recent." ] }, { "title": "A review routine for parallel client work", "steps": [ "Give each session a distinct project and a bounded task. Use separate working copies when changes might overlap.", "Name sessions so the client and purpose are easy to recognize.", "Before approving, check the project, the command or change, and the agent’s reason.", "Inspect the resulting diff and use your existing client delivery checks." ] }, { "title": "Local visibility is a personal work surface", "paragraphs": [ "Perch makes no network requests and keeps its status and notes on your Mac. It does not create a client portal or share transcripts with coworkers. Your agents remain separate services with their own data handling.", "Perch’s local behavior does not change a provider’s terms or establish a confidentiality certification. Decide which tools may handle each client’s material in your existing process." ] } ], "faqs": [ { "q": "Can my agency share one live shelf?", "a": "Perch has no shared team dashboard. Each shelf is local to its Mac." }, { "q": "Does Perch resolve overlapping edits?", "a": "No. Use task boundaries and separate working copies. Perch reports activity; it does not merge code." } ], "related": [ "/use-cases/parallel-agents/", "/guides/privacy-and-permissions/", "/alternatives/agent-dashboards/" ], "updated": "2026-10-23", "url": "https://perched.fyi/use-cases/agencies/", "markdown": "https://perched.fyi/content/use-cases/agencies.md" }, { "category": "use-cases", "slug": "parallel-agents", "title": "Monitor multiple coding agents from one place", "description": "See parallel Claude Code, Codex and Cursor sessions in one local view. Find what is working, finished or waiting for your next decision.", "lead": "Running agents in parallel creates a second job: noticing when each one needs you. Perch gathers supported sessions into a screen-edge shelf while keeping each project in its own app.", "sections": [ { "title": "Separate running work from waiting work", "paragraphs": [ "A busy terminal does not tell you what the other sessions are doing. Perch makes the distinction visible: Needs you, Working and Recent. A blue ring means work is running, amber means attention is needed, and a green check marks a finished turn.", "Status depends on the events each provider exposes. Cursor passive hooks do not report awaiting-permission status. The absence of an amber mark cannot prove that every provider is able to continue." ] }, { "title": "Give each agent independent work", "steps": [ "Split the work into tasks with clear ownership and verification criteria.", "Avoid simultaneous edits to the same working copy.", "Review waiting requests in their own project context.", "Inspect and validate finished changes before combining the results." ] }, { "title": "Clear requests without losing context", "paragraphs": [ "With opt-in answering, Claude Code supports tools, questions, plans and replies. Codex supports approvals and replies; Cursor supports replies after a turn. Every answer has two seconds to undo.", "Recent steps show kinds of activity and their timing, built from status rather than a transcript. Open the agent when you need its full output." ] }, { "title": "Keep orchestration in your existing workflow", "paragraphs": [ "Perch does not assign tasks, create branches, schedule agents or resolve conflicts. It keeps activity visible while you remain responsible for task boundaries and integration." ] } ], "faqs": [ { "q": "Can I mix agents in the same shelf?", "a": "Yes. Supported Claude Code, Codex and Cursor sessions appear together, with different available actions." }, { "q": "Is a completed turn a verified result?", "a": "No. Review the changes and check the result in the project." } ], "related": [ "/blog/monitor-multiple-coding-agents/", "/guides/agent-compatibility/", "/glossary/agent-session/" ], "updated": "2026-10-23", "url": "https://perched.fyi/use-cases/parallel-agents/", "markdown": "https://perched.fyi/content/use-cases/parallel-agents.md" }, { "category": "use-cases", "slug": "claude-code", "title": "Monitor and answer Claude Code from your screen edge", "description": "See Claude Code activity in Perch. With answering enabled, review tool requests, answer questions, approve plans and reply when a turn ends.", "lead": "Claude Code can make progress until it reaches a decision you need to make. Perch keeps that handoff nearby: watch the session, read what Claude is asking, and choose your answer without finding its terminal first.", "sections": [ { "title": "Review the request in context", "paragraphs": [ "A tool request shows the command or change and Claude’s reason. You can allow or deny it, or return to the terminal. Questions appear as numbered choices. Plan review lets you approve a plan or send feedback so Claude keeps planning.", "After a turn, the card can show its last message and a field for your next instruction. Every answer waits two seconds before sending; Esc or Undo takes it back. Perch never chooses the answer." ] }, { "title": "Connect deliberately", "steps": [ "Review the proposed Claude Code hook changes in Perch’s setup or agent settings.", "Connect the integration. Perch backs up the settings before adding its entries.", "Start a new Claude Code session and confirm its activity appears.", "Leave answering off to monitor, or enable it when you want supported requests in Perch." ] }, { "title": "The agent’s own app remains available", "paragraphs": [ "Perch steps aside when you are already in the session’s app. Switching back and staying also returns the request to the agent. A handoff wait between 2 and 30 minutes controls how long Perch holds a request.", "Ordinary Claude chats are not supported. Claude desktop Code sessions can open their conversation; terminal sessions bring the terminal host forward." ] }, { "title": "Requests stay in memory", "paragraphs": [ "Pending requests travel over a private local socket and are discarded once answered. Saved session status is separate and does not include commands, diffs or transcripts." ] } ], "faqs": [ { "q": "Is answering on by default?", "a": "No. Enable it in Settings if you want to respond from Perch." }, { "q": "Does Perch support ordinary Claude chats?", "a": "No. The integration is for the Claude Code workflow." } ], "related": [ "/guides/answering-agents/", "/guides/getting-started/", "/glossary/tool-approval/" ], "updated": "2026-10-23", "url": "https://perched.fyi/use-cases/claude-code/", "markdown": "https://perched.fyi/content/use-cases/claude-code.md" }, { "category": "use-cases", "slug": "codex", "title": "Keep Codex CLI activity and requests in view on Mac", "description": "Use Perch beside Codex CLI to see activity and, with answering enabled, allow or deny supported requests and reply after a turn.", "lead": "Keep Codex CLI in its terminal while its state stays visible at your screen edge. Perch supports Codex activity, allow and deny actions, and replies, with a two-second undo for the answers you choose.", "sections": [ { "title": "Codex beside your other sessions", "paragraphs": [ "A Codex session can appear beside Claude Code and Cursor. Check which project is running and which supported request needs attention without moving code or starting sessions inside Perch.", "Codex CLI answering has been checked live in the current product record. The Codex desktop app has not been verified. CLI support and desktop support are separate questions when evaluating your setup." ] }, { "title": "Review before sending", "paragraphs": [ "Turn on answering if you want to allow or deny supported requests or reply after a turn ends. Check the request and its project context before choosing. Each answer has a two-second undo window.", "Claude Code’s numbered question forms and plan-review actions are not listed as Codex features. The compatibility guide makes the supported boundary explicit." ] }, { "title": "Start with one session", "steps": [ "Review and connect the Codex hooks in Perch.", "Start a new Codex CLI session after connecting.", "Confirm that activity and the end of a turn appear.", "Enable answering only if you want supported requests in Perch. Keep the terminal for everything else." ] }, { "title": "Provider access stays separate", "paragraphs": [ "Perch does not supply Codex access or pay for provider usage. Its local monitoring does not change what your coding agent sends to its own service." ] } ], "faqs": [ { "q": "Is the Codex desktop app supported?", "a": "It has not been verified in the current product record. The live answering check is for Codex CLI." }, { "q": "Does Codex have Claude Code’s plan controls?", "a": "The documented Codex actions are allow, deny and replies." } ], "related": [ "/guides/agent-compatibility/", "/guides/answering-agents/", "/use-cases/parallel-agents/" ], "updated": "2026-10-23", "url": "https://perched.fyi/use-cases/codex/", "markdown": "https://perched.fyi/content/use-cases/codex.md" }, { "category": "use-cases", "slug": "cursor", "title": "See Cursor Agent activity from the edge of your Mac", "description": "Monitor Cursor local Agent activity in Perch and reply after a turn finishes. Understand Cursor status limits and session navigation.", "lead": "Keep Cursor’s local Agent in your editor and put its activity beside your other sessions. Perch shows supported Cursor events and lets you reply after a turn finishes, if you enable answering.", "sections": [ { "title": "A nearby view of Cursor activity", "paragraphs": [ "Cursor local Agent activity has been checked live in the current product record. Perch uses integration events to keep its session visible while you work in another app.", "Cursor passive hooks do not expose awaiting-permission status. Perch cannot fill in that missing event by scanning your screen or reading a conversation. Check Cursor itself when you need to inspect a permission prompt or understand why work stopped." ] }, { "title": "Reply after a completed turn", "paragraphs": [ "With answering enabled, Cursor supports a reply when a turn finishes. Your reply becomes the next instruction and has two seconds to undo.", "Tool approval, numbered questions and plan review are not documented Cursor actions in Perch. Use Cursor’s own interface for those interactions. Selecting a session opens the app rather than a specific chat." ] }, { "title": "Confirm the connection", "steps": [ "Review Perch’s proposed Cursor hook changes before connecting.", "Start a new local Agent session after connecting.", "Run a small task and confirm its activity and completed turn appear.", "Use the editor for requests outside the supported actions." ] }, { "title": "Park the next instruction in a note", "paragraphs": [ "A local sticky note can hold a test case or follow-up while Cursor works. Copy it when needed. Notes do not automatically dispatch instructions, and Perch does not coordinate Cursor’s edits with another agent’s work." ] } ], "faqs": [ { "q": "Will Perch show Cursor waiting for permission?", "a": "That status is not exposed by Cursor passive hooks." }, { "q": "Does Perch open a specific Cursor chat?", "a": "No. It opens the Cursor app." } ], "related": [ "/guides/agent-compatibility/", "/guides/agent-status-not-updating/", "/guides/sticky-notes/" ], "updated": "2026-10-23", "url": "https://perched.fyi/use-cases/cursor/", "markdown": "https://perched.fyi/content/use-cases/cursor.md" }, { "category": "guides", "slug": "getting-started", "title": "Get started with Perch on your Mac", "description": "Check Perch requirements, review local agent hooks, connect your first session and understand the three status states before enabling answers.", "lead": "Perch sits beside the coding agents you already use. Start with monitoring one session, check that its activity appears, then decide whether you want to answer supported requests from the shelf.", "sections": [ { "title": "Check availability and requirements first", "paragraphs": [ "The current offer is for Apple silicon Macs running macOS 14 or later. Perch is built with SwiftUI and AppKit. Intel Macs are not included in the current offer.", "Purchases are closed until delivery is ready. Join the launch list on the home page for availability; this guide describes the setup workflow for a Perch build you already have. No download or delivery date is promised here." ], "links": [ { "label": "Check availability", "href": "/checkout/" } ] }, { "title": "Connect your first agent", "steps": [ "Open Perch and use its setup flow or agent settings to see the detected agents.", "Review the exact change proposed for the agent’s settings before connecting.", "Connect the agent. Perch makes a backup and adds its own hook entries while preserving existing settings.", "Start a new session after connecting so it can pick up the hooks.", "Run a small task and confirm activity and the end of a turn appear in Perch." ] }, { "title": "Read the three states", "bullets": [ "Blue ring: the session is working.", "Amber dot: a supported event says the session needs you.", "Green check: a turn has finished. Review the result in the project." ], "paragraphs": [ "The shelf groups sessions into Needs you, Working and Recent. Events differ by provider: Cursor passive hooks do not expose awaiting-permission status. A state display cannot show an event the integration never receives." ] }, { "title": "Choose whether to enable answering", "paragraphs": [ "Answering is off by default. Turn it on in Settings only if you want supported requests handled in Perch. Claude Code supports approvals, questions, plans and replies. Codex supports approvals and replies. Cursor supports replies after a turn.", "Every answer waits two seconds so you can undo it. If the session’s app is already in front, Perch steps aside and the agent asks there." ], "links": [ { "label": "Understand answering and handoff", "href": "/guides/answering-agents/" } ] }, { "title": "Remove or repair the connection", "paragraphs": [ "Remove in agent settings takes out Perch’s own entries. If its hooks go stale or the app moves, use Repair when Perch offers it. Avoid replacing the agent’s entire settings file as a troubleshooting shortcut." ] } ], "faqs": [ { "q": "Do I need a Perch account?", "a": "No. The app has no account or server and makes no network requests." }, { "q": "Do I need to grant screen recording or Accessibility?", "a": "No. Optional exact-tab jumping may ask for Automation permission for Terminal or iTerm2." } ], "related": [ "/guides/agent-compatibility/", "/guides/agent-status-not-updating/", "/guides/privacy-and-permissions/" ], "updated": "2026-10-23", "url": "https://perched.fyi/guides/getting-started/", "markdown": "https://perched.fyi/content/guides/getting-started.md" }, { "category": "guides", "slug": "agent-compatibility", "title": "Perch compatibility: Claude Code, Codex and Cursor", "description": "Compare Perch support for Claude Code, Codex CLI and Cursor local Agent: status, approvals, questions, plans, replies and navigation limits.", "lead": "Perch brings supported agents into one shelf, but the available actions are different for each integration. Use this table to check the workflow you actually need.", "sections": [ { "title": "Supported actions at a glance", "table": { "caption": "Current Perch integration capabilities", "columns": [ "Capability", "Claude Code", "Codex CLI", "Cursor local Agent" ], "rows": [ [ "Activity monitoring", "Yes", "Yes", "Yes" ], [ "Awaiting-permission status", "Supported", "Supported", "Not exposed by passive hooks" ], [ "Allow or deny tools", "Yes, opt-in", "Yes, opt-in", "Use Cursor" ], [ "Numbered questions", "Yes, opt-in", "Not documented", "Use Cursor" ], [ "Plan review", "Yes, opt-in", "Not documented", "Use Cursor" ], [ "Reply after a turn", "Yes, opt-in", "Yes, opt-in", "Yes, opt-in" ], [ "Current live verification", "CLI activity and answers", "CLI answering", "Local Agent activity" ] ] } }, { "title": "A Code session is different from an ordinary chat", "paragraphs": [ "The Claude integration is for Claude Code. Ordinary Claude conversations and OpenCode are not supported. The current product record includes live checks for Claude Code CLI, Cursor local Agent activity and Codex CLI answering.", "Codex desktop app coverage has not been verified. Do not assume a desktop app is covered just because the provider’s CLI is listed." ] }, { "title": "What opening a session does", "paragraphs": [ "Claude desktop Code sessions can open their conversation. Terminal sessions bring the terminal host forward. Optional exact-tab jumping covers Terminal, iTerm2 and tmux. Cursor opens the app rather than a specific chat.", "Perch selects and focuses supported destinations. It does not type into a terminal or read its screen. Exact-tab jumping is optional and separate from basic monitoring." ] }, { "title": "Answering is always your choice", "paragraphs": [ "All answering is off by default and requires opting in. Every response has a two-second undo. Perch steps aside when you return to the session’s app and hands a held request back after your selected wait.", "Compatibility depends on events from the connected hooks. If an agent changes its integration behavior, check the connection with a new session before relying on it for a busy workflow." ], "links": [ { "label": "Troubleshoot missing activity", "href": "/guides/agent-status-not-updating/" } ] } ], "faqs": [ { "q": "Does every provider have the same actions?", "a": "No. Claude Code supports the broadest set. Codex has approvals and replies; Cursor has replies after a turn." }, { "q": "Does Perch include access to these agents?", "a": "No. Agent subscriptions and API usage are separate." } ], "related": [ "/use-cases/claude-code/", "/use-cases/codex/", "/use-cases/cursor/" ], "updated": "2026-10-23", "url": "https://perched.fyi/guides/agent-compatibility/", "markdown": "https://perched.fyi/content/guides/agent-compatibility.md" }, { "category": "guides", "slug": "answering-agents", "title": "Approve, answer and reply from Perch", "description": "Learn Perch’s opt-in answering workflow, supported provider actions, two-second undo and handoff back to the agent’s own app.", "lead": "Answering brings a supported request to the edge of your screen. You read it and decide what to send. Perch never grants permission or chooses a reply on its own.", "sections": [ { "title": "Turn it on deliberately", "paragraphs": [ "Answering is off by default. Enable it in Settings after connecting an agent. You can keep monitoring without using any answering features.", "Claude Code supports allow or deny for tools, numbered questions, plan review and replies. Codex supports allow, deny and replies. Cursor supports a reply after a turn. Other interactions belong in the agent’s own app." ] }, { "title": "Review a tool request", "steps": [ "Check the session and project so you know which work the request belongs to.", "Read the command or proposed change and the agent’s reason.", "Choose allow or deny, or return to the agent’s own app if you need more context.", "Watch the Sending state. Use Esc or Undo within two seconds to cancel a mistaken response." ] }, { "title": "Questions, plans and the next instruction", "paragraphs": [ "For Claude Code, numbered choices let you answer a question with the matching key, while a free-text response covers a more specific answer. Plan review lets you approve or send feedback while Claude keeps planning.", "When a supported turn ends, a reply becomes the next instruction. A reply is different from approving the changes the agent just made. You still need to inspect the work in your project." ] }, { "title": "Return to the original prompt", "paragraphs": [ "If the session’s app is in front when a request arrives, Perch steps aside. Switching back to the app and staying also returns the request. You can set how long Perch waits before handing it back, from 2 to 30 minutes.", "If Perch quits, the agent gets the request back. You do not have to finish every interaction in the shelf, and the original agent interface stays part of the workflow." ] }, { "title": "What happens to request content", "paragraphs": [ "The pending request reaches Perch over a private local socket, stays in memory and is discarded once answered. Prompts, commands, diffs and transcripts are not written as session history. See the privacy policy for the full data description." ] } ], "faqs": [ { "q": "Can I undo an answer after it was sent?", "a": "The undo window is the two-second Sending period. It is not a way to reverse work the agent has already performed." }, { "q": "Can I leave answering off?", "a": "Yes. Perch can be used for monitoring alone." } ], "related": [ "/guides/keyboard-shortcuts/", "/guides/agent-compatibility/", "/glossary/tool-approval/" ], "updated": "2026-10-23", "url": "https://perched.fyi/guides/answering-agents/", "markdown": "https://perched.fyi/content/guides/answering-agents.md" }, { "category": "guides", "slug": "keyboard-shortcuts", "title": "Perch keyboard shortcuts and the review loop", "description": "Open Perch with Control-Option-C, navigate sessions and use Return, number keys and Esc for supported answers and the two-second undo.", "lead": "Perch can keep the routine part of checking an agent on the keyboard. The important part still happens before the keypress: read which session is asking and what your answer will authorize.", "sections": [ { "title": "The core shortcuts", "table": { "caption": "Default Perch keyboard controls", "columns": [ "Key", "Use" ], "rows": [ [ "Control + Option + C", "Open Perch from another app; the shortcut is configurable" ], [ "Arrow keys", "Move between sessions" ], [ "Return", "Allow the displayed supported tool request" ], [ "Number keys", "Choose a numbered Claude Code answer" ], [ "Esc", "Undo during the two-second Sending window" ] ] } }, { "title": "Use one deliberate review cycle", "steps": [ "Open Perch with the shortcut.", "Move to the session you want to review.", "Read the project, request and available actions.", "Use the key for the visible action. If it was a mistake, undo during Sending.", "Review the next session separately rather than treating requests as a batch of identical approvals." ] }, { "title": "The action depends on the integration", "paragraphs": [ "Numbered question forms and plan review are Claude Code features. Codex supports allow, deny and replies. Cursor supports replies after a completed turn. A shortcut does not add an action that the integration lacks.", "The undo key only applies during the two-second Sending period. Once a request has reached the agent, undo does not reverse a command, a file edit or a completed turn." ] }, { "title": "When a shortcut seems unavailable", "paragraphs": [ "Check the configured shortcut in Perch and whether another app uses the same combination. You can still open Perch from the screen-edge tab or menu bar.", "If the shelf opens but a request is missing, check whether the agent is already asking in its own app. Perch steps aside when that app is in front, and missing provider events are a separate compatibility issue." ] } ], "related": [ "/guides/answering-agents/", "/guides/agent-status-not-updating/", "/blog/reduce-agent-context-switching/" ], "updated": "2026-10-23", "url": "https://perched.fyi/guides/keyboard-shortcuts/", "markdown": "https://perched.fyi/content/guides/keyboard-shortcuts.md" }, { "category": "guides", "slug": "privacy-and-permissions", "title": "What Perch stores and which permissions it needs", "description": "Understand Perch’s local status storage, in-memory requests and optional Automation permission. No screen recording, microphone or Accessibility.", "lead": "Perch receives activity through local agent hooks. It does not need to scan your screen or keep a transcript to tell you that an agent is working or has finished.", "sections": [ { "title": "Status and content follow different paths", "table": { "caption": "How Perch handles local data", "columns": [ "Data", "Handling" ], "rows": [ [ "Session status", "Saved locally: IDs, project folder, state, times, host app, terminal or tmux pane and tool names" ], [ "Pending answer request", "Held in memory over a private local socket, then discarded" ], [ "Prompts, commands, diffs and transcripts", "Not saved as Perch session history" ], [ "Sticky notes", "Saved locally on your Mac" ], [ "Claude desktop Code titles", "Read from local metadata and kept in memory" ] ] } }, { "title": "Permissions for monitoring", "paragraphs": [ "Perch asks for no microphone, screen recording or Accessibility access. It uses events from the agents you connect, rather than watching the contents of your terminal.", "Optional Go to the exact tab can ask macOS for Automation permission for Terminal or iTerm2. That permission lets Perch select and focus the relevant tab. It never types into a terminal or reads what is in it." ] }, { "title": "Settings changes are reviewable", "paragraphs": [ "Before connecting an agent, Perch shows the exact hook change and backs up the settings. Remove takes out Perch’s own entries. You do not need to replace all your agent settings to disconnect it.", "Status and notes live under ~/Library/Application Support/Perch. Preferences use macOS user defaults. The privacy policy describes clearing sessions, removing hooks and deleting local app data." ] }, { "title": "Perch and your providers are separate", "paragraphs": [ "The Perch app has no account, no server and no network requests. This does not make a cloud-connected coding agent run offline or change what that provider processes.", "Website launch-list data, hosting, analytics and future payments have their own handling, described in the privacy policy. The app’s local-only claim should not be applied to every service linked from this website." ], "links": [ { "label": "Read the full privacy policy", "href": "/privacy/" } ] } ], "faqs": [ { "q": "Does local monitoring make my coding agent offline?", "a": "No. Perch and the agent provider are separate. The agent may still need its own network connection." }, { "q": "Can I use monitoring without optional tab permissions?", "a": "Yes. Exact-tab jumping is optional and separate from basic monitoring." } ], "related": [ "/glossary/local-first/", "/blog/status-without-transcripts/", "/guides/getting-started/" ], "updated": "2026-10-23", "url": "https://perched.fyi/guides/privacy-and-permissions/", "markdown": "https://perched.fyi/content/guides/privacy-and-permissions.md" }, { "category": "guides", "slug": "agent-status-not-updating", "title": "What to check when agent status is not updating", "description": "Check Perch’s connection, new sessions, hidden sessions and provider limits when activity or an expected request does not appear.", "lead": "A missing state can mean an unconnected session, a stale hook or an event the provider does not expose. Check those separately before changing the rest of your agent settings.", "sections": [ { "title": "Start with the connection", "steps": [ "Confirm Perch is running and monitoring has not been paused.", "Open agent settings and check that the provider is connected.", "If Perch offers Repair for a stale hook or moved app, review and use it.", "Start a new agent session after connecting or repairing.", "Run a small task and look for activity followed by a completed turn." ] }, { "title": "Check the session you are expecting", "paragraphs": [ "Make sure you are looking for the correct project and that the session is not hidden. Perch can hide a session until its state changes. A local rename can also make it look different from the terminal title.", "A session that existed before hooks were connected may not have picked up the integration. Testing a new session is a more useful check than repeatedly opening an old conversation." ] }, { "title": "Distinguish a missing event from a missing answer", "paragraphs": [ "Cursor passive hooks do not report awaiting-permission status. Perch will not reconstruct that event from screen contents. Codex desktop coverage has not been verified, and ordinary Claude chats are outside the supported workflow.", "If activity appears but an answer card does not, check whether answering is enabled and whether that action is supported for the provider. Perch also steps aside when the session’s own app is in front, and returns requests after the chosen wait." ] }, { "title": "An opening problem may be separate", "paragraphs": [ "If the session is listed but opening it only brings an app forward, check the destination support. Cursor opens the app, not a particular chat. Exact-tab selection is optional for supported Terminal, iTerm2 and tmux sessions." ] }, { "title": "Ask for help with a small reproduction", "paragraphs": [ "Write down your macOS version, the provider and whether it is CLI or desktop, whether a new session behaves differently, and which state you expected. Avoid including credentials or private project contents. A clear sequence is more useful than an entire transcript." ], "links": [ { "label": "Email Perch support", "href": "mailto:support@trillium.one" } ] } ], "related": [ "/guides/agent-compatibility/", "/guides/getting-started/", "/guides/answering-agents/" ], "updated": "2026-10-23", "url": "https://perched.fyi/guides/agent-status-not-updating/", "markdown": "https://perched.fyi/content/guides/agent-status-not-updating.md" }, { "category": "guides", "slug": "sticky-notes", "title": "Keep the next prompt beside your coding agents", "description": "Use Perch’s ten local sticky notes for follow-up prompts, acceptance criteria and review reminders, then copy them into your coding workflow.", "lead": "An agent starts working just as you think of the next detail. Perch’s sticky notes give that thought somewhere nearby to wait without interrupting the current turn.", "sections": [ { "title": "Choose a note with a clear purpose", "paragraphs": [ "Perch supports up to ten notes in four colors, stored locally on your Mac. Pin the ones you need beside your sessions. One click on Copy puts a note on the clipboard for you to paste into an agent, terminal or document.", "Useful notes are small and actionable: an edge case to test, a sentence to include in the next prompt, or a reminder about what the current task should leave unchanged." ] }, { "title": "A prompt parking routine", "steps": [ "Write a follow-up while the agent continues its current task.", "Keep the note attached to the right project in your own wording.", "When the turn finishes, review the result before sending a follow-up.", "Copy the note and paste it into the agent when its timing and context are right.", "Update or remove the note after using it so the shelf stays useful." ] }, { "title": "Examples that fit a small note", "bullets": [ "Acceptance criteria: “Empty state still has a visible Create button.”", "Review reminder: “Check keyboard focus after closing the dialog.”", "Next prompt: “Now cover the cancelled request case; keep the existing API.”", "Handoff detail: “Client wants the original heading and spacing preserved.”" ] }, { "title": "Keep the boundary clear", "paragraphs": [ "Notes do not automatically become agent instructions. Copying a note is a clipboard action, not dispatch. Perch is not a shared backlog or a document collaboration tool.", "Local storage also means you should not assume the note is synchronized to another Mac or available to a coworker. Keep lasting project decisions in your normal documentation." ] } ], "related": [ "/use-cases/developers/", "/blog/reduce-agent-context-switching/", "/guides/privacy-and-permissions/" ], "updated": "2026-10-23", "url": "https://perched.fyi/guides/sticky-notes/", "markdown": "https://perched.fyi/content/guides/sticky-notes.md" }, { "category": "alternatives", "slug": "terminal-tabs", "title": "Perch or checking your terminal tabs?", "description": "Compare manual terminal checks with a local Perch shelf. Understand where full terminal context is useful and where visible agent state helps.", "lead": "Your agent’s own terminal is the right place for its full output. Perch adds a nearby view of supported session states so you can decide when that terminal needs attention.", "sections": [ { "title": "Two ways to find the next handoff", "table": { "caption": "Manual terminal checks and Perch", "columns": [ "Need", "Checking terminal tabs", "Perch" ], "rows": [ [ "Read full agent output", "Open the session and read it", "Open the agent; Perch does not retain transcripts" ], [ "Check several session states", "Visit the relevant tabs", "See supported sessions together in the shelf" ], [ "Answer a request", "Use the agent’s own interface", "Use supported opt-in actions or return to the agent" ], [ "See a completed turn", "Check the session", "See its supported completion event" ], [ "Coordinate overlapping edits", "Your project workflow", "Still your project workflow" ] ] } }, { "title": "When the terminal is enough", "paragraphs": [ "If you work inside one session most of the time, the original interface may already give you the context you need. You can read output, answer requests and inspect the project without adding a monitor.", "A terminal also remains important for detailed review. Perch’s recent steps describe activity and timing, not every command’s output." ] }, { "title": "When a shelf adds something useful", "paragraphs": [ "A local state view becomes useful when the recurring problem is finding which of several sessions needs you. Perch groups supported activity into Needs you, Working and Recent and makes the state visible at the screen edge.", "It works alongside your terminal rather than moving sessions elsewhere. Answering is optional and varies by provider. Cursor’s passive hooks do not expose awaiting-permission status, so checking its own interface remains necessary for that case." ] }, { "title": "Keep both in the review loop", "paragraphs": [ "Use Perch to notice the handoff and the terminal or editor to inspect details. Neither a visible status nor a completed turn replaces reviewing the resulting changes." ] } ], "related": [ "/use-cases/parallel-agents/", "/guides/agent-compatibility/", "/blog/monitor-multiple-coding-agents/" ], "updated": "2026-10-23", "url": "https://perched.fyi/alternatives/terminal-tabs/", "markdown": "https://perched.fyi/content/alternatives/terminal-tabs.md" }, { "category": "alternatives", "slug": "notifications", "title": "Perch or agent notifications?", "description": "Compare a momentary notification with a persistent local view of coding-agent sessions. Choose around how you notice and review handoffs.", "lead": "A notification tells you that something happened. A session shelf gives you a place to look for what is waiting now. The useful choice depends on what you keep missing in your current workflow.", "sections": [ { "title": "An alert and a state view answer different questions", "table": { "caption": "Notifications and a Perch session shelf", "columns": [ "Question", "A notification", "Perch" ], "rows": [ [ "What just happened?", "An alert can announce an event", "Supported activity appears as session state" ], [ "What is waiting now?", "Depends on the alerting tool and history", "Needs you groups supported waiting events" ], [ "Where is the original context?", "Follow the alert’s destination", "Open the session’s app" ], [ "Can I answer here?", "Depends on the tool", "Supported opt-in actions differ by provider" ], [ "Does a completion mean correct code?", "No", "No" ] ] } }, { "title": "When an alert is enough", "paragraphs": [ "If the only thing you need is a cue to return to one agent, your current notification setup may be enough. You can leave the review in the original app.", "Notification behavior varies across agents and operating-system settings. This comparison is about the workflow, not a claim that every agent has the same alerts or history." ] }, { "title": "When you need a place to return to", "paragraphs": [ "With several sessions, you may want a current list rather than a sequence of past alerts. Perch keeps supported sessions grouped by state. Its combined completion notice can announce several turns together, and sounds are optional.", "You can inspect waiting work when you are ready to decide. Perch still relies on provider events; it cannot show Cursor awaiting permission through passive hooks that do not expose that state." ] }, { "title": "Keep the decision separate from the signal", "paragraphs": [ "Whether you arrive through an alert or a shelf, read the request before responding. A useful cue gets you to a review. It does not make the review unnecessary." ] } ], "related": [ "/blog/reduce-agent-context-switching/", "/guides/answering-agents/", "/use-cases/developers/" ], "updated": "2026-10-23", "url": "https://perched.fyi/alternatives/notifications/", "markdown": "https://perched.fyi/content/alternatives/notifications.md" }, { "category": "alternatives", "slug": "agent-dashboards", "title": "A local Perch shelf or a shared agent dashboard?", "description": "Choose between personal local visibility and requirements such as team access, remote sessions and shared task coordination. Where Perch fits.", "lead": "A personal monitor and a shared dashboard may both show agent activity, but they can solve different problems. Start with who needs the information and where the work runs.", "sections": [ { "title": "Write down the requirements", "table": { "caption": "Questions to ask when evaluating an agent dashboard", "columns": [ "Requirement", "Perch", "What to check in another tool" ], "rows": [ [ "Personal activity on your Mac", "Core workflow", "Which local sessions it can detect" ], [ "Shared team access", "Not provided", "Identity, access and sharing controls" ], [ "Phone or remote access", "Not provided", "Remote connection and supported devices" ], [ "Task assignment and scheduling", "Not provided", "How tasks and dependencies are managed" ], [ "Data location", "Perch app status and notes stay on your Mac", "What is uploaded, retained and shared" ], [ "Provider actions", "Documented per integration", "The actual action matrix, not only provider logos" ] ] } }, { "title": "Choose Perch for the local attention problem", "paragraphs": [ "Perch is useful when you already run agents and need a quiet place to see which session needs you. It has no account or server, and it does not upload your activity.", "Its scope is the sessions on your Mac, supported answers you choose and local notes. Your provider subscriptions and their own data handling remain separate." ] }, { "title": "Evaluate shared workflows on their own terms", "paragraphs": [ "If your requirement is a shared queue, remote session access or organization-wide reporting, make that explicit before selecting a tool. Perch does not provide those features.", "Other products vary. Check their current documentation for supported providers, where execution happens, what content they retain, how access works and whether a displayed action is actually interactive. No competitor capability or pricing is assumed here." ] }, { "title": "Monitoring is not orchestration", "paragraphs": [ "Even when several states appear together, task boundaries and code integration still need an owner. Perch does not distribute work, prevent edit conflicts or merge the results." ] } ], "related": [ "/blog/agent-monitor-vs-agent/", "/guides/privacy-and-permissions/", "/use-cases/agencies/" ], "updated": "2026-10-23", "url": "https://perched.fyi/alternatives/agent-dashboards/", "markdown": "https://perched.fyi/content/alternatives/agent-dashboards.md" }, { "category": "blog", "slug": "monitor-multiple-coding-agents", "published": "2026-10-23", "title": "How to monitor multiple coding agents without checking every terminal", "description": "A practical review loop for parallel coding agents: bound the tasks, distinguish running from waiting, and verify each completed result.", "lead": "The first parallel agent feels like extra capacity. The fourth can feel like another inbox. A useful monitoring workflow starts by separating three questions: what is running, what needs a decision, and what is ready to review.", "sections": [ { "title": "Start with task boundaries", "paragraphs": [ "Before deciding where to watch agents, decide what each one owns. “Improve the app” is difficult to coordinate across sessions. “Add the empty state to this screen” and “review the request cancellation path” give you clearer ownership and a result you can inspect.", "If sessions may change overlapping files, use separate working copies or another isolation approach in your existing development process. A status monitor cannot prevent a conflict. A clear division of work is still the foundation." ] }, { "title": "Give each state a different response", "paragraphs": [ "Running work usually needs patience. Waiting work needs a decision. A completed turn needs review. Treating all three as “check the terminal” makes you reopen sessions that have nothing new to show.", "Perch puts supported sessions into Needs you, Working and Recent. The screen-edge marks make the same distinction visible while you are in another app. This is a way to route your attention; it is not a measure of whether the code is ready to ship." ] }, { "title": "Build a short review loop", "steps": [ "Check waiting sessions when you can give a decision your attention.", "Identify the project before reading the command or question.", "Answer the supported request, or open the agent for more context.", "Review completed work in the project, including the diff and the relevant checks.", "Give the next instruction only after deciding what the previous turn actually accomplished." ] }, { "title": "Keep provider limits visible", "paragraphs": [ "Not every integration reports the same events. Cursor passive hooks do not expose awaiting-permission status. Claude Code supports tools, questions, plans and replies in Perch; Codex has approvals and replies; Cursor has replies after a turn. Answering is opt-in.", "A good workflow leaves room to return to the original app. Missing a supported event and expecting an unsupported event are different problems, and they need different fixes." ] }, { "title": "Use the shelf for attention, the project for proof", "paragraphs": [ "Recent steps can tell you that a session edited files or ran a command and how long it took. They do not preserve the command output or explain whether a test was meaningful. Use them to decide where to look next, then verify the result at its source.", "That division keeps the monitor small and the review grounded: Perch helps you notice the handoff; you decide whether the work meets the task." ] } ], "related": [ "/use-cases/parallel-agents/", "/guides/agent-compatibility/", "/alternatives/terminal-tabs/" ], "updated": "2026-10-23", "url": "https://perched.fyi/blog/monitor-multiple-coding-agents/", "markdown": "https://perched.fyi/content/blog/monitor-multiple-coding-agents.md" }, { "category": "blog", "slug": "status-without-transcripts", "published": "2026-10-23", "title": "Why an agent status monitor does not need your transcripts", "description": "How Perch separates session status from request content, and what a status-only recent-steps view can and cannot tell you about coding work.", "lead": "“Is it still working?” is a much smaller question than “What did it say?” Perch keeps those questions separate, using local activity events for monitoring rather than retaining a second copy of an agent conversation.", "sections": [ { "title": "The information a glance needs", "paragraphs": [ "To show a working session, a monitor needs a session identity and a state. To help you find that session later, it needs context such as the project folder and host app. Times and tool names can describe recent activity without carrying the arguments or the output.", "Perch saves that kind of status locally: session identifiers, folder, state, times, terminal context and tool names. Prompts, commands, diffs, responses and transcripts do not become its stored session history." ] }, { "title": "A request has a different lifetime", "paragraphs": [ "Answering a request does require showing its content. You should see what a tool wants to run or what question an agent is asking before responding. In Perch, a pending request reaches the app over a private local socket and stays in memory while it is waiting.", "That content is discarded once you answer. It does not need to become a searchable transcript just because it was visible on a card. The data needed to make a decision and the data needed to show a past state are different." ] }, { "title": "What Recent steps can tell you", "paragraphs": [ "A recent-steps list can describe the sequence and timing of activity: work started, a tool ran, the session needed you, and a turn finished. It can give you a quick way back into the rhythm of a session.", "It cannot explain the full reasoning, preserve the output of every command or establish that an edit was correct. For that, open the agent and inspect the project. A status summary should not pretend to be a complete audit log." ] }, { "title": "Local monitoring does not change the agent provider", "paragraphs": [ "Perch itself makes no network requests. Claude Code, Codex and Cursor remain separate tools. Their own processing and data policies still apply to the material you give them.", "Likewise, this website’s launch list and hosting are separate from the local app. A useful privacy explanation names the system, the data and the lifetime instead of applying one broad label to everything around a product." ] } ], "related": [ "/guides/privacy-and-permissions/", "/privacy/", "/glossary/local-first/" ], "updated": "2026-10-23", "url": "https://perched.fyi/blog/status-without-transcripts/", "markdown": "https://perched.fyi/content/blog/status-without-transcripts.md" }, { "category": "blog", "slug": "human-in-the-loop-coding", "published": "2026-10-23", "title": "Keep a human decision in the coding-agent loop", "description": "Make agent approvals easier to review without turning them into automatic decisions. A practical approach to context, scope, undo and handoff.", "lead": "A permission prompt is useful only if the person answering understands it. Moving the prompt closer can help, but the review still needs the project, the proposed action and enough context to decide.", "sections": [ { "title": "Read the action before the button", "paragraphs": [ "A familiar-looking test command can belong to an unfamiliar project. Before allowing a tool, identify the session, read the actual command or change, and compare it with the task you intended.", "Perch shows the supported request on a card so the decision can happen without first locating the terminal. The goal is to make a deliberate review easier to reach. A short route to Allow is not a reason to skip reading." ] }, { "title": "Separate different kinds of consent", "paragraphs": [ "Approving a tool, choosing a product direction, accepting a plan and replying to a finished turn are different decisions. For Claude Code, Perch gives these their own supported interactions: tool requests, numbered questions, plan review and replies.", "Codex and Cursor have narrower action sets. The compatibility guide matters because a single “works with” label cannot explain what you can actually decide from the shelf." ] }, { "title": "Use undo for a mistaken input", "paragraphs": [ "Every answer has a two-second Sending window. Esc or Undo can stop an accidental answer during that period. This is a correction for a mistaken click or keypress, not a rollback system.", "Once the agent receives the answer, undo cannot reverse the command it runs or the files it edits. Reversing a change belongs in the project’s normal development workflow." ] }, { "title": "Keep a route back to the agent", "paragraphs": [ "Sometimes the card is enough. Sometimes you need the rest of the conversation, the repository or a command’s full output. Returning to the original app is part of a good review loop.", "Perch steps aside when you are in the session’s app and hands held requests back after your chosen wait. Answering stays off until you enable it. Those boundaries leave the decision with the person and the work with the agent." ] }, { "title": "A small checklist before responding", "bullets": [ "Is this the intended project and session?", "Does the action fit the task’s scope?", "Do I have enough context to decide here?", "Am I authorizing the action I actually mean to authorize?" ] } ], "related": [ "/guides/answering-agents/", "/glossary/human-in-the-loop/", "/glossary/tool-approval/" ], "updated": "2026-10-23", "url": "https://perched.fyi/blog/human-in-the-loop-coding/", "markdown": "https://perched.fyi/content/blog/human-in-the-loop-coding.md" }, { "category": "blog", "slug": "reduce-agent-context-switching", "published": "2026-10-23", "title": "Reduce the checking loop around your coding agents", "description": "Distinguish checking for a change from reviewing a result. Use visible state, project names and small notes to manage agent handoffs on Mac.", "lead": "Opening an agent window is useful when there is something to read. Reopening it just to find out whether anything happened adds a different kind of work: remembering where you were before the check.", "sections": [ { "title": "Ask a smaller question first", "paragraphs": [ "“Does this session need me?” is a useful first check. If the answer is no, you can stay with the work in front of you. If the answer is yes, the next step is to read the actual request in context.", "Perch makes supported activity states visible at the screen edge. It does not claim to measure your attention or guarantee a productivity improvement. It simply gives the status question a nearby answer." ] }, { "title": "Use names that survive an interruption", "paragraphs": [ "A vague session label can force you to reconstruct the project before every response. Local session names such as “Checkout: cancellation case” or “Docs: install steps” give you a more useful starting point.", "Names do not replace reading the request. They make it easier to notice when the action belongs to the wrong task before you answer." ] }, { "title": "Park follow-ups instead of changing the current turn", "paragraphs": [ "While an agent works, a new idea can tempt you to alter its task immediately. Sometimes that is necessary; often it can wait until you have reviewed the current result.", "Perch’s sticky notes offer a place for that next thought. Write it, keep it beside the work, and copy it into the next instruction when the timing is right. Notes are local and do not dispatch automatically." ] }, { "title": "Keep meaningful review in the loop", "paragraphs": [ "The aim is to reduce empty checks, not to remove the review that catches mistakes. A green check means a turn finished, not that the implementation passed your acceptance criteria.", "When work is ready, open the project. Read the diff, inspect the behavior and run the checks that matter. Then choose whether the agent should continue or whether the task is complete." ] }, { "title": "Start with one change to your routine", "steps": [ "Use Perch for one session before adding more.", "Give that session a clear name and a bounded task.", "Use visible status for checks and the project for review.", "Add notes or opt-in answering only when they solve a recurring part of your workflow." ] } ], "related": [ "/guides/sticky-notes/", "/guides/keyboard-shortcuts/", "/use-cases/developers/" ], "updated": "2026-10-23", "url": "https://perched.fyi/blog/reduce-agent-context-switching/", "markdown": "https://perched.fyi/content/blog/reduce-agent-context-switching.md" }, { "category": "blog", "slug": "agent-monitor-vs-agent", "published": "2026-10-23", "title": "A coding agent, a monitor and an orchestrator do different jobs", "description": "Understand where Perch fits beside coding agents: local activity and human responses, with task execution and orchestration kept separate.", "lead": "Tools around coding agents can look similar while doing very different work. It helps to separate who executes a task, who shows its state, and who coordinates several tasks together.", "sections": [ { "title": "The coding agent does the task", "paragraphs": [ "A coding agent is the tool you ask to inspect a project, propose a change or carry out work. You interact with that agent in its supported terminal or editor workflow. Its capabilities, access and service usage belong to that product.", "Perch does not supply an agent or replace one. You continue using Claude Code, Codex or Cursor, and their subscriptions or API usage remain separate." ] }, { "title": "The monitor helps you notice the handoff", "paragraphs": [ "A monitor answers a narrower set of questions: which session is working, which turn has ended, and which supported event needs your attention. Perch brings those states into a local shelf and screen-edge tab.", "With answering enabled, Perch can also pass along actions you choose. The supported actions differ by provider. It does not decide what an agent should do or generate a response for you." ] }, { "title": "Orchestration coordinates the work", "paragraphs": [ "Task assignment, dependencies, isolated working copies, scheduling and merging are coordination problems. A workflow that handles those problems needs more than a list of session states.", "Perch does not assign work or resolve edit conflicts. If you run sessions in parallel, keep ownership and verification in your development process. A monitor can sit alongside that process without becoming its coordinator." ] }, { "title": "Choose around the gap in your current setup", "paragraphs": [ "If you need an agent, start with its own product and capabilities. If your agents already work well but you keep checking whether they need you, local visibility may be the gap. If you need a shared remote queue or team coordination, identify those requirements explicitly.", "Our comparisons discuss manual terminal checking, notifications and shared dashboards as approaches. They do not rank products from different categories as if they all solve the same problem." ] } ], "related": [ "/alternatives/", "/use-cases/parallel-agents/", "/glossary/agent-session/" ], "updated": "2026-10-23", "url": "https://perched.fyi/blog/agent-monitor-vs-agent/", "markdown": "https://perched.fyi/content/blog/agent-monitor-vs-agent.md" }, { "category": "glossary", "slug": "agent-hook", "title": "What is an agent hook?", "description": "An agent hook is an event-triggered integration point. Learn how Perch uses local hooks to receive activity without reading your terminal screen.", "lead": "An agent hook is an integration point that runs when a coding agent emits a particular event. Perch uses local hooks to receive supported activity updates.", "sections": [ { "title": "An event instead of a screen scan", "paragraphs": [ "A hook can report that a session started, a tool ran or a turn finished. Perch turns supported events into session state and recent steps. It does not need to read the terminal display to learn that an event occurred.", "The provider decides which events exist and what each hook can do. Cursor’s passive hooks do not expose awaiting-permission status, for example. A hook integration cannot reliably show an event it never receives." ] }, { "title": "How Perch connects hooks", "paragraphs": [ "Perch shows the proposed agent settings change before connecting, makes a backup and adds its own entries. Remove takes those entries out. Start a new session after connecting so the integration can take effect." ], "links": [ { "label": "Connect your first session", "href": "/guides/getting-started/" } ] } ], "related": [ "/guides/agent-status-not-updating/", "/guides/agent-compatibility/" ], "updated": "2026-10-23", "url": "https://perched.fyi/glossary/agent-hook/", "markdown": "https://perched.fyi/content/glossary/agent-hook.md" }, { "category": "glossary", "slug": "agent-session", "title": "What is a coding-agent session?", "description": "A coding-agent session is a particular ongoing interaction with an agent. Understand sessions, turns and Perch’s working, waiting and recent states.", "lead": "A coding-agent session is a particular ongoing interaction with an agent, associated with its own task and project context. A turn is one period of work within that session.", "sections": [ { "title": "One provider can have several sessions", "paragraphs": [ "Two Claude Code terminals may belong to the same provider but different projects. Treat them as separate sessions when reviewing a request. Perch uses session identifiers and project context to keep their activity distinct.", "A turn ending does not necessarily end the whole session. A reply can become its next instruction, and the same session may return to Working." ] }, { "title": "What a state tells you", "paragraphs": [ "Perch groups supported activity into Needs you, Working and Recent. A completed turn means the agent stopped that turn; it is not proof that the implementation is correct.", "Use the state to decide where to look, then open the project or agent when you need the full output. Perch’s recent steps are status summaries rather than retained transcripts." ] } ], "related": [ "/use-cases/parallel-agents/", "/blog/monitor-multiple-coding-agents/" ], "updated": "2026-10-23", "url": "https://perched.fyi/glossary/agent-session/", "markdown": "https://perched.fyi/content/glossary/agent-session.md" }, { "category": "glossary", "slug": "human-in-the-loop", "title": "What does human-in-the-loop mean for coding agents?", "description": "Human-in-the-loop means a person makes a decision in an automated workflow. In Perch, you review and choose each supported agent response.", "lead": "Human-in-the-loop describes a workflow in which a person makes a decision at a defined point in an automated process. A coding-agent tool approval is one such point.", "sections": [ { "title": "A person supplies the decision", "paragraphs": [ "An agent may propose a command, ask a product question or present a plan. The person checks the scope and chooses whether or how to continue.", "In Perch, answering is off by default. When enabled, Perch presents supported requests and sends the response you choose. It does not auto-approve a request or compose the decision for you." ] }, { "title": "Keep enough context to review", "paragraphs": [ "A visible button is not enough context on its own. Check the project, the proposed action and the reason. If you need the rest of the conversation, return to the agent.", "Perch’s two-second undo corrects a mistaken input during Sending. It does not replace careful review or undo actions already performed by the agent." ] } ], "related": [ "/blog/human-in-the-loop-coding/", "/guides/answering-agents/" ], "updated": "2026-10-23", "url": "https://perched.fyi/glossary/human-in-the-loop/", "markdown": "https://perched.fyi/content/glossary/human-in-the-loop.md" }, { "category": "glossary", "slug": "local-first", "title": "What does local-first mean for Perch?", "description": "For Perch, local-first means the app keeps activity and notes on your Mac and makes no network requests. Agent provider processing remains separate.", "lead": "For Perch, local-first describes where its app data and interactions live: on your Mac. The app has no account or server and makes no network requests.", "sections": [ { "title": "Name the data and its lifetime", "paragraphs": [ "Perch saves status and notes locally. Pending answer requests stay in memory and are discarded once answered. Commands, prompts, diffs and transcripts are not saved as Perch session history.", "The phrase local-first is useful here because it points to concrete behavior. The privacy policy is the source for the full description of what is read, stored and discarded." ] }, { "title": "Keep other services separate", "paragraphs": [ "Your coding agent may still connect to its provider. Perch’s local design does not turn that service into offline software or change its privacy policy.", "The website also has separate handling for launch-list signups, hosting, analytics and future payments. A claim about the Mac app should not be read as a claim about every linked service." ], "links": [ { "label": "Read the privacy policy", "href": "/privacy/" } ] } ], "related": [ "/guides/privacy-and-permissions/", "/blog/status-without-transcripts/" ], "updated": "2026-10-23", "url": "https://perched.fyi/glossary/local-first/", "markdown": "https://perched.fyi/content/glossary/local-first.md" }, { "category": "glossary", "slug": "tool-approval", "title": "What is a coding-agent tool approval?", "description": "A tool approval is your decision about a proposed agent action. Learn the difference between approving a tool, a plan and a completed result.", "lead": "A tool approval is a person’s decision about whether a coding agent may carry out a proposed action, such as running a command or making a change.", "sections": [ { "title": "Approve the actual action", "paragraphs": [ "Read the project and session as well as the proposed command or change. A familiar action can still be outside the intended task. If the request lacks enough context, open the original agent interface.", "Perch supports opt-in allow and deny actions for Claude Code and Codex. Cursor’s documented Perch action is a reply after a turn, not in-card tool approval." ] }, { "title": "Approval is different from verification", "paragraphs": [ "Allowing a tool gives it permission to act. It does not prove the action succeeded or that the result is correct. Likewise, agreeing to a plan is different from reviewing its eventual implementation.", "After a turn, inspect the work in the project. Perch’s two-second undo applies before an answer is sent; it cannot reverse a command that already ran." ] } ], "related": [ "/guides/answering-agents/", "/guides/agent-compatibility/", "/blog/human-in-the-loop-coding/" ], "updated": "2026-10-23", "url": "https://perched.fyi/glossary/tool-approval/", "markdown": "https://perched.fyi/content/glossary/tool-approval.md" }, { "category": "glossary", "slug": "context-switching", "title": "What is context switching in an agent workflow?", "description": "Context switching means moving attention between tasks or apps. Distinguish checking agent state from the focused work of reviewing its result.", "lead": "Context switching means moving your attention between tasks, projects or apps. In an agent workflow, one common example is leaving your work to check whether a terminal needs you.", "sections": [ { "title": "A check is different from a review", "paragraphs": [ "A status check asks whether something changed. A review asks what happened and whether it is correct. Keeping those questions separate can make your workflow easier to organize.", "Perch puts supported states at the screen edge so a routine check does not always require opening the agent. When a decision or result needs attention, you still read it in context." ] }, { "title": "Keep the useful switches", "paragraphs": [ "Switching to inspect a diff, understand a request or verify a result is part of development. Perch does not claim that all switching is waste or promise a measured productivity gain.", "Clear session names and short local notes can help preserve the detail you will need after an interruption. Keep lasting project decisions in your normal documentation." ] } ], "related": [ "/blog/reduce-agent-context-switching/", "/guides/sticky-notes/" ], "updated": "2026-10-23", "url": "https://perched.fyi/glossary/context-switching/", "markdown": "https://perched.fyi/content/glossary/context-switching.md" } ] }