Skip to Content
Tares

Should the code context agent update my existing pages in place or keep one page per repository?

Tares lets you choose the layout when you set up the Shared code context project. The default updates your existing pages in place and creates a page only when nothing covers the topic, which suits a repository that already has its own pages. One page per source repository plus an index suits a fresh folder. In both cases the agent writes by pull request (recommended) or by direct commit to the branch.

How it works

You choose the layout in step 3 of the setup wizard in the Shared code context guide. There you pick the context repository, the branch that pull requests target, and the path where the pages live. Leave the path empty for the repository root. Once you pick the repository, the page shows what is at that path, so you see the layout you are handing over. The context repository cannot also be a source repository.

Keep the existing pages, update them in place (the default)

  • The agent lists the folder and reads the index and the page that covers the change.
  • It corrects what the change made outdated and adds what is new, keeping the structure and voice of the page.
  • It creates a page only when no existing page covers the topic.
  • It fits a repository that already has its own pages, one per topic.

One page per source repository plus an index

  • The agent keeps one markdown file per source repository under the path, named after the repository, with a fixed section template.
  • It also keeps a README.md index that lists those files.
  • It fits a fresh folder.

How it writes

  • Pull request: the agent writes on a branch whose name starts with tares/context, then opens a pull request, and a person merges it. This is recommended.
  • Direct commit: the agent commits straight to the branch you chose.

The rest of the flow is the same for both layouts. Tares watches commits across your source repositories, batches them per repository once per five minutes, and runs the agent. The agent decides whether a change alters anything a teammate or an agent in another repository must know. It puts the commit’s short sha next to each claim it writes. It ends with a finding on the repository’s timeline that links the pull request, or says no update is needed and why.

Set it up

  1. Install and start Tares. This is part of the AI SRE setup too.
uv tool install tares
tares up
  1. Add an Anthropic API key under Settings > Model providers, or set ANTHROPIC_API_KEY.
  2. Create a GitHub fine-grained personal access token that covers the source repositories and the context repository. Set Contents to Read and write, and Pull requests to Read and write. GitHub starts every permission at Read-only, so check both before you generate the token. With Pull requests at Read-only, the agent can push its branch but the pull request fails.
  3. Open Projects, pick Shared code context and click Set up. In step 1, pick or add the credential. Use Test to see which GitHub login it belongs to.
  4. In step 2, tick the source repositories, up to 50, or paste owner/name lines. Each row follows one branch, the default branch unless you change it.
  5. In step 3, pick the context repository, the branch and the path. Then choose the page layout:
    • Keep the existing pages, update them in place, if the path already holds pages organized by topic.
    • One page per source repository plus an index, if the folder is fresh.
  6. Still in step 3, choose how it writes: open a pull request (recommended) or commit straight to the branch.
  7. In step 4, name the project and pick the model and the round budget. The default is 12 rounds, because reading diffs and pages, writing them and opening a pull request needs more than the plain 6. Keep First look on start on if you want the pages brought current from the last seven days of commits right away. Then click Start.

After Start, the project page shows the layout and the write mode under Setup. Edit reopens the wizard with your values.

What you get

  • Context pages that follow your commits instead of going stale the week after they are written.
  • With the in-place layout, your existing pages keep their structure and voice. New pages appear only for topics nothing covers.
  • With the per-repository layout, a predictable set of files: one per source repository with the same sections, plus a README.md index.
  • With pull requests, a person reviews every change before it lands. Each page claim carries the short sha of the commit behind it.
  • Under What the agents found on the project page, one card per change shows the pull request or the reason no update was needed.
  • Pause turns the trigger and the agent off while the sources keep ingesting. Delete removes what the project created.

When something else fits

  • Pick the in-place layout when the repository already has pages of its own. Pick the per-repository layout when you start from an empty folder and want a uniform page for each source repository.
  • Start with pull requests. Switch to direct commits to the branch once you trust the agent for a repository.
  • If your team’s pages need a different voice, edit the agent’s prompt on its own page. The project keeps your version.

Still stuck? Get help

Last updated on
Quickstart