02_shared_context

02 · Shared code context

A team keeps its shared context (what each service does, its endpoints, config, conventions) in one GitHub repository. This cookbook has Tares keep that repository current on its own: it watches commits across two sample services and, when something a teammate must know changes, an agent updates the context repo and opens a pull request.

It uses the Shared code context template shipped with Tares (1.14.0 or newer): one call creates the sources (one per repo), the timeline view, the trigger, GitHub's hosted MCP server bound to your token, and the maintainer agent. Nothing to deploy; the agent runs inside Tares.

Outcome measured: for three real changes (a new required env var, a new endpoint, a renamed CLI flag), whether a correct pull request appears against the context repo, and how long after the commit it lands.

Prerequisites

• uv (or Python 3.11 / 3.12 with pipx): it installs Tares and runs the cookbook scripts.

• Tares 1.8.1 or newer running locally. Not running yet? Install and start it (the console opens at http://127.0.0.1:8787; leave it running in its own shell):

  uv tool install tares        # or: pipx install tares
  tares up

• An Anthropic key for the maintainer agent (it is a real agent): set it under Settings > Anthropic in the console, or export ANTHROPIC_API_KEY=sk-ant-... before tares up.

• A GitHub account (user or a throwaway org). Setup step 1 creates three small repos from our templates and a token scoped to them; that is all the GitHub side needs.

Docker is not needed for this cookbook; the systems it watches are GitHub repositories.

Setup

1. Three repos from our templates (one click each; private is fine, keep the names):

• create tares-cb-orders-service
• create tares-cb-billing-service
• create tares-cb-context

Pick your user or org as the owner on each. Different names? Set SAMPLE_PREFIX below to your prefix.

2. One token on those three repos: new fine-grained token

• Repository access: Only select repositories, pick the three from step 1
• Contents: Read and write (read the services, write the context repo)
• Pull requests: Read and write (open the pull request in the context repo)
• Metadata: Read-only (GitHub adds this for you)

GitHub starts each permission at Read-only; check Contents and Pull requests both say Read and write before you generate the token. It should look like this:

3. Wire Tares:

# from the repo root: venv + deps
uv venv && uv pip install -e . && source .venv/bin/activate
cd cookbooks/02_shared_context

export GITHUB_TOKEN=github_pat_...     # the token from step 2
export GITHUB_OWNER=<your user or org>
# optional: SAMPLE_PREFIX (default tares-cb), CONTEXT_LAYOUT (per_repo | existing), TARES_URL

python setup.py

setup.py checks the three repos are there, stores the token in Tares as the credential cookbook-github (Settings > GitHub), and creates the project cookbook shared code context. It prints the case URL; open it. First look on start is off in this cookbook so the only runs you see are the ones the scenario causes.

Run the scenario

python scenario.py

It commits three changes, one per beat, then polls the project:

1. orders-service: STRIPE_WEBHOOK_SECRET becomes a required env var (config and README)
2. billing-service: a new endpoint GET /invoices/{id} (README)
3. orders-service: the CLI flag --port is renamed --listen (code and README)

For each run it prints the repo, status, rounds used, the pull request link and the time from the commit to the run, then lists the open pull requests on the context repo. Expect the first run about two to three minutes after the first commit (60s source poll, 2m trigger window); the two orders-service commits are batched into one run when they land inside the trigger's 5m cooldown, which is by design.

Then read the pull requests: each page should say what changed with the commit's short sha next to the claim, and nothing about refactors or formatting.

What you'll see

A real run (claude-sonnet-4-6, per_repo layout, 2026-08-19):

change	run	rounds	pull request	commit to run
new endpoint (billing-service)	ok	6/12	creates tares-cb-billing-service.md and the index; GET /invoices/{id} under Interfaces with (f8b6cc6), ORDERS_URL under Configuration, dependency on orders-service	102s
new required env var and renamed CLI flag (orders-service, batched)	ok	6/12	creates tares-cb-orders-service.md; POST /webhooks/stripe and STRIPE_WEBHOOK_SECRET with (40e873c), --listen with "was --port before (b3d34d7)"	123s

Both pull requests add the same index README, so merging one makes the other show a conflict on that file; that is the demo shape (two first pages at once), not something a real team sees, where the second run reads the merged index.

Numbers vary by model and by how the commits fall into the trigger window; treat them as directional.

Teardown

python teardown.py     # deletes the project, its objects and events, and the credential

Want to run it again? Put the repos back to their template state first, then set up again:

python reset.py        # rewinds all three repos to their initial template commit; closes demo PRs, deletes their branches
python setup.py && python scenario.py

reset.py rewinds the branches, it does not add commits, so the repos look freshly created and the next run's pull requests read cleanly. setup.py also waits until no sample repo has a commit younger than the trigger's window before creating the project, so setup never wakes the agent by itself; the only runs you see are the ones scenario.py causes.

The GitHub repos stay; delete them yourself if they were throwaways.

Layout

cookbooks/02_shared_context/
  samples/            ← what the two service templates contain, for reference
  tares_client.py     ← credential, project, summary (REST)
  github_client.py    ← repos, files, pull requests (REST)
  setup.py            ← credential + project against your three template copies
  scenario.py         ← the three changes and the timing loop
  teardown.py         ← remove what setup created in Tares
  reset.py            ← put the three GitHub repos back to their template state