Skip to content

docs: explain GitHub operating model and token economics - #1

Merged
Stolyarovmn merged 1 commit into
mainfrom
codex/readme-github-operating-model
Apr 27, 2026
Merged

Stolyarovmn merged 1 commit into
mainfrom
codex/readme-github-operating-model

Conversation

@Stolyarovmn

Copy link
Copy Markdown
Owner

Summary

This PR expands the README with the rationale for using GitHub as part of the Hybrid Agentic OS rather than keeping the whole control plane local-only.

It explains:

  • why GitHub is used as a durable shared control plane for framework development;
  • which responsibilities move from local runtime files into GitHub-native surfaces;
  • which pieces remain local by design;
  • how the split saves LLM tokens by moving deterministic coordination into Issues, PRs, Projects, Actions, labels and templates.

Why this is better

The local runtime is still the fast execution layer: STATE.md, targets/*.local.md, tasks/TASK-*.md, inbox/, outbox/, tmux sessions and credentials remain machine-local.

GitHub is used where it is stronger and cheaper than agent context: durable IDs, timelines, review comments, PR diffs, status checks, labels, project views and issue forms. That means agents spend fewer tokens rediscovering state from chat or scanning local files, and more tokens on judgment, implementation and audit.

Verification

  • git diff --check
  • bash -n *.sh lib/runtime.sh
  • ./smoke-runtime.sh

@Stolyarovmn
Stolyarovmn merged commit cd876ff into main Apr 27, 2026
1 check passed
@Stolyarovmn
Stolyarovmn deleted the codex/readme-github-operating-model branch May 25, 2026 08:22
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