// Local-first agent harness for macOS
One agent harness
across your whole group of repos.
Arc points the Claude and Codex subscriptions you already pay for at every repository in a group, with lasting notes, docs and playbooks attached. Ask once. A brain plans the work, workers fan out across the repos, and the result lands on one session branch for you to review.
- Providers
- Claude Code + Codex CLI
- API keys
- None needed
- Runs on
- Your Mac, locally
- Telemetry
- None
// 01 The problem
CLI agents see one folder. Your system spans six.
Real products live across a handful of repositories and a database. Today that means re-explaining context every session, juggling terminals, and guessing how much quota is left.
-
One folder at a time
Context stops at the repo edge
Schemas, the other services and how they talk get pasted in by hand, again and again.
-
Lost sessions
Close the terminal, lose the thread
Long investigations vanish with the shell that ran them.
-
Invisible quota
Rate limits arrive unannounced
It is hard to tell how much subscription usage is left until you hit the wall.
Arc answers all three: a session sees every repo in a group plus its knowledge, sessions are saved and resumable, and usage is always on screen. Everything runs through your existing Claude and Codex subscriptions, with no separate API billing.
// 02 Groups and knowledge
Organize repos into groups. Give them a memory.
Pick local folders and gather them into a named group, say "Storefront" with web, api and infra. Each group carries lasting knowledge, so you stop re-explaining your system.
-
/projects
Projects
Code repositories the agents can read and modify.
-
/notes
Notes
Free-form notes you write for the agents, like how the services talk to each other.
-
/docs
Docs
Reference material: schema-only database dumps, API specs, architecture write-ups.
-
/playbooks
Prompts and Playbooks
Reusable instructions such as "how we write migrations" or a release checklist.
-
/links
Links
URLs to internal wikis or external docs that agents fetch with their own tools.
-
/custom
Custom sections
Name your own sections for anything else the agents should know.
Knowledge is stored as plain files in Arc's data folder by default. Link any group to a folder you choose, such as a git repo, to version and back it up. Every session belongs to one group and can see all of its projects and knowledge.
// 03 Brain and workers
A brain that plans. Workers that fan out. One branch at the end.
-
01 / PLAN
Ask once, from the group
"The orders report query is timing out. Find out why and fix it." The brain reads the group's schema and notes, then decides which workers to start, on which repos, with which provider and model.
-
02 / SPAWN
Workers fan out, one per sub-task
In plan-first mode nothing runs until you approve the plan. In autonomous mode the brain spawns workers on its own, up to the worker cap you set.
-
03 / WORKTREES
Every worker in its own worktree
Starting a session creates a session branch off
devin each repo. Each worker gets its own git worktree at the tip of that branch, so several workers can change the same codebase at once without stepping on each other. -
04 / MERGE
The brain merges, one at a time
When a worker finishes, the brain merges its work into the session branch, queued one merge at a time per repo. If another worker needs that change, the brain syncs it into the waiting worker's worktree and tells it what changed and why.
-
05 / RESOLVE
Conflicts get their own resolver
On a conflict, a short-lived resolver worker fixes it in a temporary merge worktree. The brain never edits code itself, and the resolver only escalates to you when it is not confident. You review the combined diff on the session branch; Arc never pushes or merges into
dev.
// 04 Spawn mode
Plan-first or autonomous. Your call, per session.
Proposed plan // awaiting approval
| Worker | Task | Provider / model |
|---|---|---|
| W1 api | Inspect the API's query code | Claude / light changed to strong |
| W2 infra | Review recent infra changes | Codex / second opinion |
The brain lists the workers it intends to start and the model for each. Nothing runs until you approve, and you can change any model first.
Autonomous // worker cap
3 / 4 workers
The brain spawns workers on its own, up to the cap you set. Once a plan is approved, or in autonomous mode, workers edit files and run commands freely, and you review the resulting diffs at the end.
// 05 Session branches
Real git, kept tidy for you.
The session branch is checked out in your own folder, so you can look at the combined work in your own editor at any time.
Layout
- Session branch
- arc/<session-slug>
- Branched from
- dev (or the default branch)
- Worker worktree
- ~/Library/Application Support/Arc/worktrees/<session-id>/<worker-id>/<repo>
- Cleanup
- Worktrees are removed once merged; session branches stay until you delete them.
Merge rules
- Merges happen in a temporary merge worktree, then the session branch moves forward.
- Uncommitted changes are never discarded: Arc asks you to stash, commit, carry them over, or cancel.
- If your checkout has unsaved changes, the merge waits and is applied later.
- Pushing, opening pull requests and merging into
devstay with you.
// 06 Needs attention
Questions bubble up. Only the hard ones reach you.
When a worker needs a permission it does not have, or has a question, it pauses and asks the brain first. The brain answers from the plan, the group's knowledge or other workers' results. Anything it cannot, or is not allowed to decide, is escalated to you.
- Workerpauses and asks
- Brainanswers what it can
- Youapprove, deny or answer
Wants to run a command outside its change policy.
Should the report page show the new field by default?
- Who, what and why. Each alert shows which worker raised it, what it wants, and why. Your answer goes back to the worker and it resumes.
- Hard to miss. A pulsing amber badge with a count sits in the session header, the waiting worker shows as an amber card, and a macOS notification arrives when Arc is in the background.
- Never a pile-up. Alerts live in one dialog, not a growing column in the session view.
- Survives restarts. Pending requests persist when you close and resume a session; workers stay paused until answered.
- Guard rails. Policy decides what the brain may approve without you, for example anything outside a worker's worktree or a destructive git command.
// 07 Models and usage
The right model per worker, with your limits in view.
The brain picks a provider and model for each worker based on how complex the task is and how much subscription usage you have left: a lighter model for simple lookups, a stronger one for complex changes, or Codex for a second opinion. Override it for the whole session or any single worker.
Usage // illustrative
- Mix providers in one session. Claude Code and Codex workers side by side.
- Usage-aware. When limits are close, the brain switches to lighter models.
- You have the last word. Session-level and worker-level overrides always beat the brain's choice.
// 08 Sessions that last
Pick up tomorrow where you left off today.
Saved and resumable
Nothing lost when the window closes
Sessions are saved with the brain's conversation, worker reports and changes. Reopen one the next morning and ask a follow-up.
Learning loop
The brain suggests what it learned
At the end of a session the brain can propose new or updated notes and docs. You accept or discard each one.
"The orders table is partitioned by month."
// 09 Terminals on demand
Chat first. Step into any worker's terminal.
The main view is a clean chat with the brain and a live list of workers. Open any worker's real terminal to watch, or step in: Arc pauses the headless process and attaches an interactive session for that worker, then hands control back when you are done.
Under the hood Arc drives the locally installed Claude Code and Codex CLIs, so it runs on their logged-in subscriptions.
// 10 The local MCP bridge
Agents coordinate through a bridge on your machine.
Arc hosts a local MCP server on 127.0.0.1 with a per-session token. Every agent process is
configured to use it, so the brain and workers talk through typed tools instead of scraping terminals.
Brain tools
- propose_plan
- spawn_worker
- message_worker
- get_worker_status
- merge_worker
- sync_worker
- get_usage
- resolve_request
- escalate_to_user
- ask_user
- suggest_knowledge_update
Worker tools
- report_progress
- report_done
- ask_brain
- request_dependency
- request_permission
A headless worker's permission prompt becomes a bridge call instead of a hung prompt.
// 11 Security and privacy
Local by design. Nothing phones home.
-
No API keys
Your subscriptions, your logins
Arc never handles credentials. The Claude and Codex CLIs handle their own login; Arc only tells you which login command to run.
-
No telemetry
No backend, no cloud
Everything runs on your Mac. The app makes no network calls of its own, and crash reports are written locally only.
-
Strict CSP
Locked-down renderer
A strict Content Security Policy, no new windows, and no navigation away from the app's own pages.
-
Typed IPC
Validated at the boundary
Every IPC channel is declared once and every message is checked with zod. Context isolation is on and there is no Node in the renderer.
-
Scoped files
Knowledge stays in its folder
Knowledge files are served through a custom protocol that only resolves paths inside the group's knowledge root.
-
Local bridge
Loopback only
The MCP bridge listens on 127.0.0.1 and every session gets its own token.
// 12 Get Arc
Bring your whole system into one session.
Arc for macOS, Apple Silicon first. Bring a Claude or Codex subscription and the matching CLI, installed and logged in.
- macOS, single user
- Claude Code and/or Codex CLI on your PATH
- Personal build: signed ad hoc, not yet notarized