Get started

How we keep our docs in sync with the code

The docs agent we run on Kortix — connected to GitHub and our codebase. Once a day it checks the code that landed since its last run and updates the docs those changes affected, opening a PR for review.

OpenChatly
Written by
The OpenChatly Team
Published
July 5, 2026
Reading time
7 min read
Topics
Documentation, Case Study, Engineering

Documentation tends to fall behind the code. The README, the setup guide, the API reference, and architecture notes drift a release or two back while the code keeps changing. The person who changes the code is usually not the person who owns the page it affects, so the two rarely get updated together. A renamed environment variable, a new setup step, or a removed endpoint is a small code change and a docs change that often goes unmade.

We handle this by running a docs sweep close to when the code changes: once a day, over everything that merged since the last run. This writes up how we run that on Kortix — the connections, the steps, and the guardrails — so you can set up the same thing for your own repo.

Team
Kortix
Source of truth
The codebase
Connected systems
GitHub · Codebase · Docs site
Mode
Daily sweep · PR-gated

The problem

The common fixes each have limits. "Docs are part of the PR" tends to get cut under deadline. A scheduled audit finds drift late and in bulk, when reconstructing what changed is hardest. And a generic AI writer pointed at the docs produces prose that doesn't match the code, because it never reads the code.

We wanted the docs we already have to stay accurate to the code, updated on each merge rather than in periodic cleanups.

What we built

On Kortix, a docs agent runs once a day in the same persistent session — a cloud sandbox — with scoped access to what a docs update needs: the commits that landed since its last run, the codebase for context, and the docs. It picks up from a checkpoint it kept from the previous run, determines what changed, rewrites the affected pages, and opens a single docs PR for review. Nothing publishes without a human merge.

How it works

1

Copy the setup prompt into a new session

Open your Kortix workspace, start a new session, paste this prompt and send it. The agent writes the agent file, the docs sync skill and the daily trigger, and opens a change request for you to review. Prefer clicks? Choose Use this template instead.

Setup prompt

Set up a daily docs maintainer agent in this workspace.

  1. Create the agent agents/docs-maintainer.md. Its job is to keep the docs in owner/repo accurate to the code. It may use the GitHub connector and open pull requests.

  2. Create the skill skills/docs-sync/SKILL.md with these rules:

    • Read the last checkpoint commit from memory/docs-sync-log.md, then read every commit that landed since then.
    • Read the changed code in full, not only the diff.
    • Find every page under docs/ and every README that the change made wrong. Update only the affected section.
    • Docs and READMEs are the only files you edit. If the code looks wrong, log it for a person. Never change code.
    • Group the day's changes into one pull request, with the commit that prompted each one. Never merge it.
    • If nothing doc-visible changed, move the checkpoint forward and stop without a pull request.
  3. Add a cron trigger daily-docs-sync to kortix.yaml. It runs the docs-maintainer agent every day at 06:00 with the prompt "Load the docs-sync skill and run one docs sync pass on owner/repo."

  4. Tell me which of these connectors are not connected yet.

  5. Open a change request with all of it. Do not merge it.

2

Connect your tools

Open Connectors in your workspace and connect GitHub. Credentials are brokered server-side and never enter the agent's machine. Add a GitHub token as the GH_TOKEN secret so the agent can open the pull request.

GitHub

Reads new commits and opens one PR with the doc updates.

Or useGitLabBitbucket
Required
Mintlify

Publishes the docs once a person merges the PR.

Or useGitBookReadMe
Optional
3

Run it once with this prompt

Merge the change request, then start a session with the docs-maintainer agent and send this prompt. Read the pull request before you let the schedule take over.

Prompt

Run one docs sync pass on owner/repo.

  1. Read the checkpoint in memory/docs-sync-log.md and list the commits since then.
  2. For each commit, read the changed code and note what behavior changed.
  3. Search docs/ and every README for text that no longer matches the code.
  4. Update only those sections, in the style the docs already use.
  5. Open one pull request with the commit and the reason for each change. Do not merge it.
  6. Move the checkpoint to the newest commit you read.
4

Let the daily schedule take over

The change request added this trigger to kortix.yaml. From now on the agent runs every day at 06:00, each run in a new session on its own cloud computer. The checkpoint in memory tells each run where the last one stopped. To change the time, edit the cron line, or open Triggers in the workspace.

kortix.yaml
triggers:- slug: daily-docs-sync  name: Daily docs sync  on:    cron: "0 0 6 * * *"  run:    agent: docs-maintainer    prompt: Load the docs-sync skill and run one docs sync pass on owner/repo.
5

Edit only docs, through a pull request

The agent edits only files under the docs path and README files. The rest of the code is read-only to it. When the code itself looks wrong, it logs the problem for a person instead of changing it. A person reviews the pull request and merges it.

6

Review the pull request

Each run ends with one docs pull request, or none when nothing drifted. This is what a run looks like in the session:

Daily docs sync · 06:00
Load the docs-sync skill and run one docs sync pass on owner/repo.
Worked for 5m 09s
github · list commitsgithub · read file × 11github · search codegithub · create branchgithub · open pull request

Read 9 commits since the last checkpoint. 3 changed documented behavior: a renamed env var, a new API endpoint and a removed CLI flag. Updated 4 pages in one pull request, and the checkpoint moved to the newest commit.

Illustrative example. Your commits and pages differ.

The pattern

Connect the repo via a trigger on merge, give the agent scoped connectors into the diff, the codebase, and the docs, encode the writing standard as skills and memory, and gate every change behind a reviewed PR.

Make it do more

Once it works, paste any of these into the same session.

Draft missing pages

When a commit adds a public endpoint or command with no doc page, draft a new page for it in the same pull request.

Check code samples

Run every code sample in the pages you change, and fix the sample when its output no longer matches the text.

Find quiet drift

Every Friday, list the doc pages that have not changed in 6 months but describe code that changed since then.

Guardrails

Giving an agent write access to documentation is a trust question. The relevant controls on Kortix:

  • Isolation. The daily sweep runs in its own isolated sandbox, resuming the same session across runs via a durable checkpoint rather than persisting the raw repo state. The session can read the whole repo to understand a change, and only the docs PR it opens is written back out.
  • Scoped secrets. The GitHub credential is encrypted in the secrets manager, injected into the sandbox at runtime, and scoped to the agents you grant it to.
  • PR-gated. No change reaches a branch anyone reads without a person reviewing the diff and merging it.
  • Everything is code. The agent's persona, skills, and permissions are files in the repo — versioned and changed through a reviewed change request, not a dashboard setting.

The outcome

Docs re-checked against the code that landed since the last run
Daily
Drift caught before it reaches a reader
Same-day
The diff, the codebase, and the docs — in one agent
3 systems

The backlog of "someone should update the README" changes now arrives as small, reviewable PRs within a day of the code landing, with the reasoning written down. The team reviews a diff instead of reconstructing months of drift, and readers stop hitting instructions that are no longer accurate.

The setup relies on four pieces working together: sandbox isolation for the daily session, a secrets manager to broker the GitHub token, a PR gate on every change, and a durable checkpoint that carries the sweep forward run to run.

On this page

  • The problem
  • What we built
  • How it works
  • Make it do more
  • Guardrails
  • The outcome

Run this yourself

Install this exact setup — agent, connectors, schedule, and guardrails — in a guided flow.

More use cases.

  • How we handle GDPR data-subject requests on a deadline

    Legal·July 11, 2026

  • OpenChatly

    How we QA every pull request automatically

    QA·July 5, 2026

  • Slack
    GitHub
    Linear
    OpenChatly

    How we run operations from Slack

    Operations·July 5, 2026

Own your AI.Start today, in our cloud.

Start for free

OpenChatly is the AI workspace for everything. One person directing, agents executing, from goal to finished work.

©2026 OpenChatly AI.沪ICP备2025124785号-5

Resource guide

  • Product overview
  • Skills marketplace

Terms of service

  • User agreement
  • Privacy policy

Contact us