Guides

Set up knowledge for a repo

Let EasyCode scan a repo and map your org's code, so every session can read how the repos fit together before it changes anything.

Last updated November 15, 2026View as Markdown

A session that only sees one folder misses how the org's repos fit together: which service publishes an event, who calls a route, where an env key is read. Knowledge gives every session in your org the whole picture. It works from the code itself, on your team's own machines and GitHub logins.

A module

Knowledge is a module. With it off, a product's Knowledge tab says "Knowledge is off for" your org, and only Overview shows until an admin turns it on.

What it does

There are three parts, and the first two need nothing from you once a repo is in a product.

  • The scan. The desktop app reads each repo of your org's products and builds an index of its code facts: routes, client calls, events published and handled, queues, packages, scripts, env keys and symbols. Only names, paths, line numbers and one-line signatures go to EasyCode, never code bodies, and secret-shaped values are dropped. The scan reads the default branch from git. It never reads your working folder, and nothing is installed, built or run.
  • The checkouts and the map. In an org space, the app keeps a read-only checkout of each repo, at the head of its default branch. Beside them it writes the org map: ORG.md, one line per repo with its products, a summary and its key paths, and the org/*.tsv tables. Every row in a table ends in the repo/path:line it came from.
  • Model-written knowledge. For each product, an admin can have a model propose its conventions and capture its design system. You review the result before it is published.

Before you start

  • The repo is linked to a product. On a product with none, the tab says "Link a repo in the product settings to set up its knowledge"; an admin or a maintainer does that. See Products and repos.
  • The GitHub App can see the repo.
  • Someone on the team runs the desktop app and can read the repo on GitHub.

Let your computer scan

The scan runs on members' computers, through their own git login. In the desktop app, open Settings, then Desktop, and turn on Scan repos on this computer: "When you can read a picked repo on GitHub, this computer reads it and builds its index for the org." It's on by default (knowledge.scan). A computer scans at most three repos at a time, and a repo is scanned by one computer at a time.

When a scan fails for the repo's own sake, such as a refused clone, EasyCode records the error on the repo.

What a session gets

When a session starts in an org space, its instructions carry a short "Org code" rule: every repo is checked out read-only, and ORG.md maps the products and repos. Before changing files in a repo, the session reads that repo's rows in the tables.

The map goes in whole while it fits. In a larger org the session gets its own product in full and one line for each other repo, or one line per repo. The session's chip shows which: "Org map: full", "Org map: this product in full, others one line" or "Org map: one line a repo". ORG.md itself always holds the whole map.

The tables are plain files a harness can grep:

TableWhat's in it
org/repos.tsvEach repo, its indexed commit and default branch
org/products.tsvWhich repos make up each product, and their roles
org/routes.tsvHTTP routes, by method
org/events.tsvEvents and topics, who publishes and who handles them
org/env.tsvWhere each env key is read
org/deps.tsvWhich repo depends on which, and how
org/stack.tsv, org/components.tsv, org/commands.tsvThe stack, the components and the commands each repo runs
org/agent-files.tsvEach repo's own harness files, such as CLAUDE.md
org/owners.tsv, org/submodules.tsv, org/design.tsvCode owners, submodules and design systems, when there are any

The harness reads the checkouts and the map with its own file tools, under its own permissions. There is no separate search tool to call.

Propose conventions and capture the design system

On a product, open the Knowledge tab. "Repos are scanned on their own. These two are written by a model on the assignee's computer, and you review the result before it is published."

Start the task

Press Propose conventions (the product's rules and standards, each with its evidence in the code) or Capture the design system (its tokens and components, read from its repos). Only admins and the product's maintainers start these. Assign the task to a member who can see the product and read its repos on GitHub.

Run it

The assignee opens the task and presses Start run. It runs in Claude Code or Codex on their machine, and shows to the team as an org session titled with the task. Retry resumes a failed stage on the same machine.

Review and publish

An approver opens the Result for approval, with its sections, evidence and provenance, and presses Approve and publish or Send back with what to change. A published result becomes a library asset that sessions load.

To have your computer take tasks assigned to you on its own, turn on Run my knowledge tasks in the background in the desktop app's Desktop settings (knowledge.autoRefresh). Org admins set the review rule and the model per harness under Settings, Knowledge.

Your org admin can stop knowledge runs with the knowledge switch. Setup and review still work.

Something wrong or missing? Suggest a change

On this page