ai-coworkers

# ai-coworkers

> A daemon with a job description. No chat window: it wakes on a clock or a webhook, reads its sensors, and acts inside a role you wrote in markdown, with its own responsibilities and boundaries. TypeScript, Node >= 22, MIT.

The distinctive thesis: agents live in a filesystem directory (role docs + state), run a game-clock tick loop (sense → perceive → deliberate → act), are gated by regex boundaries + dry-run by default, and escalate to a human inbox instead of guessing. Adapters let you plug in MCP servers, Hermes/OpenClaw skills, Vercel Eve `agent/` folders, or native tools.

## Docs

- [README](https://github.com/danieljohnmorris/ai-coworkers/blob/main/README.md): install, first coworker, tick loop overview, boundaries + dry-run, humans↔coworker messaging, adapter table, templates, operating notes.
- [ADR 0001 — CoALA memory taxonomy mapping](https://github.com/danieljohnmorris/ai-coworkers/blob/main/docs/adr/0001-coala-memory-taxonomy.md): how working / episodic / semantic / entity / procedural / reflective memory map to modules in this repo.
- [ADR 0002 — code.delegate speaks ACP](https://github.com/danieljohnmorris/ai-coworkers/blob/main/docs/adr/0002-acp-code-delegate.md): why we adopt Zed's Agent Client Protocol (Goose / Codex / Claude Code plug in unmodified), permission model, sandbox scope.
- [ADR 0003 — subprocess sandboxing + container isolation](https://github.com/danieljohnmorris/ai-coworkers/blob/main/docs/adr/0003-container-isolation.md): AICW_SANDBOX config, bwrap/firejail wrapping for the ACP delegated agent, and why per-tool container isolation is designed but deferred.
- [ADR 0004 — keep events.db as one file](https://github.com/danieljohnmorris/ai-coworkers/blob/main/docs/adr/0004-events-db-single-file.md): bench result — no cross-writer contention on our topology, so the theorised inbound/outbound split isn't worth the schema complexity.
- [ADR 0005 — evaluators + services (design spike)](https://github.com/danieljohnmorris/ai-coworkers/blob/main/docs/adr/0005-evaluators-services.md): proposed interfaces to close the ElizaOS gaps (per-action post-response hooks + long-lived push singletons). Design only; implementation staged.
- [systemd deployment](https://github.com/danieljohnmorris/ai-coworkers/blob/main/docs/systemd.md): running coworkers as user services.
- [Dedicated Linear identity for your coworker](https://github.com/danieljohnmorris/ai-coworkers/blob/main/docs/dedicated-linear-user.md): setting up a service account or OAuth app so the coworker posts under its own name, not yours (AIC-28).
- [Tool cookbook — Hermes / MCP / native](https://github.com/danieljohnmorris/ai-coworkers/blob/main/docs/tool-cookbook.md): decision tree for adding a new capability. Hermes first (best setup UX), MCP next (widest coverage), native last. Verified Hermes google-workspace skill loads via our adapter (AIC-16/17).
- [CONTRIBUTING.md](https://github.com/danieljohnmorris/ai-coworkers/blob/main/CONTRIBUTING.md): dev setup, PR flow, coding conventions, what we won't merge, security-issue reporting.
- [Release process + semver stance](https://github.com/danieljohnmorris/ai-coworkers/blob/main/docs/release-process.md): what MAJOR/MINOR/PATCH mean here, cut steps, deprecation policy, migration scripts.
- [Webhooks + external wakes](https://github.com/danieljohnmorris/ai-coworkers/blob/main/docs/webhooks.md): using the /wake endpoint to trigger ticks from Linear/Slack/GitHub webhooks.
- [Migration from Hermes / OpenClaw / Eve](https://github.com/danieljohnmorris/ai-coworkers/blob/main/docs/migration.md): exact source-format → destination-file matrix + what needs manual authoring after `bin/import-*.sh`.

## Runtime (src/runtime/)

- [tick.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/tick.ts): the game clock. Budget gate → sense → perceive → quiet gate → deliberate (chained tool calls) → boundary check → act → hygiene → rituals → sleep.
- [deliberate.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/deliberate.ts): LLM-facing prompt assembly + JSON decision parsing (`{action, tool, input, thoughts, reason, pace}`).
- [role.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/role.ts): loads `role/*.md` into a system prompt + parses `BOUNDARIES.md` resource limits.
- [boundaries.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/boundaries.ts): regex-based pre-execute check against every tool call.
- [semantic.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/semantic.ts): capped `MEMORY.md` with injection scan on write.
- [reflect.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/reflect.ts): the weekly "dream" — LLM compacts the week's events into learnings, cites source event IDs (AIC-70), enforces loss guards + snapshots.
- [role_audit.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/role_audit.ts): daily drift audit (ritual `role.audit`) that snapshots every role doc, flags Must-not-touch entries removed or cap values raised as `critical` findings, and escalates to `state/questions.md`. Advance the snapshot with `bin/audit-accept.sh <coworker> [DOC]`.
- [inbox.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/inbox.ts) & [reactions.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/reactions.ts): human → coworker channels (notes + 👍/👎 reactions) with cursor-based one-time presentation.
- [branch_room.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/branch_room.ts): per-branch narrative files (`state/branches/<branch>.md`) — coworker's running record of patches / CI / review / merge for each branch it touches. Exposed via `branch.note`, `branch.read`, `branch.list` tools.
- [entities.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/entities.ts): per-person + per-project cards, alias-aware detection in perception.
- [rituals.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/rituals.ts) + [rituals_loader.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/rituals_loader.ts): due-based scheduler for hourly/daily/weekly rituals. Rituals are declared in `role/rituals/*.json` (AIC-80) — falls back to built-in defaults if the dir is absent. Actions: `reflect`, `journal`, `role_audit`, `health_snapshot`.
- [budget.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/budget.ts), [tempo.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/tempo.ts), [circuit.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/circuit.ts): LLM-call budgets, tempo self-awareness, per-sensor circuit breakers.
- [rate_limits.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/rate_limits.ts) + [triage.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/triage.ts) + [metrics.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/metrics.ts): 429 detection + per-prefix cooldown (AIC-62), TRIAGE_MODEL cheap-first preflight (AIC-47), Prometheus `/metrics` on the wake server (AIC-67).

## Adapters (src/adapters/)

- [mcp.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/adapters/mcp.ts): MCP servers via `MCP_SERVERS` env var.
- [hermes.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/adapters/hermes.ts): Hermes/OpenClaw/Anthropic-style skills folders → procedural memory.
- [eve.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/adapters/eve.ts): Vercel Eve `agent/` folder loader.
- [acp.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/adapters/acp.ts) + [code_delegate.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/tools/code_delegate.ts): Agent Client Protocol client — spawns any ACP-conformant coding agent (Goose, Codex, Claude Code) as a subprocess and drives one prompt turn. Configured via `ACP_AGENT_CMD`. Delegated agent is jailed via bwrap/firejail when available (see sandbox below).
- [sandbox.ts](https://github.com/danieljohnmorris/ai-coworkers/blob/main/src/runtime/sandbox.ts): `wrapWithSandbox(argv, opts)` for subprocess isolation via bwrap or firejail on Linux. Env-configured with `AICW_SANDBOX=auto|off|bwrap|firejail`. Currently wraps the ACP delegated agent.

## Coworker templates (examples/)

- [generic-triage](https://github.com/danieljohnmorris/ai-coworkers/tree/main/examples/generic-triage): Linear triage engineer.
- [pr-reviewer](https://github.com/danieljohnmorris/ai-coworkers/tree/main/examples/pr-reviewer): reviews open PRs across watched GitHub repos.
- [project-manager](https://github.com/danieljohnmorris/ai-coworkers/tree/main/examples/project-manager): project health summaries, aging tickets.
- [scribe](https://github.com/danieljohnmorris/ai-coworkers/tree/main/examples/scribe): keeps README + docs honest as the code changes.
- [trace](https://github.com/danieljohnmorris/ai-coworkers/tree/main/examples/trace): incident RCA — reads traces, walks git history, posts root-cause notes.
- [log](https://github.com/danieljohnmorris/ai-coworkers/tree/main/examples/log): auto-changelog — updates CHANGELOG.md on merge, drafts GitHub releases on tag.
- [watchtower](https://github.com/danieljohnmorris/ai-coworkers/tree/main/examples/watchtower): monitoring — baselines operational signals and alerts on real anomalies, with aggressive dedup.

## Operator CLI (bin/)

- `bin/note-to.sh <coworker> "msg"`: leave a note that surfaces in the next tick's perception.
- `bin/answer.sh <coworker> "answer"`: answer a persistent question the coworker filed.
- `bin/react.sh <coworker> 👍|👎 [note]`: reinforcement signal, surfaces once then marked read.
- `bin/why.sh <coworker> <event-id>[,...]`: walk from a `[ev:...]` citation in MEMORY.md back to the source events.
- `bin/review-proposal.sh <coworker> [show|accept|reject <id>]`: handle role-doc change proposals.
- `bin/new-coworker.sh <name>` / `bin/new-coworker-interview.sh <name>`: scaffold blank or JD-interview-driven coworker.
- `bin/import-hermes.sh <src> <name>` / `bin/import-openclaw.sh` / `bin/import-eve.sh`: migrate an existing agent from Hermes / OpenClaw / Vercel Eve into an ai-coworker (see `docs/migration.md`).
- `bin/audit-accept.sh <coworker> [DOC]`: after reviewing `role.audit` critical findings, accept the current role docs as the new snapshot baseline.

## Optional

- [llms-full.txt](https://github.com/danieljohnmorris/ai-coworkers/blob/main/llms-full.txt): everything above with the linked doc bodies inlined.