Using Arco

Begin with a working name and the idea in plain language. The staged conversation helps describe what to build, who it is for and where the scope ends.

CREATE & SCAFFOLD creates a new project after confirmation. For an existing folder, SAVE PLAN creates a checklist and reference documents; it does not attach that plan to another workflow automatically.

Start an existing-folder draft from DRAFT IN GENESIS in the PLAN panel. Saving returns to the plan chooser, where the saved plan can be attached. SAVE PLAN creates SPEC.md and TODO.md only when they are missing.

Ask the agent directly

You can say: "Create a plan for this project and attach it to this workflow. Do not start implementing it." When no plan is attached, Arco sends the agent instructions for creating and attaching one. Supported Agent tabs have plan tools; you do not have to start with the PLAN button.

The tools can create and attach a plan, list existing plans, and read or write reference documents. Availability depends on the provider, mode and permissions. Local-provider tools require AUTO mode; ordinary Chat tabs and ISOLATED Native members do not receive workflow plan tools.

Open PLAN to confirm the plan is attached and review its checklist. A loose Markdown file is not an Arco plan. If the agent cannot complete the action, use the PLAN button, which the manual recommends as the most reliable route across providers.

Attach a plan with the controls

In the composer, open PLAN and choose DRAFT → I'LL REVIEW. Read the draft, use REFINE if needed, then choose SAVE & ATTACH or, in a cluster, ATTACH TO CLUSTER.

To reuse a plan, open the PLAN panel and use PREVIEW before ATTACH. A cluster without a plan also offers DRAFT A PLAN and ATTACH EXISTING. Its attached plan is shared with the members.

Keep the checklist readable

Use checklist items for the work itself. Put supporting specifications, research and decisions in reference documents, then link them from the relevant items. The panel refreshes when agents edit the plan. Its checkboxes can also be changed directly.

Track execution separately

A checked plan item records progress against the plan. A board task carries an owner, status, dependencies and discussion. A plan task can be promoted to a board task; attaching a plan does not mean every item has been assigned.

For example, the plan might say "Build and check the empty state." The board can track the implementation with Builder 1 while a separate task tracks testing. Open Task board to follow that work through review and acceptance.

Create and follow a task

Add a task on the board; it starts in TODO. Open its card to edit the title, notes, priority and dependencies. A plan task or a delivered peer message can also be promoted to a board task.

The board has TRIAGE, TODO, READY, IN PROGRESS, BLOCKED, REVIEW, DONE and ARCHIVED states. Tasks can carry comments and run history. Dependencies and a blocked reason show what must happen before work can proceed.

Review before accepting

Members report results into REVIEW; their tools cannot directly set DONE or ARCHIVED. Read the evidence before selecting ACCEPT. That click accepts one task. Dragging to DONE or ARCHIVED, and bulk acceptance, ask for confirmation.

SETTINGS > Agents and clusters > Board auto-done is off by default. If enabled, it marks review tasks done when the Director signs off as met, without a separate ACCEPT click.

Choose the scope and automation

A new cluster starts with its own board. The creator and board bar can instead select the project board or no board. Check the scope before expecting another cluster to share the same tasks.

AUTOMATION contains the task dispatcher and recovery tools. Dispatch is off by default and must be armed by the operator. Board dispatch handles eligible tasks; AUTO-PICKUP handles waiting peer mail. They are separate settings.

A NORTH STAR is guidance, not permission to continue working on its own. It is separate from the attached plan.

PLAN FIRST applies to one turn and is hidden for cluster roles that do not edit code. It blocks the Write and Edit tools until plan mode ends, but does not block shell commands. It is not a filesystem sandbox.

Members read mail with their peer tools. A waiting-mail notice can arrive with the next turn; the member still needs to read the mailbox. A card shows the waiting count. The mark is muted while the member is busy and highlighted when an idle member has mail.

Open MAILBOX to inspect pending notes. Automatic mailbox reminders are folded in chat and HISTORY; select + to read the full text.

Open NUDGE, choose recipients and select SEND NUDGE. No recipients are selected initially. As an alternative, NUDGE ALL WITH MAIL immediately sends a reminder to every member with waiting mail, whether idle or busy. It does not merely select the checkboxes.

A highlighted mail mark on an idle member can also be clicked to nudge it. The reminder does not empty the mailbox. Providers without mid-turn steering receive the reminder after the current turn.

MAIL ALERTS reports an idle member with pending mail. Despite the documentation's "idle nudger" name, it does not send prompts to agents.

AUTO-PICKUP offers Rule-based, which wakes idle members for mail that asks for work and filters acknowledgements. Limits reduce repeated back-and-forth wake-ups.

Smart modes need a chosen evaluator model. Observe-only records decisions without starting members. Automatic may start a turn after Arco checks the member, mail and limits again. Turning pickup off prevents further starts; an existing turn finishes normally.

Also remind busy members is a separate option under Rule-based and Smart: Automatic. It is off by default. When enabled, actionable unread mail can send a busy reminder once per batch, with at least five minutes between reminders to the same member. It does not run in Observe-only.

The composer starts with the member in view as recipient. Select one or several recipients; EVERYONE selects all. Idle recipients start a turn and busy recipients receive a follow-up.

HISTORY follows the member in view. Under MEMBERS, SAVE STATE saves a cluster snapshot. Restoring a saved snapshot creates a new cluster rather than changing the original.

Choose a template or Build my own. Pick each member's provider and model, optionally choose a plan, then select CREATE CLUSTER. In the opened cluster, select a member card to open its conversation.

Director or coordinator

Tracks the plan, delegates and checks results. Either name counts toward the one-Director limit.

Builder

Implements an assigned part of the work.

Tester

Runs project checks and tests changes where a real fault is likely.

Reviewer

Inspects changes and reports concerns.

Researcher

Investigates focused questions.

Documenter

Writes or updates documentation.

Roles guide the work; they are not permission boundaries. Role hints and work size do not select a model or change its effort. Choose from the connected providers offered for that member; not every provider supports every mode.

Connections has a cluster capacity setting for Ollama and llama.cpp. Provider billing follows the selected provider's terms; model and effort choices follow its available catalog.

Review a change

Choose the reviewer and scope before starting. SUB-WORKER runs a separate reviewer and saves an artifact. A cluster member can review LAST TURN or LAST N TURNS; its findings appear in that member's conversation, not a review artifact.

Plan, full-history, current-session, checkpoint and Git-diff scopes require SUB-WORKER. Member choices are disabled for those scopes. Read the findings before deciding what to change or accept.

Review the plan or verify the work

REVIEW PLAN starts in CRITIQUE mode: examine the proposed plan. VERIFY WORK starts in VERIFY mode: check claimed-completed items against the actual code. It has INCLUDE GIT DIFF selected initially.

The mode can be changed in the dialog. Phase review controls narrow the scope to a section. CUSTOM REVIEW allows items from different sections to be selected together.

A review produces findings. Accepting a board task is a separate action; see Task board.

Choose the models and review what context they will receive. Blind hides model names until a draft is picked.

USE THIS REPLY puts a draft in the composer. Edit it before sending.

Set the new direction and choose a model and effort. This suits a separate line of investigation or a different piece of work.

For a fresh session in the same tab, use HANDOFF instead.

After a successful spawn, From in the seed or HANDOFFS opens the earlier conversation at the saved boundary. Show full history removes that display filter. Source links survive restarts; archived or deleted sources are unavailable until a retained archive is restored.

Set Maximum running at once, Maximum starts per turn and Sub-agent model. Changes apply on the next parent turn. Blank tab limits inherit Settings; blank Settings limits use the defaults. Agent's choice keeps the agent's model choice, while a selected model overrides it.

Extra admitted tasks queue. Calls beyond the turn budget are refused. Use CANCEL on a queued or running task to stop it; stopping the parent stops both. A queued cancellation returns its reserved place, but a child that already started counts toward the budget.

These controls apply to Claude Native Agent tabs outside clusters. Claude CLI, Codex and Cursor keep their own sub-agent behavior. This is not the operator's SPAWN action, and it adds no ask-first approval prompt or spending cap.

REVERT TO HERE restores the files included in that checkpoint and can remove files created since it. The confirmation explains what will change.

Non-Git checkpoints exclude nested repositories and worktrees. Older checkpoint formats have different scope limits. Read the checkpoint's exclusions and confirmation rather than treating it as a full-folder backup.

Use the file views to inspect source and diffs. OUTPUTS collects generated files for the current workflow or cluster; a cluster identifies which member produced each result.

Start the development server before opening PREVIEW. Arco discovers preview ports; preview configuration and remote forwarding are separate from starting the server.

Send a file to an agent

Use + FILE, paste or drop an attachment. Image-capable models receive fitted images. PDFs, Office documents and notebooks are decoded as text or supported images; text-only models receive descriptions instead of image inputs. File readers can select document pages, sheets, slides or cells. Public image and document URLs use the same guarded decoding.

Large JPEG and PNG uploads can be replaced by smaller versions in Arco's upload storage, without keeping a full-size upload backup. This does not rewrite project images read through file tools. Keep an original separately when its full resolution matters.

Remote PREVIEW access also needs the separate preview ports forwarded. Follow the preview access instructions.

ARTIFACTS

Browse project cards and agent-produced results.

CHANGED FILES

Find files changed by any program in the last 48 hours. Incomplete scans are marked.

PLANS

Browse plans across projects, edit them or mark completed plans done.

STORAGE

Inspect disk use and review cleanup actions. Each cleanup action asks first.

TREE

Browse the file hierarchy.

For the current conversation's results, use FILES > OUTPUTS.

Open another session or pop the terminal into a separate window. Reopening a session restores its recent output.

Commands can be placed in the terminal for review without running automatically. Selected output can be sent to the composer for the agent to read. Use the session's explicit kill action to stop it.

Select a pull request to read its description and diff. Actions runs show jobs and logs; the Code view can switch branches.

Repository access uses the configured GitHub connection. Actions such as CREATE PR write to GitHub when submitted.

Select an output's name or image to open its preview. The producing workflow remains attached even if a different tab is in view. Editor saves and exported variants appear under that workflow.

For images, FIT fits the view and 1:1 shows actual pixels. EDIT opens the editor. Saving an existing image asks before overwriting it.

Audio and video operations need FFmpeg and write new files. Imported files are staged before conversion. Optional stem separation needs Demucs; opening the viewer does not install it.

Open PENDING to inspect queued messages. EDIT removes a pending message from the queue and appends its text to the current draft, preserving its kind, attachments and selected skills.

Already-delivered messages cannot be taken back. For Claude and Codex, INTERRUPT & SEND stops the current turn before sending the correction. Completed file edits remain in place.

After EDIT, SEND or Enter preserves the restored kind. Alt+Enter explicitly chooses a follow-up; INTERRUPT & SEND chooses an interruption where available. Once idle, the message starts an ordinary turn.

Manual compaction

Wait for the current turn to finish, then select COMPACT. The button is available for Claude Native, Codex app-server, Cursor and Ollama. Typing /compact uses the same action wherever the button is available. While the agent is busy, Arco keeps the draft and asks to wait.

The same tab continues with a smaller context. COMPACT never sends a continuation message itself. After Claude Native compacts between turns, COMPACTED: CONTINUE resumes the work; dismissing it leaves the agent idle.

Automatic compaction

Under AUTO-COMPACTION, use the provider default or choose Off or On with a threshold. Claude Native and Ollama can use Arco compaction. Claude CLI and Codex compact through their own runtimes. Claude Native can also compact inside a running turn and continue that turn.

COMPACTION AUTO-CONTINUE applies only to automatic compactions between turns. It does not make the manual COMPACT button resume work.

Compaction, FOLD or HANDOFF?

Compaction summarizes earlier history. Claude Native FOLD builds a digest without a model call and keeps a recent verbatim tail. HANDOFF starts a fresh session with context carried forward. Summaries can lose detail; keep important requirements in the attached plan and its references.

QUICK builds the starting context from recent conversation, the action digest and Git state. A written handoff is another option. Review the mode and destination before proceeding.

AUTO-HANDOFF in CONFIG is off by default. When enabled, it hands off at the end of a turn after a chosen number of compactions. It is available only where Arco can count the provider's compactions.

After a successful handoff, From in the seed or HANDOFFS opens the earlier conversation at the saved boundary. Show full history removes that filter. Eligible Agent tabs can also retrieve earlier turns with their handoff-history tool. Chat, Incognito, BLIND and ISOLATED conversations are excluded.

For a native package install, install uv and run arco voice setup, or use the guided setup. Test the microphone and recognizer before enabling hands-free mode. Docker does not include the voice runtime.

Microphone access requires the local app address or HTTPS. "Cancel capture" discards an unsent directive. "Stop listening" turns listening off. Reloading or disconnecting also disarms the microphone; turning it back on requires a button or shortcut.

Recognition uses local speech components. The selected Computer provider may process the request remotely, and online speech options send text to their service.

Choose an agent and select USE AGENT. Computer has its own provider, model and conversation. It does not browse the web or run shell commands; those requests belong in a worker conversation.

Computer also supports watches and conditional scripts. A watch reports when current work finishes. A conditional script can send a message or nudge when its conditions are met. Review its targets and limits; a script can be paused or cancelled separately from a pending voice capture.

Choose an offered provider and model, save the choice and use TEST to check it. Nothing is selected silently. CLEAR removes the saved choice.

The utility agent has no tools and uses facts Arco already holds. Requests still go to the chosen provider. Some local choices require the selected model to be loaded first.

CATCH ME UP uses activity since the earlier of the last visit or last operator message. An empty range offers SINCE LAST TURN, LAST HOUR and TODAY.

In a cluster, BRIEF offers THIS WORKER or WHOLE CLUSTER. It lists the facts behind the answer and sends nothing to the working agents.

Review or edit the proposed wording. REFINE adds instructions, and KEEP ORIGINAL discards the proposal. UNDO TIDY restores the original until the draft changes.

APPLY ONCE adds the skill to the next turn. PIN TO TAB reapplies it until its visible chip is removed. Cluster-wide skill pinning is not available in 0.1.5.

IMPORT accepts a public GitHub link, local folder or zip. REVIEW shows the files and security findings before IMPORT saves them. UPDATE shows per-file changes before APPLY UPDATE. TURN OFF keeps the skill but removes it from the agent's list and active pins.

MOVE TO GLOBAL, MOVE TO PROJECT and DUPLICATE manage scope. Project skills are ignored by Git. SHARE WITH REPOSITORY previews the files and adds an exception for that skill; it does not stage or commit them.

Built-in skills carry OPERATOR or MODEL badges. Operator skills offer RUN; EDITABLE COPY saves an editable version. Architecture review reports candidates without changing code. The model-invoked proportionate-testing skill guides how much to test and asks before adding suites, gates, tooling or CI checks.

SHOW IN BELL controls the categories shown there. Desktop alerts need browser permission; TEST DESKTOP checks that setup.

Phone alerts are a separate opt-in feature. Notifications report activity; they do not accept remote commands.

Choose POINT AT THINGS, then click a control to read its help. Press Escape to leave help mode.

Open USER MANUAL for the indexed guide. The interface groups side panels under WORKSPACE, AGENT, MEMORY and RUNTIME.

Choose the appearance and text size that are comfortable to read. On narrower layouts, panel controls can move into grouped menus; the manual describes where to find them.

Use arco update to update an existing package install. It stops the service before replacing the package and protects the previous installation for rollback. Finish or cancel running turns and save drafts and edits first.

The version box opens the update dialog. Packaged background services and Linux source user services offer UPDATE AND RESTART after confirmation. Other run modes show the applicable command.

Check for new releases and CHECK NOW are under SETTINGS > Advanced > CLI and runtime versions. Release checks do not install updates.