Coworker Architecture and Runtime

1. The workspace shape

The README makes the main product shape clear:

Area	Why it matters
desktop shell	user-facing local app
local action runtime	does the real work on files and tasks
provider layer	supports many remote and local model backends
tool connections	integrate with external productivity systems
approval and logs	keep the user in control

That is the right architecture for a local productivity agent.

2. The runtime mental model

At runtime, Coworker generally does this:

1. the user gives a task,
2. the selected model reasons about the task,
3. the local runtime proposes or performs actions,
4. the user reviews, approves, or stops the work,
5. logs and results remain visible.

3. Why the local-first design matters

Coworker is strongest when users want:

• their files to stay local,
• their own provider choice,
• and a system that can be inspected and interrupted.

That local-first posture is not marketing fluff. It shapes the whole runtime design.

4. Why approval is part of the architecture

The README explicitly says you approve every action and can inspect logs. That means review is part of the product contract, not an afterthought.

5. What to read first in code

Start with:

1. the README overview,
2. desktop shell and local-runtime code,
3. provider integration surfaces,
4. logging and approval behavior.