Skip to content

[codex] document concurrency model#308

Merged
everettjf merged 3 commits intomainfrom
codex/document-concurrency-model
Apr 1, 2026
Merged

[codex] document concurrency model#308
everettjf merged 3 commits intomainfrom
codex/document-concurrency-model

Conversation

@everettjf
Copy link
Copy Markdown
Contributor

Summary

This PR adds a repo-tracked architecture note that explains MicroClaw's current concurrency model in direct response to issue #307.

The issue is valid in one important sense: one individual agent run is still sequential through src/agent_engine.rs, so a single turn can still be busy while it is inside LLM calls, tool execution, or compaction.

At the same time, the repo already has several non-blocking lanes that are easy to miss if you only look at the shared agent loop in isolation:

  • independently spawned channel runtimes in src/runtime.rs
  • streamed web runs with replayable SSE events in src/web/stream.rs
  • background scheduler and reflector tasks in src/scheduler.rs
  • session-native subagents with durable lifecycle and completion announce flow in src/tools/subagents.rs

The goal of this PR is to make that distinction explicit in the docs, so we do not answer the issue with either overclaiming or underselling the current architecture.

User impact

Users asking for a more Spacebot-like model now have a canonical document that explains:

  • what is already concurrent today
  • what is still strictly sequential
  • why binary size is mostly orthogonal to the concurrency question
  • which existing features (/api/send_stream, sessions_spawn, subagent announce/tuning) already help with responsiveness
  • which gaps remain on the roadmap

Changes

  • added docs/operations/concurrency-and-responsiveness.md
  • added a short concurrency note near the streamed web API section in README.md
  • linked the new note from the README documentation index

Validation

This PR changes documentation only.

I validated the technical claims against the current code paths referenced above while preparing the note.

@everettjf everettjf marked this pull request as ready for review April 1, 2026 20:22
@everettjf everettjf merged commit 3aa3c52 into main Apr 1, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant